GET /tool/Macro#

Overview#

This section provide details on use case examples with GET tool/macro.

In each case, you will need to specify the organization hierarchy, for example, Provider, Customer, or Site, and provide a macro that specifies the data to retrieve.

All GET calls in this OpenAPI format example point to the same endpoint, tool/macro. You will add a VOSS Automate macro as the input parameter for this endpoint to retrieve the information you require.

The following is a basic example of the syntax of a GET request, using a macro as the input parameter, to a fictional Automate endpoint:

GET https://<hostname>/api/tool/Macro/
    ?hierarchy=<hierarchy>
    &method=evaluate
    &input='<macro>'

Refer to the link below to view full details around the syntax, parameter values, and response samples related to the combination of endpoint (GET tool/macro) and various macro input parameters used for retrieving data associated to the macro:

OpenAPI Specification Examples.

References:

(GET) Customers#

Fetches a list of customers and their details, in UC deployments.

Customer data is held in the following fields in VOSS Automate:

Field

Description

Short Name

The name of the customer.

Extended Name

An extended version of the customer name.

Deal ID

The external reference ID for the customer

Two scenarios are provided:

  • UC deployment with Cisco HCM-F

  • UC deployment without Cisco HCM-F

(GET) Customers (with HCM-F)#

Looks up an external reference used for customers, in a Cisco HCM-F deployment. The external reference ID is stored in device.hcmf.Customer.dealIDInfo (Automate field) for each customer.

Note

Other fields in device.hcmf.Customer (Automate table/model) may also be used for storing external references and can also be looked up using this same method.

Example 1: Fetch a list of all customers and their external IDs

Query parameters:

  • Hierarchy: Provider

  • Input: None

  • Macro:

    {# device.hcmf.Customer.shortName,extendedName,dealIDInfo | type: Customer #}

Example 2: Pass a customer’s external ID and fetch details for that customer only

Query parameters:

  • Hierarchy: Provider

  • Input: DealIDInfo

  • Macro:

    {# device.hcmf.Customer. shortName,extendedName | dealIDInfo:01150015 | type: Customer #}

(GET) Customers (without HCM-F)#

Looks up an external reference used for customers, in a non-Cisco HCM-F deployment. The external reference ID is stored in data.HCSHcmfCustomerDAT.dealIDInfo (Automate field), for each customer.

Note

Other fields in data.HCSHcmfCustomerDAT (Automate table/model) can also be used for storing external references and can also be looked up, using this same method.

Example 1: Fetch the list of all customers and their respective external IDs

Query parameters:

  • Hierarchy: Provider

  • Input: None

  • Macro:

    {# data.HCSHcmfCustomerDAT.shortName,extendedName,dealIDInfo #}

Example 2: Pass a customer’s external ID and fetch information for that customer only

Query Parameters:

  • Hierarchy: Provider

  • Input: DealIDInfo

  • Macro:

    {# data.HCSHcmfCustomerDAT.shortName,extendedName | dealIDInfo:<Reference ID>#}

(GET) All Sites Belonging to the Customer#

Passes the customer name to fetch a list of all sites (locations) in the system that belong to the specified customer.

Note

You can use this macro to dynamically populate the list of sites in the ServiceNow form, enabling the user to select the site where the standalone phone needs to be provisioned.

Query parameters:

  • Hierarchy: Site

  • Input: Customer Name

  • Macro:

    {# device.hcmf.CustomerLocation.shortName | bkCustomer_shortName:<CustomerName> #}

(GET) Directory Numbers#

Fetches all directory numbers that are at a specific site, regardless of whether the numbers are available or used.

Query parameters:

  • Hierarchy: Site

  • Input: None

  • Macro:

    {# data.InternalNumberInventory.internal_number,e164number,description,status,usage #}

(GET) Next Available Number#

Fetches the next available (unused) directory number (DN) in the site.

Automate maintains the availability and status in the internal number inventory (INI). The API call uses the flags set in the INI table to fetch the relevant information.

Query parameters:

  • Hierarchy: Site

  • Input: None

  • Macro:

    {{ fn.one data.InternalNumberInventory.internal_number | status:Available | direction:up }}

(GET) Phone Models#

Fetches phone model information. Two options are provided:

  • Fetch all phone models currently available to a customer

  • Fetch all phone models currently offered to customers by the Provider

(GET) All phone models currently available to a customer#

Fetches all phone models that are currently available to a customer.

Note

This is useful where a Provider supplies a selection of phone models for different customers, rather than a general list of phone models for all of its customers.

Query parameters:

  • Hierarchy: Customer

  • Input: None

  • Macro:

    {{ data.PhoneConfigMapping.profiles.*.profile_name | name:Default }}

Note

Ensure that data.PhoneConfigMapping.profiles is cloned from the sys or provider level to the customer level, and only retain the device types that are offered to the customer.

(GET) All phone models currently offered to customers by the provider#

Fetches all phone models that are currently offered to customers by the Provider. The user selects a phone model from the dynamically populated list, to be used in the next transaction.

Query parameters:

  • Hierarchy: Customer or Site

  • Input: None

  • Macro:

    {# data.HcsDeviceTypeDAT.name | name:/^Cisco \d\d\d\d/ | direction:up #}

(GET) All Phones Belonging to a Customer (with PKIDs)#

Fetches the following details for all phones belonging to a customer, with their PKIDs:

Phone detail

Notes

PKID

PKID is the database record reference of the phone in phone model (table) that will be used for modification or deletion.

MAC Address

Phone Model

Phone Description

Phone Owner (if associated)

Line settings

For example:

  • Line Display

  • Line Display ASCII

  • Line Label

  • Line Recording

Query parameters:

  • Hierarchy: Customer (or) Site

  • Input: None

  • Macro:

    {# device.cucm.Phone.__pkid,name,product,description,ownerUserName,lines.line.index,lines.line.dirn.pattern,lines.line.dis  play,lines.line.displayAscii,lines.line.label,lines.recordingFlag,lines.recordingMediaSource,lines.recordingProfileName #}

(GET) Subscriber PKID and Name#

Fetches the PKID, user ID, first name, and last name of all users at the customer or site hierarchy.

Query parameters:

  • Hierarchy: Customer (or) Site

  • Input: None

  • Macro:

    {# device.cucm.User.firstName,userid,__pkid,lastName #}

(GET) All Phones#

Fetches all phones at a specified hierarchy.

Query parameters:

* Hierarchy: Customer (or) Site
* Input: None
* Output(s): Phone MAC Address, Details of Phone
* Macro

customer hierarchy:

{{ fn.get_phone_choices ,,,down }}

site hierarchy:

{{ fn.get_phone_choices ,,,local }}

(GET) All Phones Belonging to a Subscriber#

Fetches all phones that belong to a specified user.

Query parameters:

  • Hierarchy: Site

  • Input: Userid

  • Macro:

    {{ fn.one device.cucm.User.associatedDevices.device | userid:<usename> }}

(GET) All Phones Without Associated User#

Fetches all phones at a site that do not have a owneruserid; that is, unassociated phones.

Query parameters:

  • Hierarchy: Site

  • Input: None

  • Output values: Phone MAC Address, Phone Description

  • Macro:

    {# device.cucm.Phone.name,description | ownerUserName:null | direction:local #}

(GET) All DeviceProfiles Without Associated User#

Fetches all Cisco Unified Device Profiles (UDP) at a site that are not associated to a user.

Query parameters:

  • Hierarchy: Site

  • Input: None

  • Output value(s): UDP Name

  • Macro:

    {# fn.list_set_left macro.DEVICEPROFILE_LIST,macro.PHONEPROFILE_LIST_FLATTENED #}

(GET) All Line Details#

Fetches all lines at a specified hierarchy.

Query parameters:

  • Hierarchy: Customer (or) Site

  • Input: None

  • Output(s): Line record PKID, Line Pattern, Line Description, Line AlertingName, Line ASCIIAlertingName

  • Macro:

    {# device.cucm.Line.__pkid,pattern,description,alertingname,asciialertingname #}

(GET) Subscribers Lines#

Fetches all lines that belong to a subscriber.

Query parameters:

  • Hierarchy: Customer (or) Site

  • Input: User name

  • Macro:

    {{ fn.get_associated_lines <username> }}

(GET) Supported Protocols#

Fetches all the protocols that a specified phone model supports.

Query parameters:

  • Hierarchy: Customer

  • Input: Phone Model

  • Macro:

    {{device.cucm.PhoneType.ProtocolTemplates.*.Protocol | PhoneType:<Phone Model> | direction:up, device:macro.SITE_CUCM }}

(GET) Phone Button Templates for Phone Model#

Fetches all the Phone Buttons Templates that are available in the system for a specified phone model.

Query parameters:

  • Hierarchy: Customer

  • Input: Phone Model, Protocol

  • Macro

    {{ device.cucm.PhoneType.ProtocolTemplates.*.PBT| PhoneType:<Phone Model>, ProtocolTemplates.*.Protocol:<Phone Protocol> | direction:up, device:macro.SITE_CUCM }}

(GET) Security Profiles for Phone Model#

Fetches all the available security profiles for a specified phone model.

Query parameters:

  • Hierarchy: Customer

  • Input: Phone Model, Protocol

  • Macro:

    {{ device.cucm.PhoneType.ProtocolTemplates.*.SecurityProfile | PhoneType:<Phone Model>, ProtocolTemplates.*.Protocol:<Phone Protocol> | direction:up, device:macro.SITE_CUCM }}

(GET) Subscriber’s Phones and Services#

Fetches the details of existing phones, lines, and services of a subscriber. You can use these details to assign further services to a subscriber or to move a subscriber between sites.

Query parameters:

  • Hierarchy: Customer

  • Input: username

  • Macro:

    {{ fn.movesub_getguirules_on_username_change <username> }}

(GET) Available Hierarchies of a Customer#

Fetches all the available hierarchy paths for a specified customer.

Query parameters:

  • Hierarchy: Customer

  • Input: None

  • Macro:

    {# fn.friendly_path_choices,down #}

The output provides the customer hierarchy and site hierarchies.

(GET) Usernames at Customer and Downwards#

Fetches all usernames at the customer hierarchy, and below.

Query parameters:

  • Hierarchy: Customer

  • Input: None

  • Macro:

    {{ fn.list_end_user_names down, fn.null }}

(GET) User Details#

Fetches a user’s username, first name, last name, email, and sync_type.

Query parameters:

  • Hierarchy: Site

  • Input: Username

  • Macro

    {# data.User.username,first_name,last_name,email,sync_type | username: <username> #}

(GET) Customer Common Phone Configs#

Fetches the names of all Common Phone Configs.

Query parameters:

  • Hierarchy: Customer

  • Input: None

  • Macro:

    {# device.cucm.CommonPhoneConfig.name #}

(GET) Available Quick Add Groups#

Fetches all Quick Add Groups available at a site. This will be used in Quick Add Subscriber.

Query parameters:

  • Hierarchy: Site

  • Input: None

  • Macro

    {# data.QuickAddGroups.group_name || direction:up, to:Hcs #}

(GET) Unassociated Phones of Specific Model at Site#

Fetches all unassociated phones of a specified model and protocol, at a site.

Query parameters:

  • Hierarchy: Site

  • Input: Phone Model, Phone Protocol

    Note

    This query is used to pre-populate the Phone MAC Address field in Quick Subscriber.

  • Macro

    {{ fn.get_phone_choices <Phone Model>,<Phone Protocol>,null,up }}