Machine Inventory API

URL

Operations

• create: Creates a machine by updating the database. See table below for restrictions per machine type. Create is allowed for external machines types only.

• delete: Removes one machine.

  Note	You cannot delete the Virtualized Voice Browser (VVB), Unified SIP Proxy and Gateway external machines if they are associated with a SIP Server Group. To delete these external machines, you must disassociate them from the SIP Server Group. You cannot delete a Principal VVB.

• get: Returns one machine and all associated addresses and services based on machine ID, using the URL https://<server>/unifiedconfig/config/machineinventory/<id>.

  • status: Returns any alerts indicating errors in the state of the inventory, using the URL https://<server>/unifiedconfig/config/machineinventory/status.

  • stats: Returns CVP Call Server and VXML Server statistics based on the machine type, using the URL https://<server>/unifiedconfig/config/machineinventory/<machine_id>/stats.

• list: Retrieves a list of all machines in the inventory. See table below for more details.

• update: Updates one machine.

Parameters

Machine parameters:

• refURL: The refURL of the machine. See Shared Parameters.

• name: External name of the machine. For example, the VM host name. Valid characters are period (.), hyphen (-), underscore (_), and alphanumeric. The first character must be alphanumeric. Maximum length is 128 characters.

• changeStamp: See Shared Parameters.

• type: The type of machine.

• versionInfo: Version info available depending on product type. Includes the following parameters (by product type):

  • UCCE: version, buildNumber, esNumber, patchVersion

  • CVVB: version and buildNumber

  • CVP: version, buildNumber, buildDate, esNumber, srNumber, dropNumber

  • VOS: version and buildNumber

  • Gateway: version

• vmhost: A reference to a machine of type VM_HOST, including refURL and name. See References.

• autogenerated: Indicates if the information was generated automatically.

• hostName: The host name of the machine.

  • If you provide a hostname, a lookup is performed to find the FQDN for that host. If the FQDN is found, the hostName field is then set to that FQDN value and the Machine Address is set to the IP address corresponding to the hostname.

  • If you do not provide a hostname, a lookup is performed using the address field in the API request. If the FQDN is found, the hostName field is set to that FQDN value.

• networks: A collection of network parameters. See the network parameters below.

• vmInstanceUuid: A unique identifier for the virtual machine.

Network parameters:

• type: Public or private. Private networks are only specified for CCE_PG and CCE_ROGGER.

• address: The IP address. Must be valid hostname, IPV4, or IPV6 address.

• services: A collection of service parameters. See the services parameters below.

Services parameters:

• uri: The service URL, for example, Diagnostic Portal URL or management console link.

• port: The port for this service.

• password: The password used to access the service. The password can be used when creating or updating, but is not returned.

• enablePassword: Used for gateways.

• description: The description of the service. See Shared Parameters.

• pairing: Indicates if services on different machines are related. Related services have a matching value.

  For the service type PRINCIPAL_AW, the pairing value is "true" for the AW that manages credentials for the features, and "false" for all other AWs.

  For the service type PRINCIPAL_VVB, the pairing value is "true" for the VVB that manages configurations for the feature like Customer Virtual Assistant, and is "false" for all other VVBs.

  For the service type MEDIA_SERVER, the following pairing values are supported:

  • True: Indicates CVP is enabled as a Media Server.

  • False: Indicates CVP is disabled as a Media Server.

  For the service type FTP_CREDENTIAL, the following pairing values are supported:

  • True: Indicates FTP is enabled on the Media Server.

  • False: Indicates FTP is disabled on the Media Server.

• username: The username used to access the service. Username maximum is 128 characters.

  For the service type FTP_CREDENTIAL, the userName Anonymous indicates that anonymous access is enabled on the FTP Server.

• For the machine types EXTERNAL_THIRD_PARTY_GATEWAY and DC_EXTERNAL_THIRD_PARTY_GATEWAY username and password are not required.

• status: Used to indicate the status of the machine which are of type CVP_WSM, DIAGOSTIC_PORTAL, or CVVB.

• type: The service type. Values for type are as follows:

  • ESXI: VM Host running ESXi server for connection to interrogate for VMs.

  • AXL: AXL connection information for Unified CM. Required for UCM Publisher.

  • DIAGNOSTIC_PORTAL: For CCE and Unified CVP, this is the Diagnostic Portal API. For Finesse and Unified Intelligence Center, this is the SOAP API. Required for CCE_AW on side A, CVP Reporting Server, CUSP and FINESSE on side A, and CUIC Publisher.

  • CVP_WSM: Connection information for CVP Servers.

  • MEDIA_SERVER: Indicates Media Server service on CVP.

  • FTP_CREDENTIAL: Connection information for FTP service on the Media Server.

  • GATEWAY: Connection information for gateways.

  • CVVB: Provides connection information of the external CVVB machines.

  • MANAGEMENT_LINK: Provides a URL of the management console for the machine.

  • PRINCIPAL_VVB: Indicates the VVB that manages configurations for the feature like Customer Virtual Assistant.

  • TIP_PG: LiveData connection information for peripheral gateways.

  • TIP_ROUTER: LiveData connection information for the router.

  • ADMINISTRATION: Connection information for administrative access. Required for CVP OAMP.

  • SM_REST_API: SocialMiner REST API.

  • IDS: Indicates an Identity Server service. IDS contains the following parameters:

    • components: Information about the component, including the component refURL and component name.

  • IDS_PRIMARY_REF: When present, the <uri> parameter for this service refers to the primary Identity Server (IdS) to which this component is associated.

  • IDS_SECONDARY_REF: Read only. The <uri> parameter for this service refers to the backup IdS to which this component is associated. For a create or update request, this field is automatically filled with the refURL of the secondary IdS (if present).

  • MR_PG_CONNECTION: Connection information for the MR PG.

  • VRU_PG_CONNECTION: Connection information for the VRU PG.

  • UCM_PG_CONNECTION: Connection information for the UCM PG.

  • DATA_CENTER_REF: Read only. Contains information for the Data Center machine.

  • PRINCIPAL_AW: Indicates the AW that manages credentials for the features.

Search and Sort Values

The following table shows the parameters that are searched and the parameters that are sortable.

See Search and Sort.

Advanced search parameters

You can perform a machine type search or a service type search on the Machine Inventory API:

• types: (machine_type1 | machine_type2 | machine_type3...): Returns all the machines of the specified type. For example, types:(VM_HOST | EXTERNAL_SOCIAL_MINER | PUB_SUBSCRIBER) returns all the machines that belong to any of the specified machine types. The machine type is case-insensitive.

• datacenters: (dc1|dc2|dc3...): Returns machines which belong to any of the specified data center. The data center names are fully matched (case-insensitive, no partial matches). Searching for "core" returns all machines in the core data center.

• serviceType:<service type>: Returns only machines associated with the specified service type. For example, serviceType:IDS_PRIMARY_REF returns only SSO-capable machines.

• peripheralsets: (ps1|ps2|ps3...): Returns machines which belong to any of the specified peripheral sets. The peripheral set names are fully matched (case-insensitive, no partial matches).

• ipaddress: <IP address>: Returns machines that are configured with the specified IP address in the inventory. You can even specify a partial IP address to search. Search includes both public and private IP addresses.

Example Inventory Status Response

https://<server>/unifiedconfig/config/machineinventory/status

Copy<status>
   <alerts>
      <alert>
         <apiErrors>
            <apiError>
               <errorData>CM_PUBLISHER</errorData>
               <errorMessage>CM_PUBLISHER not found on vmhost sideA</errorMessage>
               <errorType>inventory.MissingMachine</errorType>
            </apiError>
         </apiErrors>
         <machine>
            <host>sideA</host>
            <type>CM_PUBLISHER</type>
         </machine>      
      </alert>
   </alerts>
   <scanInfo>
      <lastScanDateTime>1374842924017</lastScanDateTime>
      <scanState>Idle</scanState>
   </scanInfo>
</status>

Example Stats Response

https://<server>/unifiedconfig/config/machineinventory/<machine_id>/stats

Copy<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<statistics>
    <callServer>
        <icmStats>
         ....
        </icmStats>
        <infrastrutureStats>
         ....   
        </infrastrutureStats>
        <sipStats>
         ...   
        </sipStats>
    </callServer>
    <vxmlServer>
        <infraStructure>
         ...
        </infraStructure>
        <ivr>
         ...
        </ivr>
        <vxml>
         ...
        </vxml>
    </vxmlServer>
</statistics>

Example Get Response

https://<server>/unifiedconfig/config/machineinventory/<id>

Copy<machine>
    <changeStamp>4</changeStamp>
    <refURL>/unifiedconfig/config/machineinventory/12073</refURL>
    <networks>
        <network>
            <address>10.10.10.21</address>
            <services>
                <service>
                    <autoGenerated>false</autoGenerated>
                    <port>7890</port>
                 <status>OUT_OF_SYNC</status>
                    <type>DIAGNOSTIC_PORTAL</type>
                    <userName>user@domain</userName>
                </service>
		   <service>
                    <type>MEDIA_SERVER</type>
                    <pairing>true</pairing>
                </service>
                <service>
                    <autoGenerated>false</autoGenerated>
                    <port>56</port>
                    <pairing>true</pairing>
                    <type>FTP_CREDENTIAL</type>
                    <userName>Anonymous</userName>
                    <password />
                </service>
            </services>
            <type>PUBLIC</type>
        </network>
    </networks>
    <autoGenerated>false</autoGenerated>
    <hostName>CCE-AW-1-21</hostName>
    <type>CCE_AW</type>
    <versionInfo>
        <buildNumber>03297</buildNumber>
        <version>11.0(1)</version>
    </versionInfo>
    <name>WJ2-AW-1</name>
    <vmHost>
        <refURL>/unifiedconfig/config/machineinventory/12071</refURL>
        <name>sideA</name>
    </vmHost>
    <vmInstanceUuid>50290e07-fa3d-2667-b84b-1c35989000e2</vmInstanceUuid>
</machine>

Example Updating SSO-Capable Components Associated to an IdS

SSO-capable components can be associated to an IdS with the <components> element. For example, a PUT request like this will update the IDS_PRIMARY_REF and IDS_SECONDARY_REF of any SSO-capable components. Note that refURLs of any on-box PCCE machines will be ignored as these cannot be changed. An example of an off-box PCCE machine is the EXTERNAL_HDS machine.

This operation will also de-associate any existing component references to that IdS that aren’t in the list. For example, if there were three components associated to this IdS before the operation, only two components would be associated after the operation is complete.

Copy<machine>
    <changeStamp>1</changeStamp>
    <refURL>/unifiedconfig/config/machineinventory/5000</refURL>
    <networks>
        <network>
            <type>PUBLIC</type>
            <address>10.10.10.22</address>
            <services>
                <service>
                    <type>IDS</type>
                    <components>
                        <component>
                            <refURL>/unifiedconfig/config/machineinventory/6000</refURL>
                        </component>
                        <component>
                            <refURL>/unifiedconfig/config/machineinventory/6001</refURL>
                        </component>
                    </components>
                </service>
            </services>
        </network>
    </networks>
</machine>