Add a Cisco subscriber ------------------------------ Overview .......... This API POST call creates a new Cisco subscriber. ``POST https:///api/api/view/QuickSubscriber`` .. rubric:: References: * `OpenAPI example for view/QuickSubscriber `__ * `Model: view/QuickSubscriber `__ * `API Reference for view/QuickSubscriber `__ Using POST QuickSubscriber ............................ Creating a new Cisco subscriber involves the following tasks: 1. Identify the customer and customer hierarchy, and the site and site hierarchy. 2. Hardcode the value of ``lookUpForUser`` to ``true`` in the payload. 3. Resolve the user details and credentials. 4. Retrieve lines and select the lines to be assigned. 5. Retrieve Quick Add Groups. 6. Select services for the subscriber. 7. Allocate soft phones for the subscriber 8. Allocate one or more desk phones for the subscriber Step 1: Identify Customer+Customer Hierarchy and Site+Site Hierarchy ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 1. Fetch the list of customers and populate a drop-down list. User selects a customer from the list. ```` Refer to :ref:`tool-macro-customers-id`. 2. Fetch available site hierarchies for the selected customer (````). User selects the site where the subscriber will be added. Refer to :ref:`tool-macro-sites-belonging-to-the-customer-id` 3. Resolve ```` and ````. * ```` is the entry in the earlier step that ends with the ````. For example, if ```` is Innovia, the ```` will be ``sys.hcs.CS-P.CS-NB.Innovia``. * ```` is the entry in the earlier step that the operator selects. For example, ``sys.hcs.CS-P.CS-NB.Innovia.INV-Reading``, ``sys.hcs.CS-P.CS-NB.Innovia.INV-New York`` Step 2: Set lookUpForUser to True in the payload '''''''''''''''''''''''''''''''''''''''''''''''''''''''''' 1. In the payload, hardcode the value for ``lookUpForUser`` to ``true``. Step 3: Resolve user details and credentials '''''''''''''''''''''''''''''''''''''''''''''''' 1. Fetch all available users currently in the customer to populate the ``user_username`` drop-down. Refer to :ref:`tool-macro-usernames-at-customer-and-downwards-id` (Customer hierarchy). 2. The user can either select a value from the drop-down (for LDAP users synced in from CUCM or Active Directory), or they can fill out a username (for local users). Choose an option, and follow the relevant steps for the use case: * Option 1: User selects an existing name from the drop-down: a. Resolve ```` to the selected value: 1. Run :ref:`tool-macro-user-details-id` to fetch the users detail stored in the system, and resolve the returned values to ``user_firstname``, ``user_lastname`` and ``user_email``. 2. Does the sync_type in the returned data contain the word "LDAP"? * **Yes**. In this case, disable the following fields: ``username``, ``firstname``, ``lastname``, ``email``, and ``password``. Populate the following fields with the values returned in :ref:`tool-macro-user-details-id` Do not send ```` in the payload. * **No**. In this case, populate the following fields with the values fetched from :ref:`tool-macro-user-details-id`: ``firstname``, ``lastname``, ``email`` Keep these fields enabled to allow the user to change values if they wish. Keep the ``password`` field enabled, allowing the user to fill out a password (which is resolved in ````, in the payload. * Option 2: User enters a new value for ``username``: a. User inputs values for the following fields: ``firstname``, ``lastname``, ``email`` b. Resolve these values to the following: ````, ````, ```` c. User fills out a password (``password``), which resolves to ````. 3. User fills out the voicemail / Extension Mobility PIN in ``pin``, which resolves to ```` Step 4: Retrieve the lines to be assigned '''''''''''''''''''''''''''''''''''''''''''''' 1. List all available directory numbers (DN) to populate ``lines``. Refer to :ref:`tool-macro-directory-numbers-id` (at the site hierarchy) .. note:: Values in the drop-down should be the concatenation of values fetched ("internal_number \| e164number \| status"). For example, "1084000 \| +441184121000 \| Available","1084010 \| +441184121010 \| Used". 2. User chooses a directory number (``directory_number``). .. note:: Multiple lines can be added to one phone. Two or more lines can be ordered 1,2,... (````). Step 5: Retrieve Quick Add Groups '''''''''''''''''''''''''''''''''''' 1. Populate read-only ``qagroup_name`` drop-down with values from the system. Refer to :ref:`tool-macro-available-quick-add-groups-id` Display that value in the list as default ("78XX Reference Quick Add Group"). 2. Set ```` with the default value or a selected value. Step 6: Select services for the subscriber '''''''''''''''''''''''''''''''''''''''''''''''' * Voicemail service: If user selects the **Voicemail** checkbox, set the value for ```` to True (`` = true``) * Extension Mobility service: If the user selects the **Extension Mobility** checkbox, set the value for ```` to True (`` = true``) Step 7: Allocate a soft phone for a subscriber '''''''''''''''''''''''''''''''''''''''''''''''''' 1. If the user selects the **Cisco Jabber Phone** checkbox, they can assign one or more jabber devices. Device names are allocated using an API call specific to the device type selected: * ```` :: GET https://ucprovision.voss-solutions.com/api/tool/Macro/?method=evaluate&input={{ fn.jabber_device_name 'Cisco Dual Mode for Android', }} * ```` :: GET https://ucprovision.voss-solutions.com/api/tool/Macro/?method=evaluate&input={{ fn.jabber_device_name 'Cisco Unified Client Services Framework', }} * ```` :: GET https://ucprovision.voss-solutions.com/api/tool/Macro/?method=evaluate&input={{ fn.jabber_device_name 'Cisco Jabber for Tablet', }} * ```` :: GET https://ucprovision.voss-solutions.com/api/tool/Macro/?method=evaluate&input={{ fn.jabber_device_name 'Cisco Dual Mode for iPhone', }} Step 8: Allocate desk phones for a subscriber '''''''''''''''''''''''''''''''''''''''''''''''''''' 1. If the user selects the **Allocate Deskphone** checkbox, set the value for ```` to ``true``, and enable and display the relevant fields. 2. Fetch available phone types, and allow the user to select a phone model, which resolves into ```` Refer to :ref:`tool-macro-phone-models-id` (````) 3. Once a value is selected for ````, populate the following fields: * ```` User selects a phone protocol (````)from the drop-down. The chosen option is resolved as the value (````) Refer to :ref:`tool-macro-protocols-supported-id` (using ```` and ````) * ```` Users selects a phone button template (````) from the drop-down, which is resolved as the value for ```` Refer to :ref:`tool-macro-phone-button-templates-for-phone-model-id` * ``"phone_name": "`` In the "Phone MAC Address" drop-down, populate unassociated phones that belong to ````, currently in this site. Refer to :ref:`tool-macro-unassociated-phones-of-specific-model-at-site-id` Choose *one* of the following options: * User selects one value, which resolves to ````. Alternatively: * Users fills out a MAC address for ````. .. note:: Note the input conditions for MAC address in the `OpenAPI example for view/QuickSubscribe `__ 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: :: { "lookUpForUser": true, "username": "", "firstname": "", "lastname": "", "email": "", "password": "", "pin": "", "lines": [ { "directory_number": "" }, { "directory_number": "" } ], "qagroup_name": "", "voice": , "phone_type": "", "phone_protocol": "", "button_template": "", "phones": [ { "phone_name": "" } ], "voicemail": , "mobility": , "jabber": , "jabber_devices": [ { "jabber_agent": "android", "device_name": "" }, { "jabber_agent": "csf", "device_name": "" }, { "jabber_agent": "ipad", "device_name": "" }, { "jabber_agent": "iphone", "device_name": "" } ], "request_meta": { "external_id": "", "external_reference": "", "callback_url": "", "callback_username": "", "callback_password": "" } } The table describes the parameters in the request: .. tabularcolumns:: |p{3cm}|p{3cm}|p{3cm}|p{6cm}| +----------------------+-----------------------------+--------------+-----------------------------------------------+ | Parameter | Description | Type | Notes | +======================+=============================+==============+===============================================+ | ``username`` | The username. | string | For local users, the operator enters the user | | | | | details (username, firstname, | | | | | lastname, and email) in the form. | | | | | | | | | | For Active Directory (AD) users, the user | | | | | details (username, firstname, lastname, and | | | | | email) are fetched from the system, and the | | | | | form fields are read-only. | +----------------------+-----------------------------+--------------+-----------------------------------------------+ | ``firstname`` | The user's first name. | string | For local users, the operator enters the user | | | | | details (username, firstname, | | | | | lastname, and email) in the form. | | | | | | | | | | For Active Directory (AD) users, the user | | | | | details (username, firstname, lastname, and | | | | | email) are fetched from the system, and the | | | | | form fields are read-only. | +----------------------+-----------------------------+--------------+-----------------------------------------------+ | ``lastname`` | The user's last name. | string | For local users, the operator enters the user | | | | | details (username, firstname, | | | | | lastname, and email) in the form. | | | | | | | | | | For Active Directory (AD) users, the user | | | | | details (username, firstname, lastname, and | | | | | email) are fetched from the system, and the | | | | | form fields are read-only. | +----------------------+-----------------------------+--------------+-----------------------------------------------+ | ``email`` | The user's email address. | string | For local users, the operator enters the user | | | | | details (username, firstname, | | | | | lastname, and email) in the form. | | | | | | | | | | For Active Directory (AD) users, the user | | | | | details (username, firstname, lastname, and | | | | | email) are fetched from the system, and the | | | | | form fields are read-only. | +----------------------+-----------------------------+--------------+-----------------------------------------------+ | ``password`` | The user's password. | string | For local users, the operator enters the user | | | | | password in the form. | | | | | | | | | | For Active Directory (AD) users, the user | | | | | password is not relevant, and the password | | | | | field is hidden on the form. | +----------------------+-----------------------------+--------------+-----------------------------------------------+ | ``pin`` | Voicemail/ | string | | | | extension mobility PIN. | | | +----------------------+-----------------------------+--------------+-----------------------------------------------+ | ``lines`` | One or more user lines. | array of | Multiple lines can be added to a phone, and | | | | objects | are ordered 1,2, and so on. | | | | | | | | | | "directory_number":"``line_1``", | | | | | "directory_number":"``line_2``", | | | | | "directory_number": "``line_n``" | +----------------------+-----------------------------+--------------+-----------------------------------------------+ .. tabularcolumns:: |p{3cm}|p{3cm}|p{3cm}|p{6cm}| +----------------------+-----------------------------+--------------+-----------------------------------------------+ | Parameter | Description | Type | Notes | +======================+=============================+==============+===============================================+ | ``qagroup_name`` | The Quick Add Group name | string | Part of the desk phone details, which | | | | | includes qagroup_name, phone_type, | | | | | phone_protocol, phone_name. | +----------------------+-----------------------------+--------------+-----------------------------------------------+ | ``voice`` | Desk phone. | boolean | Defines whether a desk phone is required. | | | | | ```` | | | | | | | | | | Default is False. | +----------------------+-----------------------------+--------------+-----------------------------------------------+ | ``phone_type`` | The phone model. | string | Part of the desk phone details, which | | | | | includes qagroup_name, phone_type, | | | | | phone_protocol, phone_name. | | | | | | | | | | Displays when ``"voice": true``. | +----------------------+-----------------------------+--------------+-----------------------------------------------+ | ``phone_protocol`` | The desk phone protocol. | string | Part of the desk phone details, which | | | | | includes qagroup_name, phone_type, | | | | | phone_protocol, phone_name. | +----------------------+-----------------------------+--------------+-----------------------------------------------+ | ``button_template`` | The desk phone button | string | | | | template name. | | | +----------------------+-----------------------------+--------------+-----------------------------------------------+ | ``phones`` | One or more phones. | array of | Includes the desk phone MAC address | | | | objects. | (phone_name) for each of the user's phones. | +----------------------+-----------------------------+--------------+-----------------------------------------------+ | ``voicemail`` | Voicemail service | boolean | Defines whether the voicemail service is | | | | | required. ```` | | | | | | | | | | The default is False. | +----------------------+-----------------------------+--------------+-----------------------------------------------+ | ``mobility`` | Extension mobility service | boolean | Defines whether the extension mobility | | | | | service is required. | | | | | ```` | | | | | | | | | | The default is False. | +----------------------+-----------------------------+--------------+-----------------------------------------------+ | ``jabber`` | Jabber service (True/False) | boolean | Allows allocation of soft phones. | | | | | ```` | | | | | | | | | | The default is False. | +----------------------+-----------------------------+--------------+-----------------------------------------------+ | ``jabber_devices`` | One or more Jabber devices. | array of | If ``=True``, the list of Jabber | | | | objects | devices, specifying a value for | | | | | ```` and ```` | | | | | | | | | | Four types of jabber devices can be assigned: | | | | | | | | | | * "android" | | | | | * "ipad" | | | | | * "iphone" | | | | | * "windows" | +----------------------+-----------------------------+--------------+-----------------------------------------------+ | ``request_meta`` | Callback details. | object | These details enable VOSS Automate to update | | | | | the status when the initiated transaction is | | | | | complete. | +----------------------+-----------------------------+--------------+-----------------------------------------------+