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
totrue
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.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 besys.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
totrue
.
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:
Resolve
<user_username>
to the selected value:Run (GET) User Details to fetch the users detail stored in the system, and resolve the returned values to
user_firstname
,user_lastname
anduser_email
.Does the sync_type in the returned data contain the word “LDAP”?
Yes. In this case, disable the following fields:
username
,firstname
,lastname
,email
, andpassword
.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
:User inputs values for the following fields:
firstname
,lastname
,email
Resolve these values to the following:
<user_firstname>
,<user_lastname>
,<user_email>
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>
totrue
, 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>
"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 |
---|---|
|
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 |
---|---|---|---|
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
Voicemail/ extension mobility PIN. |
string |
|
|
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”:” |
Parameter |
Description |
Type |
Notes |
---|---|---|---|
|
The Quick Add Group name |
string |
Part of the desk phone details, which includes qagroup_name, phone_type, phone_protocol, phone_name. |
|
Desk phone. |
boolean |
Defines whether a desk phone is required.
Default is False. |
|
The phone model. |
string |
Part of the desk phone details, which includes qagroup_name, phone_type, phone_protocol, phone_name. Displays when |
|
The desk phone protocol. |
string |
Part of the desk phone details, which includes qagroup_name, phone_type, phone_protocol, phone_name. |
|
The desk phone button template name. |
string |
|
|
One or more phones. |
array of objects. |
Includes the desk phone MAC address (phone_name) for each of the user’s phones. |
|
Voicemail service |
boolean |
Defines whether the voicemail service is
required. The default is False. |
|
Extension mobility service |
boolean |
Defines whether the extension mobility
service is required.
The default is False. |
|
Jabber service (True/False) |
boolean |
Allows allocation of soft phones.
The default is False. |
|
One or more Jabber devices. |
array of objects |
If Four types of jabber devices can be assigned:
|
|
Callback details. |
object |
These details enable VOSS Automate to update the status when the initiated transaction is complete. |