.. _change-cucm-pin-passw-or-cuc-pin:

Reset a CUCM PIN/password and/or CUC PIN
--------------------------------------------------

Overview 
..........

This API POST call resets passwords and PINs for the following: 

1. CUCM (Cisco Unified Communications Manager) PIN, used for extension mobility
2. CUCM (Cisco Unified Communications Manager) password for Jabber (if device is associated to a CUCM local user)
3. CUC (Cisco Unified Unity) voicemail PIN

``POST https://<hostname>/api/api/view/ResetUCPasswordPinVIEW``


.. rubric:: References:

* `OpenAPI Example for view/ResetUCPasswordPinVIEW <ServiceNow-integration.html#/paths/~1api~1view~1ResetUCPasswordPinVIEW/post>`__
* `Model: view/ResetUCPasswordPinVIEW <https://documentation.voss-solutions.com/release_RELEASENUM/html/src/api-ref/view_ResetUCPasswordPinVIEW-Model.html>`__
* `API Reference for view/ResetUCPasswordPinVIEW <https://documentation.voss-solutions.com/release_RELEASENUM/html/src/api-ref/view_ResetUCPasswordPinVIEW-API.html>`__


Using POST ResetUCPasswordPinVIEW
...................................

Resetting a CUCM PIN/password and/or CUC PIN involves the following tasks: 

1. Identify the customer and the customer's hierarchy.
2. Define whether the password/PIN reset is for CUCM (Extension Mobility PIN and Jabber password) and/or 
   CUC voicemail PIN.
3. Resolve the user details and credentials.
4. Allow user to fill out a PIN.


Step 1: Identify Customer+Customer Hierarchy
''''''''''''''''''''''''''''''''''''''''''''''''

1. Fetch the list of customers and populate a drop-down list, and allow the user to select a 
   customer from the list. ``<Customer Name>``

   Refer to :ref:`tool-macro-customers-id`.

2. Fetch available hierarchies for the selected customer (``<Customer Name>``). 

   Refer to :ref:`tool-macro-available-hierarchies-of-a-customer-id`


3. Resolve ``<Customer Hierarchy>``. 

   ``<Customer Hierarchy>`` is the entry from step 2 that ends with the ``<Customer Name>``). 

   For example, if ``<Customer Name>`` is Innovia, the ``<Customer Hierarchy>`` 
   will be ``sys.hcs.CS-P.CS-NB.Innovia``.



Step 2: Define whether the password/PIN reset is for CUCM or CUC 
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

1. The user is presented with two checkboxes on the GUI, one for CUCM and one for CUC.

   * ``<cucm_checkbox_boolean>``
   * ``<cuc_checkbox_boolean>``

2. Users can select one or both checkboxes. 

   When selected, set the value for the relevant fields to ``true``, else, set to ``false``. 



Step 3: Resolve user details and credentials
''''''''''''''''''''''''''''''''''''''''''''''''

1. Fetch all available users currently in the customer to populate the ``user_username`` drop-down, and 
   allow the user to select a value. 

   Refer to :ref:`tool-macro-usernames-at-customer-and-downwards-id` (Customer hierarchy)

2. Fetch user details stored in the system to identify whether it is a 
   LDAP user or a local user.

   Refer to :ref:`tool-macro-user-details-id`
 
3. Does the ``sync_type`` in the data returned contain the word "LDAP"? 
 
   * **Yes**. Disable the ``password`` field, and do bot send ``<password_value>`` in the payload.
   * **No**. Keep the ``password`` field enabled, allowing the user to fill out a password, which 
     resolves to ``<password_value>`` in the payload.

4. Provide a text field titled "Voicemail/Extension Mobility PIN", and allow the user to 
   fill out a PIN, which resolves to ``<pin_value>``. 

   .. note::

      Validate form field to only allow numeric values.




Query parameters
......................


.. tabularcolumns:: |p{4cm}|p{11cm}|

+--------------------+----------------+
| Parameter          | Value          |
+====================+================+
| ``hierarchy``      | Site           |
+--------------------+----------------+



Request Payload (Body)
...........................

The box lists all parameters that could be included in the call request. These parameters are described 
in the table below the box: 


::

   {
      "user": "<username>",
      "cucm": <cucm_checkbox_boolean>,
      "cuc": <cuc_checkbox_boolean>,
      "password": "<password_value>",
      "pin": "<pin_value>",
      "request_meta": {
         "external_id": "<id>",
         "external_reference": "<Reference>",
         "callback_url": "<url_string>",
         "callback_username": "<callback_username>",
         "callback_password": "<callback_password>"
      }
   }



The table describes the parameters in the request: 

.. tabularcolumns:: |p{3cm}|p{3cm}|p{3cm}|p{6cm}|

+----------------------+-----------------------------+--------------+-----------------------------------------------+
| Parameter            | Description                 | Type         | Notes                                         |
+======================+=============================+==============+===============================================+
| ``user``             | The username.               | string       |                                               |
+----------------------+-----------------------------+--------------+-----------------------------------------------+
| ``cucm``             | CUCM.                       | boolean      | Defines whether the password/PIN reset is for |
|                      |                             |              | CUCM. ``<cucm_checkbox_boolean>``             |
|                      |                             |              |                                               |
|                      |                             |              | Default is False. Set to True to reset a CUCM |
|                      |                             |              | PIN or password.                              |
+----------------------+-----------------------------+--------------+-----------------------------------------------+
| ``cuc``              | CUC                         | boolean      | Defines whether the password/PIN reset is for |
|                      |                             |              | CUC. ``<cuc_checkbox_boolean>``               |
|                      |                             |              |                                               |
|                      |                             |              | Default is False. Set to True to reset a CUC  |
|                      |                             |              | PIN.                                          |
+----------------------+-----------------------------+--------------+-----------------------------------------------+
| ``password``         | The Jabber password.        | string       | When value for ``<cucm_checkbox_boolean>``    |
|                      |                             |              | is ``True``, set the Jabber password in       |
|                      |                             |              | ``<password_value>``.                         | 
+----------------------+-----------------------------+--------------+-----------------------------------------------+
| ``pin``              | The Extension Mobility or   | integer      | When value for ``<cucm_checkbox_boolean>``    |
|                      | Voicemail PIN.              |              | and/or ``<cuc_checkbox_boolean>`` is          |
|                      |                             |              | ``True``, set a numeric PIN for CUCM          |
|                      |                             |              | Extension Mobility and CUC voicemail.         |
+----------------------+-----------------------------+--------------+-----------------------------------------------+
| ``request_meta``     | Callback details.           | object       | These details enable VOSS Automate to update  |
|                      |                             |              | the status when the initiated transaction is  |
|                      |                             |              | complete.                                     |
+----------------------+-----------------------------+--------------+-----------------------------------------------+