Add a Cisco subscriber#

Overview#

This API POST call creates a new Cisco subscriber.

POST https://<hostname>/api/api/view/QuickSubscriber

References:

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. <Customer Name>

    Refer to (GET) Customers (for deployments with or without HCM-F).

  2. Fetch available site hierarchies for the selected customer (<Customer Name>). User selects the site where the subscriber will be added.

    Refer to (GET) All Sites Belonging to the Customer

  3. Resolve <Customer Hierarchy> and <Site Hierarchy>.

    • <Customer Hierarchy> is the entry in the earlier step 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.

    • <Site Hierarchy> 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 (GET) Usernames at Customer and Downwards (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:

      1. Resolve <user_username> to the selected value:

        1. Run (GET) User Details 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 (GET) User Details

            Do not send <user_password> in the payload.

          • No. In this case, populate the following fields with the values fetched from (GET) User Details: 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 <user_password>, in the payload.

    • Option 2: User enters a new value for username:

      1. User inputs values for the following fields: firstname, lastname, email

      2. Resolve these values to the following: <user_firstname>, <user_lastname>, <user_email>

      3. User fills out a password (password), which resolves to <user_password>.

  3. User fills out the voicemail / Extension Mobility PIN in pin, which resolves to <user_vm_em_pin>

Step 4: Retrieve the lines to be assigned#

  1. List all available directory numbers (DN) to populate lines.

    Refer to (GET) Directory Numbers (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,… (<line_(n)>).

Step 5: Retrieve Quick Add Groups#

  1. Populate read-only qagroup_name drop-down with values from the system.

    Refer to (GET) Available Quick Add Groups

    Display that value in the list as default (“78XX Reference Quick Add Group”).

  2. Set <qag_name> 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 <voicemail> to True (<voicemail_reqd_true_false> = true)

  • Extension Mobility service:

    If the user selects the Extension Mobility checkbox, set the value for <mobility> to True (<extnmobility_reqd_true_false> = 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:

    • <android_jabber_device_name>

      GET https://ucprovision.voss-solutions.com/api/tool/Macro/?method=evaluate&input={{ fn.jabber_device_name 'Cisco Dual Mode for Android', <user_username> }}
      
    • <csf_jabber_device_name>

      GET https://ucprovision.voss-solutions.com/api/tool/Macro/?method=evaluate&input={{ fn.jabber_device_name 'Cisco Unified Client Services Framework', <user_username> }}
      
    • <ipad_jabber_device_name>

      GET https://ucprovision.voss-solutions.com/api/tool/Macro/?method=evaluate&input={{ fn.jabber_device_name 'Cisco Jabber for Tablet', <user_username> }}
      
    • <iphone_jabber_device_name>

      GET https://ucprovision.voss-solutions.com/api/tool/Macro/?method=evaluate&input={{ fn.jabber_device_name 'Cisco Dual Mode for iPhone', <user_username> }}
      

Step 8: Allocate desk phones for a subscriber#

  1. If the user selects the Allocate Deskphone checkbox, set the value for <voice> 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 <deskphone_model>

    Refer to (GET) Phone Models (<Site Hierarchy>)

  3. Once a value is selected for <deskphone_model>, populate the following fields:

    • <phone_protocol>

      User selects a phone protocol (<phone_protocol>)from the drop-down. The chosen option is resolved as the value (<deskphone_protocol>)

      Refer to (GET) Supported Protocols (using <Site Hierarchy> and <deskphone_model>)

    • <button_template>

      Users selects a phone button template (<button_template>) from the drop-down, which is resolved as the value for <deskphone_pbt_name>

      Refer to (GET) Phone Button Templates for Phone Model

    • "phone_name": "<deskphone_MAC_address>

      In the “Phone MAC Address” drop-down, populate unassociated phones that belong to <deskphone_model>, currently in this site.

      Refer to (GET) Unassociated Phones of Specific Model at Site

      Choose one of the following options:

      • User selects one value, which resolves to <deskphone_MAC_address>.

        Alternatively:

      • Users fills out a MAC address for <deskphone_MAC_address>.

        Note

        Note the input conditions for MAC address in the OpenAPI example for view/QuickSubscribe

Query parameters#

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": "<user_username>",
   "firstname": "<user_firstname>",
   "lastname": "<user_lastname>",
   "email": "<user_email>",
   "password": "<user_password>",
   "pin": "<user_vm_em_pin>",
   "lines": [
   {
         "directory_number": "<line_1>"
   },
   {
         "directory_number": "<line_2>"
   }
   ],
   "qagroup_name": "<qag_name>",
   "voice": <deskphone_reqd_true_false>,
   "phone_type": "<deskphone_model>",
   "phone_protocol": "<deskphone_protocol>",
   "button_template": "<deskphone_pbt_name>",
   "phones": [
   {
         "phone_name": "<deskphone_MAC_address>"
   }
   ],
   "voicemail": <voicemail_reqd_true_false>,
   "mobility": <extnmobility_reqd_true_false>,
   "jabber": <jabber_reqd_true_false>,
   "jabber_devices": [
   {
         "jabber_agent": "android",
         "device_name": "<android_jabber_device_name>"
   },
   {
         "jabber_agent": "csf",
         "device_name": "<csf_jabber_device_name>"
   },
   {
         "jabber_agent": "ipad",
         "device_name": "<ipad_jabber_device_name>"
   },
   {
         "jabber_agent": "iphone",
         "device_name": "<iphone_jabber_device_name>"
   }
   ],
   "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:

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/ extension mobility PIN.

string

lines

One or more user lines.

array of objects

Multiple lines can be added to a phone, and are ordered 1,2, and so on.

“directory_number”:”line_1”, “directory_number”:”line_2”, “directory_number”: “line_n

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. <deskphone_reqd_true_false>

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 template name.

string

phones

One or more phones.

array of objects.

Includes the desk phone MAC address (phone_name) for each of the user’s phones.

voicemail

Voicemail service

boolean

Defines whether the voicemail service is required. <voicemail_reqd_true_false>

The default is False.

mobility

Extension mobility service

boolean

Defines whether the extension mobility service is required. <extnmobility_reqd_true_false>

The default is False.

jabber

Jabber service (True/False)

boolean

Allows allocation of soft phones. <jabber_reqd_true_false>

The default is False.

jabber_devices

One or more Jabber devices.

array of objects

If <jabber>=True, the list of Jabber devices, specifying a value for <jabber_agent> and <device_name>

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.