Using the API

Developer Guidelines

The following practices are recommended to all developers. The aim is to reduce the number and extent of any updates that may be necessary.

  1. Third party API clients must specify the API Version when integrating with Cisco Unified Communications Domain Manager 10.6(1). This is required if the third party clients want to make use of backwards compatibility, since it ensures they continue to receive consistent schemas.

  2. The order of elements within the interface schema and messages may change, within the constraints of the interface specification. Developers should avoid unnecessary dependence on the order of elements to interpret information exchanged with Cisco Unified Communications Domain Manager 10.6(1).

  3. New interface methods, operations, actions, requests, responses, headers, parameters, attributes, other elements, or new values of existing elements, may be introduced into the Cisco Unified Communications Domain Manager 10.6(1) interfaces. Developers should disregard or provide generic treatments where necessary for any unknown elements or unknown values of known elements encountered.

  4. Notifications, operations, methods, actions, requests, responses, headers, parameters, attributes, and other elements from previous versions ofCisco Unified Communications Domain Manager 10.6(1) interfaces, will remain, and will maintain their previous meaning and behavior to the extent possible and consistent with the need to correct defects.

  5. Applications should not be dependent on interface behavior resulting from defects (behavior not consistent with published interface specifications), since the behavior can change when defects are fixed.

  6. The use of deprecated methods, operations, actions, handlers, requests, responses, headers, parameters, attributes, or other elements should be removed from applications as soon as possible to avoid issues when those deprecated items are removed fromCisco Unified Communications Domain Manager 10.6(1) or its interfaces.

  7. Application Developers should be aware that not all new features and new supported devices (for example, phones) will be forward compatible. New features and devices may require application modifications to be compatible or to make use of the new features or devices.

Workflow Tasks

Procedure
    Step 1   Login with the username "hcsadmin@sys.hcs ", using the password that was set during the installation.
    Step 2   Get the Provider Name & Provider PKID using the data/HierarchyNode API in the url, where "hierarchy" = "sys.hcs".
    Step 3  
    Note   

    For all POST/PUT/DELETE operations to be asynchronous transactions, set the query param "nowait=true" in the URI.

    To create a provider Admin use the relation/HcsAdminUserREL API in the url, with the hierarchy value that you receive in the get call of Step-1 (pkid or the dot notation).
    Step 4  
    Note   

    Creating a Reseller is not mandatory, and it depends on the structure of provisioning. A Reseller must be created if the tree structure of the provisioning is : Provider -> Reseller -> Customer -> Site.

    To create a Reseller use the relation/HcsResellerREL API, with the Provider hierarchy of the API of Step-1.
    Step 5   To create a Reseller Admin use the relation/HcsAdminUserREL API in the url , with the hierarchy value of the Reseller (pkid or the dot notation).
    Step 6   To create a Shared Network Device (Call Manager or Unity), it needs to be done either at either the Provider Hierarchy or the Reseller Hierarchy Level. Use the following APIs for each of the devices listed below:
    Device API
    CallManager

    relation/HcsCallManagerREL

    Unity

    relation/HcsUnityConnectionREL

    Presence

    relation/HcsPresenceREL

    WebEx

    relation/HcsWebExREL

    Step 7  
    Note   

    The Customer will be directly under Provider if the deployment structure is Provider -> Customer -> Site or under the Reseller if the deployment structure is Provider ->Reseller ->Customer -> Site.

    To create a Customer use the relation/HcsCustomerREL API, with the hierarchy of provider/reseller that can be retrieved using the respective API.
    Step 8   To create a Customer Admin use the relation/HcsAdminUserREL API in the url, with the hierarchy value of the Customer(pkid or the dot notation).
    Step 9  
    Note   

    If the Customer is using "shared_uc_apps" then you cannot add dedicated devices for that customer.

    Adding a Dedicated Network Device for a Customer(Call Manager or Unity) needs to be done at the Customer hierarchy Level. Use the following APIs for each of the devices listed below:
    Device API
    CallManager

    relation/HcsCallManagerREL

    Unity

    relation/HcsUnityConnectionREL

    Presence

    relation/HcsPresenceREL

    WebEx

    relation/HcsWebExREL

    Step 10   Once the devices are configured a Network Device List (NDL) needs to be configured for the Customer. To create a NDL use the relation/HcsNetworkDeviceListREL API. At least one device is required to add an NDL.
    Step 11  
    Note   

    It is not mandatory to have a Network Device List (NDL) to create a Site. However, an NDL is needed to add a Subscriber or Phone or Lines to a Site. Sites created without an NDL can later be able associated to one.

    To create a site use the relation/HcsSiteREL API.
    Step 12  
    Note   

    Using the relation/HcsAdminUserREL API will only be local Cisco Unified Communications Domain Manager admin. To add an Admin who is also a Subscriber, use the relation/HcsUserREL API, which can later be moved to any Cisco Unified Communications Manager that is associated with the Site.

    To create a Site Admin use the relation/HcsAdminUserREL API in the url, with the hierarchy value of the Site (pkid or the dot notation).
    Step 13   Complete the following activities at the Site level:
    1. To create a Subscriber use the relation/Subscriber API.
    2. To create a Line use the view/HcsDNMgmtVIEW API.
    3. To create a Phone use the relation/SubscriberPhone API.
    4. To create a Voicemail use the relation/Voicemail API.

    Developer Tools

    The Developer tools that are available in Mozilla Firefox and Google Chrome allow all the actions exposed by each API to be displayed as they are being called in the GUI. This gives us the opportunity to view the request and response actions as they occur, and provide the details of what each API provides and its relationship to the GUI.

    With Developer tools enabled, the network tab of the Developer tools will show the information that is contained in each request and response as you navigate and use the GUI. This allows partners a direct view as to what data each API requires.