NIFI-1210: Makes various changes to the User Guide for the 0.4.0 version release.

Reviewed and amended (see ticket for details) by Tony Kurc (tkurc@apache.org)

nifi-docs/src/main/asciidoc/user-guide.adoc

@@ -40,7 +40,6 @@ use a supported web browser to view the User Interface. Supported web browsers i
 Note that there is a known issue in Internet Explorer (IE) 10 and 11 that can cause problems when moving items on the NiFi graph. If you encounter this problem, we suggest using a browser other than IE. This known issue is described here: https://connect.microsoft.com/IE/Feedback/Details/1050422.
 
 
-
 [template="glossary", id="terminology"]
 Terminology
 -----------
@@ -100,6 +99,11 @@ Terminology
 	As a result, several components may be combined together to make a larger building block from which to create a dataflow.
 	These templates can also be exported as XML and imported into another NiFi instance, allowing these building blocks to be shared.
 
+*flow.xml.gz*: Everything the DFM puts onto the NiFi User Interface canvas is written, in real time, to one file called the flow.xml.gz. This file is located in the nifi/conf directory.
+	Any change made on the canvas is automatically saved to this file, without the user needing to click a "save" button. In addition, the user may create a back-up copy of this file at any time
+	by selecting the Controller Settings button in the far-right section of the tool bar and clicking "Back-up flow" on the General tab. By default, this action saves a copy of the current flow in the nifi/conf/archive directory.
+	See <<Controller_Settings>> for a description of where the "Back-up flow" button may be found. (Note that in a NiFi Cluster, the NiFi Cluster Manager's copy of this file is named flow.tar, whereas this file is still named flow.xml.gz on the nodes.)
+
 
 [[User_Interface]]
 NiFi User Interface
@@ -191,7 +195,26 @@ image::add-processor-with-tag-cloud.png["Add Processor with Tag Cloud"]
 Clicking the `Add` button or double-clicking on a Processor Type will add the selected Processor to the canvas at the
 location that it was dropped.
 
-*Note*: For any component added to the graph, it is possible to select it with the mouse and move it anywhere on the graph. Also, it is possible to select multiple items at once by either holding down the Shift key and selecting each item or by holding down the Shift key and dragging a selection box around the desired components. 
+*Note*: For any component added to the canvas, it is possible to select it with the mouse and move it anywhere on the graph. Also, it is possible to select multiple items at once by either holding down the Shift key and selecting each item or by holding down the Shift key and dragging a selection box around the desired components. 
+
+Once a Processor has been dragged onto the canvas, the user may interact with it by right-clicking on the Processor and selecting an option from
+context menu. 
+
+image::nifi-processor-menu.png["Processor Menu", width=300]
+
+The following options are available:
+
+- *Configure*: This option allows the user to establish or change the configuration of the Processor. (See <<Configuring_a_Processor>>.)
+- *Start* or *Stop*: This option allows the user to start or stop a Processor; the option will be either Start or Stop, depending on the current state of the Processor.
+- *Stats*: This option opens a graphical representation of the Processor's statistical information over time.
+- *Upstream connections*: This option allows the user to see and "jump to" upstream connections that are coming into the Processor. This is particularly useful when processors connect into and out of other Process Groups.
+- *Downstream connections*: This option allows the user to see and "jump to" downstream connections that are going out of the Processor. This is particularly useful when processors connect into and out of other Process Groups.
+- *Usage*: This option takes the user to the Processor's usage documentation.
+- *Change color*: This option allows the user to change the color of the Processor, which can make the visual management of large flows easier.
+- *Center in view*: This option centers the view of the canvas on the given Processor.
+- *Copy* or *Paste*: This option places a copy of the selected Processor on the clipboard, so that it may be pasted elsewhere on the canvas.
+- *Delete*: This option allows the DFM to delete a Processor from the canvas.
+
 
 
 [[input_port]]
@@ -228,6 +251,24 @@ image:iconProcessGroup.png["Process Group", width=32]
 and maintain. When a Process Group is dragged onto the canvas, the DFM is prompted to name the Process Group. All Process
 Groups within the same parent group must have unique names. The Process Group will then be nested within that parent group.
 
+Once a Process Group has been dragged onto the canvas, the user may interact with it by right-clicking on the Process Group and selecting an option from
+context menu. 
+
+image::nifi-process-group-menu.png["Process Group Menu", width=300]
+
+The following options are available:
+
+- *Configure*: This option allows the user to establish or change the configuration of the Process Group.
+- *Enter group*: This option allows the user to enter the Process Group. It is also possible to double-click on the Process Group to enter it.
+- *Start*: This option allows the user to start a Process Group.
+- *Stop*: This option allows the user to stop a Process Group.
+- *Stats*: This option opens a graphical representation of the Process Group's statistical information over time.
+- *Upstream connections*: This option allows the user to see and "jump to" upstream connections that are coming into the Process Group.
+- *Downstream connections*: This option allows the user to see and "jump to" downstream connections that are going out of the Process Group.
+- *Center in view*: This option centers the view of the canvas on the given Process Group.
+- *Copy* or *Paste*: This option places a copy of the selected Process Group on the clipboard, so that it may be pasted elsewhere on the canvas.
+- *Delete*: This option allows the DFM to delete a Process Group.
+
 
 
 [[remote_process_group]]
@@ -241,6 +282,27 @@ how busy each node is. This information is then used to load balance the data th
 then interrogated periodically to determine information about any nodes that are dropped from or added to the cluster and to 
 recalculate the load balancing based on each node's load. For more information, see the section on <<site-to-site,Site-to-Site>>.
 
+Once a Remote Process Group has been dragged onto the canvas, the user may interact with it by right-clicking on the Remote Process Group and selecting an option from
+context menu. 
+
+image::nifi-rpg-menu.png["Remote Process Group Menu", width=300]
+
+The following options are available:
+
+- *Configure*: This option allows the user to establish or change the configuration of the Remote Process Group.
+- *Remote Ports*: This option allows the user to see input ports and/or output ports that exist on the remote instance of NiFi that the Remote Process Group is connected to. Note that if the site-to-site configuration is secure, only the ports that the connecting NiFi has been given accessed to will be visible.
+- *Enable transmission*: Makes the transmission of data between NiFi instances active. (See <<Remote_Group_Transmission>> )
+- *Disable transmission*: Disables the transmission of data between NiFi instances.
+- *Stats*: This option opens a graphical representation of the Remote Process Group's statistical information over time.
+- *Upstream connections*: This option allows the user to see and "jump to" upstream connections that are coming into the Remote Process Group.
+- *Downstream connections*: This option allows the user to see and "jump to" downstream connections that are going out of the Remote Process Group.
+- *Refresh*: This option refreshes the view of the status of the remote NiFi instance.
+- *Go to*: This option opens a view of the remote NiFi instance in a new tab of the browser. Note that if the site-to-site configuration is secure, the user must have access to the remote NiFi instance in order to view it.
+- *Center in view*: This option centers the view of the canvas on the given Remote Process Group.
+- *Copy* or *Paste*: This option places a copy of the selected Process Group on the clipboard, so that it may be pasted elsewhere on the canvas.
+- *Delete*: This option allows the DFM to delete a Remote Process Group from the canvas.
+
+
 
 [[funnel]]
 image:iconFunnel.png["Funnel", width=32]
@@ -276,11 +338,10 @@ choosing `Configure...`
 
 
 
-
+[[Configuring_a_Processor]]
 === Configuring a Processor
 
-Once a Processor has been dragged onto the Canvas, it is ready to configure. This is done by right-clicking on the
-Processor and clicking the `Configure...` option from the context menu. The configuration dialog is opened with four
+To configure a processor, right-click on the Processor and select the `Configure...` option from the context menu. The configuration dialog is opened with four
 different tabs, each of which is discussed below. Once you have finished configuring the Processor, you can apply
 the changes by clicking the `Apply` button or cancel all changes by clicking the `Cancel` button.
 
@@ -460,8 +521,12 @@ for all the Processors that are available. Clicking on the desired Processor in
 
 While DFMs have the ability to create Controller Services from the Configure Processor window, there is also a central place within the User Interface for adding and configuring both Controller Services and Reporting Tasks. To get there, click on the Controller Settings button in the Management section of the toolbar.
 
+[[Controller_Settings]]
+==== Controller Settings
+
 image:controller-settings-button.png["Controller Settings Button", width=200]
 
+
 The Controller Settings window has three tabs across the top: General, Controller Services, and Reporting Tasks. The General tab is for settings that pertain to general information about the NiFi instance. For example, here, the DFM can provide a unique name for the overall dataflow, as well as comments that describe the flow. Be aware that this information is visible to any other NiFi instance that connects remotely to this instance (using Remote Process Groups, a.k.a., Site-to-Site).
 
 The General tab also provides settings for the overall maximum thread counts of the instance, as well as the ability to click "Back-up flow" to create a backup copy of the current flow, which is saved by default in the /conf/archive directory.
@@ -472,7 +537,7 @@ To the right of the General tab is the Controller Services tab. From this tab, t
 
 image:controller-services-tab.png["Controller Services Tab", width=900]
 
-The Add Controller Service window opens. This window is similar to the Add Processor window. It provides a list of the available Controller Services on the right and a tag cloud, showing the most common catagory tags used for Controller Services, on the left. The DFM may click any tag in the tag cloud in order to narrow down the list of Controller Services to those that fit the categories desired. The DFM may also use the Filter field at the top of the window to search for the desired Contoller Service. Upon selecting a Controller Service from the list, the DFM can see a description of the the service below. Select the desired controller service and click Add, or simply double-click the name of the service to add it.
+The Add Controller Service window opens. This window is similar to the Add Processor window. It provides a list of the available Controller Services on the right and a tag cloud, showing the most common category tags used for Controller Services, on the left. The DFM may click any tag in the tag cloud in order to narrow down the list of Controller Services to those that fit the categories desired. The DFM may also use the Filter field at the top of the window to search for the desired Controller Service. Upon selecting a Controller Service from the list, the DFM can see a description of the the service below. Select the desired controller service and click Add, or simply double-click the name of the service to add it.
 
 image:add-controller-service-window.png["Add Controller Service Window", width=700]
 
@@ -513,7 +578,7 @@ The Comments tab is just an open-text field, where the DFM may include comments
 When you want to run the Reporting Task, click the Start button in the far-right column of the Reporting Tasks tab.
 
 
-
+[[Connecting_Components]]
 === Connecting Components
 
 Once processors and other components have been added to the graph and configured, the next step is to connect them
@@ -581,10 +646,28 @@ The following prioritizers are available:
 - *FirstInFirstOutPrioritizer*: Given two FlowFiles, the on that reached the connection first will be processed first.
 - *NewestFlowFileFirstPrioritizer*: Given two FlowFiles, the one that is newest in the dataflow will be processed first.
 - *OldestFlowFileFirstPrioritizer*: Given two FlowFiles, the on that is oldest in the dataflow will be processed first. This is the default scheme that is used if no prioritizers are selected.
-- *PriorityAttributePrioritizer*: Given two FlowFiles that both have a "priority" attribute, the one that has the highest priority value will be prprocessed first. Note that an UpdateAttribute processor should be used to add the "priority" attribute to the FlowFiles before they reach a connection that has this prioritizer set. Values for the "priority" attribute may be alphanumeric, where "a" is a higher priority than "z", and "1" is a higher priority than "9", for example.
+- *PriorityAttributePrioritizer*: Given two FlowFiles that both have a "priority" attribute, the one that has the highest priority value will be processed first. Note that an UpdateAttribute processor should be used to add the "priority" attribute to the FlowFiles before they reach a connection that has this prioritizer set. Values for the "priority" attribute may be alphanumeric, where "a" is a higher priority than "z", and "1" is a higher priority than "9", for example.
 
 *Note*: After a connection has been drawn between two components, the connection's configuration may be changed, and the connection may be moved to a new destination; however, the processors on either side of the connection must be stopped before a configuration or destination change may be made.
 
+image:nifi-connection.png["Connection", width=300]
+
+
+To change a connection's configuration or interact with the connection in other ways, right-click on the connection to open the connection context menu.
+
+image:nifi-connection-menu.png["Connection Menu", width=200]
+
+The following options are available:
+
+- *Configure*: This option allows the user to change the configuration of the connection.
+- *Stats*: This option opens a graphical representation of the connection's statistical information over time.
+- *Bring to front*: This option brings the connection to the front of the canvas if something else (such as another connection) is overlapping it.
+- *Go to source*: This option can be useful if there is a long distance between the connection's source and destination components on the canvas. By clicking this option, the view of the canvas will jump to the source of the connection.
+- *Go to destination*: Similar to the "Go to source" option, this option changes the view to the destination component on the canvas and can be useful if there is a long distance between two connected components.
+- *Empty queue*: This option allows the DFM to clear the queue of FlowFiles that may be waiting to be processed. This option can be especially useful during testing, when the DFM is not concerned about deleting data from the queue. When this option is selected, users must confirm that they want to delete the data in the queue.
+- *Delete*: This option allows the DFM to delete a connection between two components. Note that the components on both sides of the connection must be stopped and the connection must be empty before it can be deleted.
+
+
 === Processor Validation
 
 Before trying to start a Processor, it's important to make sure that the Processor's configuration is valid.
@@ -717,7 +800,7 @@ Now see the following section on how to start and stop the dataflow. When the da
 
 
 
-== Command and Control of DataFlow
+== Command and Control of the DataFlow
 
 When a component is added to the NiFi canvas, it is in the Stopped state. In order to cause the component to
 be triggered, the component must be started. Once started, the component can be stopped at any time. From a
@@ -802,7 +885,7 @@ Only Ports and Processors can be enabled and disabled.
 === Remote Process Group Transmission
 
 Remote Process Groups provide a mechanism for sending data to or retrieving data from a remote instance
-of NiFi. When a Remote Process Group (RPG) is added to the canvas, it is added with the Transmision Disabled,
+of NiFi. When a Remote Process Group (RPG) is added to the canvas, it is added with the Transmission Disabled,
 as indicated by the icon (
 image:iconTransmissionInactive.png["Transmission Disabled"]
 ) in the top-left corner. When Transmission is Disabled, it can be enabled by right-clicking on the
@@ -1118,7 +1201,7 @@ image:iconNotSecure.png["Not Secure"]
 			will be counted.
 			
 	** image:iconTransmissionActive.png["Transmitting"]
-		*Transmitting Ports*: The number of Output Ports from whcih this NiFi is connected and currently configured
+		*Transmitting Ports*: The number of Output Ports from which this NiFi is connected and currently configured
 			to pull data from. Ports can be turned on and off by enabling and disabling transmission on the Remote Process
 			Group (see <<Remote_Group_Transmission>>) or via the <<Remote_Port_Configuration>> dialog.