From 68ab8c23be6e363935743bfcc00846c634c66039 Mon Sep 17 00:00:00 2001
From: Sandra McCann <samccann@redhat.com>
Date: Thu, 23 Jan 2020 19:02:16 -0500
Subject: [PATCH] Network prompts (#66584)

* add network prompt examples and module examples

* Update docs/docsite/rst/network/user_guide/network_working_with_command_output.rst

Co-Authored-By: Nathaniel Case <this.is@nathanielca.se>
---
 .../network_working_with_command_output.rst   | 65 +++++++++++++++++--
 .../modules/network/ios/ios_command.py        |  1 +
 .../modules/network/nxos/nxos_command.py      |  9 +++
 3 files changed, 71 insertions(+), 4 deletions(-)

diff --git a/docs/docsite/rst/network/user_guide/network_working_with_command_output.rst b/docs/docsite/rst/network/user_guide/network_working_with_command_output.rst
index d486e9ddf8d..d046334c827 100644
--- a/docs/docsite/rst/network/user_guide/network_working_with_command_output.rst
+++ b/docs/docsite/rst/network/user_guide/network_working_with_command_output.rst
@@ -1,10 +1,13 @@
 .. _networking_working_with_command_output:
 
-**********************************************
-Working with Command Output in Network Modules
-**********************************************
+**********************************************************
+Working with command output and prompts in network modules
+**********************************************************
 
-Conditionals in Networking Modules
+.. contents::
+  :local:
+
+Conditionals in networking modules
 ===================================
 
 Ansible allows you to use conditionals to control the flow of your playbooks. Ansible networking command modules use the following unique conditional statements.
@@ -63,3 +66,57 @@ The ``wait_for`` argument must always start with result and then the
 command index in ``[]``, where ``0`` is the first command in the commands list,
 ``1`` is the second command, ``2`` is the third and so on.
 
+
+Handling prompts in network modules
+===================================
+
+Network devices may require that you answer a prompt before performing a change on the device. Individual network modules such as :ref:`ios_command <ios_command_module>` and :ref:`nxos_command <nxos_command_module>` can handle this with a ``prompt`` parameter.
+
+.. note::
+
+	``prompt`` is a Python regex. If you add special characters such as ``?`` in the ``prompt`` value, the prompt won't match and you will get a timeout. To avoid this, ensure that the ``prompt`` value is a Python regex that matches the actual device prompt. Any special characters must be handled correctly in the ``prompt`` regex.
+
+You can also use the :ref:`cli_command <cli_command_module>` to handle multiple prompts.
+
+.. code-block:: yaml
+
+  ---
+  - name: multiple prompt, multiple answer (mandatory check for all prompts)
+    cli_command:
+      command: "copy sftp sftp://user@host//user/test.img"
+      check_all: True
+      prompt:
+        - "Confirm download operation"
+        - "Password"
+        - "Do you want to change that to the standby image"
+      answer:
+        - 'y'
+        - <password>
+        - 'y'
+
+You must list the prompt and the answers in the same order (that is, prompt[0] is answered by answer[0]).
+
+In the above example, ``check_all: True`` ensures that the task gives the matching answer to each prompt. Without that setting, a task with multiple prompts would give the first answer to every prompt.
+
+In the following example, the second answer would be ignored and ``y`` would be the answer given to both prompts. That is, this task only works because both answers are identical. Also notice again that ``prompt`` must be a Python regex, which is why the ``?`` is escaped in the first prompt.
+
+.. code-block:: yaml
+
+  ---
+   - name: reboot ios device
+     cli_command:
+       command: reload
+       prompt:
+         - Save\?
+         - confirm
+       answer:
+         - y
+         - y
+
+.. seealso::
+
+  `Rebooting network devices with Ansible <https://www.ansible.com/blog/rebooting-network-devices-with-ansible>`_
+      Examples using ``wait_for``, ``wait_for_connection``, and ``prompt`` for network devices.
+
+  `Deep dive on cli_command <https://www.ansible.com/blog/deep-dive-on-cli-command-for-network-automation>`_
+      Detailed overview of how to use the ``cli_command``.
diff --git a/lib/ansible/modules/network/ios/ios_command.py b/lib/ansible/modules/network/ios/ios_command.py
index b9d4f8e246a..59ea254b2dc 100644
--- a/lib/ansible/modules/network/ios/ios_command.py
+++ b/lib/ansible/modules/network/ios/ios_command.py
@@ -111,6 +111,7 @@ tasks:
       wait_for:
         - result[0] contains IOS
         - result[1] contains Loopback0
+
   - name: run commands that require answering a prompt
     ios_command:
       commands:
diff --git a/lib/ansible/modules/network/nxos/nxos_command.py b/lib/ansible/modules/network/nxos/nxos_command.py
index 9fcad38a5e3..8a213ea6ccd 100644
--- a/lib/ansible/modules/network/nxos/nxos_command.py
+++ b/lib/ansible/modules/network/nxos/nxos_command.py
@@ -103,6 +103,15 @@ EXAMPLES = """
     commands:
       - command: show version
         output: json
+
+- name: run commands that require answering a prompt
+  nxos_command:
+    commands:
+      - configure terminal
+      - command: 'no feature npv'
+        prompt: 'Do you want to continue'
+        answer: 'y'
+
 """
 
 RETURN = """