nifi-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From scottyas...@apache.org
Subject nifi git commit: NIFI-4462 Update User and Admin Guide with Variables window UI documentation and screenshots
Date Mon, 09 Oct 2017 19:46:33 GMT
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 <scottyaslan@gmail.com>


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 <andrewlim.apache@gmail.com>
Authored: Mon Oct 9 15:13:52 2017 -0400
Committer: Scott Aslan <scottyaslan@gmail.com>
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


Mime
View raw message