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:

Identify the customer and customer hierarchy, and the site and site hierarchy.
Hardcode the value of lookUpForUser to true in the payload.
Resolve the user details and credentials.
Retrieve lines and select the lines to be assigned.
Retrieve Quick Add Groups.
Select services for the subscriber.
Allocate soft phones for the subscriber
Allocate one or more desk phones for the subscriber

Step 1: Identify Customer+Customer Hierarchy and Site+Site Hierarchy#

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).
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
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#

In the payload, hardcode the value for lookUpForUser to true.

Step 3: Resolve user details and credentials#

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).
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>.
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#

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”.
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#

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”).
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#

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#

If the user selects the Allocate Deskphone checkbox, set the value for <voice> to true, and enable and display the relevant fields.
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>)
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.

Add a Cisco subscriber

On this page

Add a Cisco subscriber#

Overview#

Using POST QuickSubscriber#

Step 1: Identify Customer+Customer Hierarchy and Site+Site Hierarchy#

Step 2: Set lookUpForUser to True in the payload#

Step 3: Resolve user details and credentials#

Step 4: Retrieve the lines to be assigned#

Step 5: Retrieve Quick Add Groups#

Step 6: Select services for the subscriber#

Step 7: Allocate a soft phone for a subscriber#

Step 8: Allocate desk phones for a subscriber#

Query parameters#

Request Payload (Body)#