Repository: nifi Updated Branches: refs/heads/master b5e1fa7ff -> b2c68d2b2
NIFI-4462 Update User and Admin Guide with Variables window UI documentation and screenshots This closes #2202 Signed-off-by: Scott Aslan <[email protected]> Project: http://git-wip-us.apache.org/repos/asf/nifi/repo Commit: http://git-wip-us.apache.org/repos/asf/nifi/commit/b2c68d2b Tree: http://git-wip-us.apache.org/repos/asf/nifi/tree/b2c68d2b Diff: http://git-wip-us.apache.org/repos/asf/nifi/diff/b2c68d2b Branch: refs/heads/master Commit: b2c68d2b2930b9f7befe35a38681650f6cde893c Parents: b5e1fa7 Author: Andrew Lim <[email protected]> Authored: Mon Oct 9 15:13:52 2017 -0400 Committer: Scott Aslan <[email protected]> Committed: Mon Oct 9 15:21:42 2017 -0400 ---------------------------------------------------------------------- .../src/main/asciidoc/administration-guide.adoc | 12 +- .../main/asciidoc/images/new_variable-apply.png | Bin 0 -> 69277 bytes .../src/main/asciidoc/images/variable-name.png | Bin 0 -> 49827 bytes .../asciidoc/images/variable-overridden.png | Bin 0 -> 60928 bytes .../images/variable-putfile-property.png | Bin 0 -> 67481 bytes ...riable-unauthorized-ref-processor-canvas.png | Bin 0 -> 246129 bytes .../src/main/asciidoc/images/variable-value.png | Bin 0 -> 56107 bytes .../variable_insufficient-permissions.png | Bin 0 -> 161730 bytes .../images/variable_nav-controller_services.png | Bin 0 -> 81906 bytes .../asciidoc/images/variable_window-goto.png | Bin 0 -> 77419 bytes .../asciidoc/images/variable_window-rpg.png | Bin 0 -> 56898 bytes .../images/variables-context_menu-pg.png | Bin 0 -> 227053 bytes .../images/variables-context_menu-rpg.png | Bin 0 -> 216948 bytes .../variables-window_controller-services.png | Bin 0 -> 64086 bytes .../images/variables-window_unauthorized.png | Bin 0 -> 61600 bytes .../asciidoc/images/variables_window_empty.png | Bin 0 -> 42741 bytes nifi-docs/src/main/asciidoc/user-guide.adoc | 115 ++++++++++++++++--- 17 files changed, 111 insertions(+), 16 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/nifi/blob/b2c68d2b/nifi-docs/src/main/asciidoc/administration-guide.adoc ---------------------------------------------------------------------- diff --git a/nifi-docs/src/main/asciidoc/administration-guide.adoc b/nifi-docs/src/main/asciidoc/administration-guide.adoc index 540e817..b0e68d5 100644 --- a/nifi-docs/src/main/asciidoc/administration-guide.adoc +++ b/nifi-docs/src/main/asciidoc/administration-guide.adoc @@ -3150,11 +3150,19 @@ To configure custom properties for use with NiFiâs Expression Language: * Create the custom property. Ensure that: ** Each custom property contains a distinct property value, so that it is not overridden by existing environment properties, system properties, or FlowFile attributes. ** Each node in a clustered environment is configured with the same custom properties. -* Update the 'nifi.properties' file with the location of the custom property files. +* Update `nifi.variable.registry.properties` with the location of the custom property file(s): |==== |*Property*|*Description* |nifi.variable.registry.properties|This is a comma-separated list of file location paths for one or more custom property files. |==== -NOTE: *For Upgrading* - Take care when configuring the properties above that are marked with an asterisk (*). To make the upgrade process easier, it is advisable to change the default configurations to locations outside the main root installation directory. In this way, these items can remain in their configured location through an upgrade, and NiFi can find all the repositories and configuration files and pick up where it left off as soon as the old version is stopped and the new version is started. Furthermore, the administrator may reuse this _nifi.properties_ file and any other configuration files without having to re-configure them each time an upgrade takes place. As previously noted, it is important to check for any changes in the _nifi.properties_ file of the new version when upgrading and make sure they are reflected in the _nifi.properties_ file you use. +* Restart your NiFi instance(s) for the updates to be picked up. + +Custom properties can also be configured in the NiFi UI. See the <<user-guide.adoc#Variables_Window,Variables Window>> section in the User Guide for more information. + +[WARNING] +.Upgrading +============ +Take care when configuring the properties above that are marked with an asterisk (*). To make the upgrade process easier, it is advisable to change the default configurations to locations outside the main root installation directory. In this way, these items can remain in their configured location through an upgrade, and NiFi can find all the repositories and configuration files and pick up where it left off as soon as the old version is stopped and the new version is started. Furthermore, the administrator may reuse this _nifi.properties_ file and any other configuration files without having to re-configure them each time an upgrade takes place. As previously noted, it is important to check for any changes in the _nifi.properties_ file of the new version when upgrading and make sure they are reflected in the _nifi.properties_ file you use. +============ http://git-wip-us.apache.org/repos/asf/nifi/blob/b2c68d2b/nifi-docs/src/main/asciidoc/images/new_variable-apply.png ---------------------------------------------------------------------- diff --git a/nifi-docs/src/main/asciidoc/images/new_variable-apply.png b/nifi-docs/src/main/asciidoc/images/new_variable-apply.png new file mode 100644 index 0000000..5e0f386 Binary files /dev/null and b/nifi-docs/src/main/asciidoc/images/new_variable-apply.png differ http://git-wip-us.apache.org/repos/asf/nifi/blob/b2c68d2b/nifi-docs/src/main/asciidoc/images/variable-name.png ---------------------------------------------------------------------- diff --git a/nifi-docs/src/main/asciidoc/images/variable-name.png b/nifi-docs/src/main/asciidoc/images/variable-name.png new file mode 100644 index 0000000..3e969c9 Binary files /dev/null and b/nifi-docs/src/main/asciidoc/images/variable-name.png differ http://git-wip-us.apache.org/repos/asf/nifi/blob/b2c68d2b/nifi-docs/src/main/asciidoc/images/variable-overridden.png ---------------------------------------------------------------------- diff --git a/nifi-docs/src/main/asciidoc/images/variable-overridden.png b/nifi-docs/src/main/asciidoc/images/variable-overridden.png new file mode 100644 index 0000000..ec9f76e Binary files /dev/null and b/nifi-docs/src/main/asciidoc/images/variable-overridden.png differ http://git-wip-us.apache.org/repos/asf/nifi/blob/b2c68d2b/nifi-docs/src/main/asciidoc/images/variable-putfile-property.png ---------------------------------------------------------------------- diff --git a/nifi-docs/src/main/asciidoc/images/variable-putfile-property.png b/nifi-docs/src/main/asciidoc/images/variable-putfile-property.png new file mode 100644 index 0000000..5bb15ac Binary files /dev/null and b/nifi-docs/src/main/asciidoc/images/variable-putfile-property.png differ http://git-wip-us.apache.org/repos/asf/nifi/blob/b2c68d2b/nifi-docs/src/main/asciidoc/images/variable-unauthorized-ref-processor-canvas.png ---------------------------------------------------------------------- diff --git a/nifi-docs/src/main/asciidoc/images/variable-unauthorized-ref-processor-canvas.png b/nifi-docs/src/main/asciidoc/images/variable-unauthorized-ref-processor-canvas.png new file mode 100644 index 0000000..8d21cf8 Binary files /dev/null and b/nifi-docs/src/main/asciidoc/images/variable-unauthorized-ref-processor-canvas.png differ http://git-wip-us.apache.org/repos/asf/nifi/blob/b2c68d2b/nifi-docs/src/main/asciidoc/images/variable-value.png ---------------------------------------------------------------------- diff --git a/nifi-docs/src/main/asciidoc/images/variable-value.png b/nifi-docs/src/main/asciidoc/images/variable-value.png new file mode 100644 index 0000000..0bf859e Binary files /dev/null and b/nifi-docs/src/main/asciidoc/images/variable-value.png differ http://git-wip-us.apache.org/repos/asf/nifi/blob/b2c68d2b/nifi-docs/src/main/asciidoc/images/variable_insufficient-permissions.png ---------------------------------------------------------------------- diff --git a/nifi-docs/src/main/asciidoc/images/variable_insufficient-permissions.png b/nifi-docs/src/main/asciidoc/images/variable_insufficient-permissions.png new file mode 100644 index 0000000..5563b66 Binary files /dev/null and b/nifi-docs/src/main/asciidoc/images/variable_insufficient-permissions.png differ http://git-wip-us.apache.org/repos/asf/nifi/blob/b2c68d2b/nifi-docs/src/main/asciidoc/images/variable_nav-controller_services.png ---------------------------------------------------------------------- diff --git a/nifi-docs/src/main/asciidoc/images/variable_nav-controller_services.png b/nifi-docs/src/main/asciidoc/images/variable_nav-controller_services.png new file mode 100644 index 0000000..cf2a5d4 Binary files /dev/null and b/nifi-docs/src/main/asciidoc/images/variable_nav-controller_services.png differ http://git-wip-us.apache.org/repos/asf/nifi/blob/b2c68d2b/nifi-docs/src/main/asciidoc/images/variable_window-goto.png ---------------------------------------------------------------------- diff --git a/nifi-docs/src/main/asciidoc/images/variable_window-goto.png b/nifi-docs/src/main/asciidoc/images/variable_window-goto.png new file mode 100644 index 0000000..7580045 Binary files /dev/null and b/nifi-docs/src/main/asciidoc/images/variable_window-goto.png differ http://git-wip-us.apache.org/repos/asf/nifi/blob/b2c68d2b/nifi-docs/src/main/asciidoc/images/variable_window-rpg.png ---------------------------------------------------------------------- diff --git a/nifi-docs/src/main/asciidoc/images/variable_window-rpg.png b/nifi-docs/src/main/asciidoc/images/variable_window-rpg.png new file mode 100644 index 0000000..d1c39a4 Binary files /dev/null and b/nifi-docs/src/main/asciidoc/images/variable_window-rpg.png differ http://git-wip-us.apache.org/repos/asf/nifi/blob/b2c68d2b/nifi-docs/src/main/asciidoc/images/variables-context_menu-pg.png ---------------------------------------------------------------------- diff --git a/nifi-docs/src/main/asciidoc/images/variables-context_menu-pg.png b/nifi-docs/src/main/asciidoc/images/variables-context_menu-pg.png new file mode 100644 index 0000000..14fb84c Binary files /dev/null and b/nifi-docs/src/main/asciidoc/images/variables-context_menu-pg.png differ http://git-wip-us.apache.org/repos/asf/nifi/blob/b2c68d2b/nifi-docs/src/main/asciidoc/images/variables-context_menu-rpg.png ---------------------------------------------------------------------- diff --git a/nifi-docs/src/main/asciidoc/images/variables-context_menu-rpg.png b/nifi-docs/src/main/asciidoc/images/variables-context_menu-rpg.png new file mode 100644 index 0000000..27a88ea Binary files /dev/null and b/nifi-docs/src/main/asciidoc/images/variables-context_menu-rpg.png differ http://git-wip-us.apache.org/repos/asf/nifi/blob/b2c68d2b/nifi-docs/src/main/asciidoc/images/variables-window_controller-services.png ---------------------------------------------------------------------- diff --git a/nifi-docs/src/main/asciidoc/images/variables-window_controller-services.png b/nifi-docs/src/main/asciidoc/images/variables-window_controller-services.png new file mode 100644 index 0000000..26659ea Binary files /dev/null and b/nifi-docs/src/main/asciidoc/images/variables-window_controller-services.png differ http://git-wip-us.apache.org/repos/asf/nifi/blob/b2c68d2b/nifi-docs/src/main/asciidoc/images/variables-window_unauthorized.png ---------------------------------------------------------------------- diff --git a/nifi-docs/src/main/asciidoc/images/variables-window_unauthorized.png b/nifi-docs/src/main/asciidoc/images/variables-window_unauthorized.png new file mode 100644 index 0000000..98a1f1f Binary files /dev/null and b/nifi-docs/src/main/asciidoc/images/variables-window_unauthorized.png differ http://git-wip-us.apache.org/repos/asf/nifi/blob/b2c68d2b/nifi-docs/src/main/asciidoc/images/variables_window_empty.png ---------------------------------------------------------------------- diff --git a/nifi-docs/src/main/asciidoc/images/variables_window_empty.png b/nifi-docs/src/main/asciidoc/images/variables_window_empty.png new file mode 100644 index 0000000..e1c938e Binary files /dev/null and b/nifi-docs/src/main/asciidoc/images/variables_window_empty.png differ http://git-wip-us.apache.org/repos/asf/nifi/blob/b2c68d2b/nifi-docs/src/main/asciidoc/user-guide.adoc ---------------------------------------------------------------------- diff --git a/nifi-docs/src/main/asciidoc/user-guide.adoc b/nifi-docs/src/main/asciidoc/user-guide.adoc index 184f3bb..f2c520f 100644 --- a/nifi-docs/src/main/asciidoc/user-guide.adoc +++ b/nifi-docs/src/main/asciidoc/user-guide.adoc @@ -707,27 +707,19 @@ image::comments-tab.png["Comments Tab"] === Additional Help -You can access additional documentation about each Processor's usage by right-clicking -on the Processor and selecting `Usage' from the context menu. Alternatively, select Help from the Global Menu in the top-right -corner of the UI to display a Help page with all of the documentation, including usage documentation -for all the Processors that are available. Click on the desired Processor to view usage documentation. +You can access additional documentation about each Processor's usage by right-clicking on the Processor and selecting `Usage' from the context menu. Alternatively, select Help from the Global Menu in the top-right corner of the UI to display a Help page with all of the documentation, including usage documentation for all the Processors that are available. Click on the desired Processor to view usage documentation. [[Using_Custom_Properties]] === Using Custom Properties with Expression Language -You can use NiFi Expression Language to reference FlowFile attributes, compare them to other values, -and manipulate their values when you are creating and configuring dataflows. +You can use NiFi Expression Language to reference FlowFile attributes, compare them to other values, and manipulate their values when you are creating and configuring dataflows. For more information on Expression Language, see the link:expression-language-guide.html[Expression Language Guide]. In addition to using FlowFile attributes, system properties, and environment properties within Express Language, you can also define custom properties for Expression Language use. Defining custom properties gives you more flexibility in handling and processing dataflows. You can also create custom properties for connection, server, and service properties, for easier dataflow configuration. -To create custom properties for use with Expression Language, identify one or more sets of key/value -pairs, and give them to your system administrator. - NiFi properties have resolution precedence of which you should be aware when creating custom properties:⨠- * Processor-specific attributes * FlowFile properties⨠* FlowFile attributes⨠@@ -738,11 +730,106 @@ NiFi properties have resolution precedence of which you should be aware when cre When you are creating custom properties, ensure that each custom property contains a distinct property value, so that it is not overridden by existing environment properties, system properties, or FlowFile attributes. -Once you have added the new custom properties, ensure that you have updated the nifi.variable.registry.properties -field in the nifi.properties file, with the custom properties location. -For more information on Expression Language, see the link:expression-language-guide.html[Expression Lanuaguage Guide]. -For information on how to define custom properties, see the link:administration-guide.html[System Administratorâs Guide]. +There are two ways to use and manage custom properties: + +* In the NiFi UI via the Variables window +* Referencing custom properties via 'nifi.properties' + +[[Variables_Window]] +==== Variables Window + +Variables can be created and configured within the NiFi UI. The variables can be used in any field that supports Expression Language. NiFi automatically picks up new or modified variables created in the UI. + +To access the Variables window, right-click on the canvas with nothing selected: + +image::variables-context_menu-rpg.png["Variables in Context Menu for RPG"] + +Select "Variables" from the Context Menu: + +image::variables_window_empty.png["Empty Variables Window"] + +"Variables" is also available in the right-click Context Menu when a process group is selected: + +image::variables-context_menu-pg.png["Variables in Context Menu for PG"] + +===== Creating a Variable + +In the Variables window, click the "+" button to create a new variable. Add a name: + +image::variable-name.png["Variable Name Creation"] + +and a value: + +image::variable-value.png["Variable Value Creation"] + +Select "Apply": + +image::new_variable-apply.png["New Variable Applied"] + +Steps to update the variable are performed (Identifying components affected, Stopping affected Processors, etc.). For example, the Referencing Processors section now lists the "PutFile-Root" processor. Selecting the name of the processor in the list will navigate to that processor on the canvas. Looking at the properties of the processor, `${putfile_dir}` is referenced by the Directory property: + +image::variable-putfile-property.png["Processor Property Using Variable"] + +===== Variable Scope + +Variables are scoped by the Process Group they are defined in and are available to any Processor defined at that level and below (i.e. any descendant Processors). + +Variables in a descendant group override the value in a parent group. More specifically, if a variable `x` is declared at the root group and also declared inside a process group, components inside the process group will use the value of `x` defined in the process group. + +For example, in addition to the `putfile_dir` variable that exists at the root process group, assume another `putfile_dir` variable was created within Process Group A. If one of the components within Process Group A references `putfile_dir`, both variables will be listed, but the `putfile_dir` from the root group will have a strikethrough indicating that is is being overridden: + +image::variable-overridden.png["Variable Overridden"] + +A variable can only be modified for the process group it was created in, which is listed at the top of the Variables window. To modify a variable defined in a different process group, select the "arrow" icon in that variable's row: + +image::variable_window-goto.png["Variable Go To"] + +which will navigate to the Variables window for that process group: + +image::variable_window-rpg.png["Variables Window for RPG"] + +===== Variable Permissions + +Variable permissions are based solely on the privileges configured on the corresponding Process Group. + +For example, if a user does not have access to View a process group, the Variables window can not be viewed for that process group: + +image::variable_insufficient-permissions.png["Insufficient Permissions to View Variables"] + +If a user has access to View a process group but does not have access to Modify the process group, the variables can be viewed but not modified. + +For information on how to manage privileges on components, see the <<administration-guide.adoc#access-policies,Access Policies>> section in the System Administrator's Guide. + +===== Referencing Controller Services + +In addition to Referencing Processors, the Variables window also displays Referencing Controller Services: + +image::variables-window_controller-services.png["Referencing Controller Services"] + +Selecting the name of the controller service will navigate to that controller service in the Configuration window: + +image::variable_nav-controller_services.png["Controller Service Using Variable"] + +===== Unauthorized Referencing Components + +When View or Modify privileges are not given to a component that references a variable, the UUID of the component will be displayed in the Variables window: + +image::variables-window_unauthorized.png["Unauthorized Referencing Components"] + +In the above example, the variable `property1` is referenced by a processor that "user1" is not able to view: + +image::variable-unauthorized-ref-processor-canvas.png["Unauthorized Referencing Processor"] + +==== Referencing Custom Properties via nifi.properties +Identify one or more sets of key/value pairs, and give them to your system administrator. + +Once the new custom properties have been added, ensure that the `nifi.variable.registry.properties` +field in the 'nifi.properties' file is updated with the custom properties location. + +NOTE: NiFi must be restarted for these updates to be picked up. + +For more information, see the <<administration-guide.adoc#custom_properties,Custom Properties>> section in the System Administrator's Guide. [[Controller_Services]] === Controller Services
