Cisco Unified Contact Center Enterprise Developer Reference, Release 12.6(1)

Machine Inventory API

This API returns the machines in the solution.

URL

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

Operations

create: Creates a machine by updating the database. See the following table for restrictions per machine type.
delete: Removes one machine.
get: Returns one machine and all associated addresses and services based on the machine ID, using the URL https://<server>/unifiedconfig/config/machineinventory/<id>.
list: Retrieves a list of all machines in the inventory. See the following table for more details.
update: Updates one machine.


Type	Create / Update / Delete operations allowed	Number allowed
CCE_ROUTER	No	0/1 Side A 0/1 Side B
CCE_PROGGER	No	0/1 Side A 0/1 Side B
CCE_CALL_SERVER	No	0/1 Side A 0/1 Side B
CCE_PG	No	0/150 Side A 0/150 Side B
LIVE_DATA	All	0/1 Side A 0/1 Side B
PRIMARY_AW	All	0/2 Primary
SECONDARY_AW	All	0/2 Secondary
CCE_AW	Update only	0/8 Primary
IDS_PUBLISHER	All	0 or more
IDS_SUBSCRIBER	No	0 or more
FINESSE_PRIMARY	All	0 or more
FINESSE_SECONDARY	Update and Delete only	0 or more
CUIC_PUBLISHER	All	0/1
CUIC_SUBSCRIBER	No	0/1
CUIC_PUBLISHER_STANDALONE	All	0 or more
CUIC_SUBSCRIBER_STANDALONE	Update and Delete only	0 or more
EXTERNAL_CUSTOMER_COLLABORATION_PLATFORM	All	0/1
CLOUD_CONNECTOR_PUB	All	0-1
CLOUD_CONNECTOR_SUB	No	0-1

Note

When you create a CUIC_PUBLISHER, CUIC_PUBLISHER_STANDALONE, or FINESSE_PRIMARY machine, any other machine in the cluster (CUIC_SUBSCRIBER, CUIC_SUBSCRIBER_STANDALONE, or FINESSE_SECONDARY) is automatically added to the inventory. When you delete a CUIC_PUBLISHER, CUIC_PUBLISHER_STANDALONE, or FINESSE_PRIMARY machine, any other machines in the cluster are also removed from the inventory.

CUIC_PUBLISHER and CUIC_SUBSCRIBER have Unified Intelligence Center, Live Data, and Cisco Identity Service installed on the same VM. These machines can only be used in the following deployment types:

UCCE: 2000 Agents
UCCE: Progger (Lab Only)
HCS-CC: 500 Agents (Deprecated)
HCS-CC: 2000 Agents

If you create a CUIC_PUBLISHER on a system that already contains a LIVE_DATA machine, the LIVE_DATA machine is deleted. If the system already contains a CUIC_PUBLISHER_STANDALONE or IDS_PUBLISHER machine, you receive an error message of error type INVENTORY_ONLY_ONE_CUIC_PUB_ALLOWED.

Parameters

Machine parameters:

refURL: The refURL of the machine. See Shared Parameters.
name: External name of the machine. For example, the VM hostname. 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.
autogenerated: Indicates if the information was generated automatically.
hostName: The hostname 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 section.

Network parameters:

type: Must be public.
versionInfo: Version info available depending on the product type. Includes the following parameters (by product type):
- UCCE: version, buildNumber, esNumber, patchVersion
- VOS: version and buildNumber
address: The IP address. Must be valid hostname, IPv4, or IPv6 address.
services: A collection of service parameters. See the Services Parameters section.

Services parameters:

uri: The service URL, for example MR_PG_A URL.

For MR_PG_A and MR_PG_B, the machines on which the MR PGs reside must be configured in the Machine Inventory:
- Most Unified CCE and HCS for Contact Center deployments use the CCE_PGs.
- Progger deployments use the CCE_PROGGERs.
- HCS500 and HCS1000 deployments use the CCE_CALL_SERVERs.
The URLs must be different, and must follow the pattern /unifiedconfig/config/machineinventory/<id>.
name: The hostname of service. This read-only parameter applies only to the MR_PG_A and MR__PG_B services. It is returned if the uri matches the unifiedconfig machine host (for example /unifiedconfig/config/machineinventory/1234 where 1234 is a valid id).
port: The port for this service.

For MR_PG_A and MR_PG_B, the default port is 38001, and the valid range is 10000 to 65535. If you do not specify a value or specify 0, the default port is used. MR_PG_A and MR_PG_B must use the same port.
username: The username used to access the service. Username maximum is 128 characters.
password: The password used to access the service. The password can be used when creating or updating, but is not returned.
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 Contact Share node, if the service type is ACTIVE_MQ, the pairing value contains the valid ApplicationGatewayID.

For the service type PRINCIPAL_AW, the pairing value is "false" for all AWs.
type: The service type. Values for type are as follows:
- LIVE_DATA_API: Connection information for the Live Data Rest API. Requires a username and password.
- LIVE_DATA_CASSANDRA: Connection information for the Live Data Cassandra database.
- LIVE_DATA_WEB_SOCKETS: Connection information for the Live Data Socket.IO service.
- TIP_PG: LiveData connection information for peripheral gateways.
- TIP_ROUTER: LiveData connection information for the router.
- TIP_PG_TOS: LiveData test-other-side connection information for peripheral gateways.
- TIP_ROUTER_TOS: LiveData test-other-side connection information for the router.
- ACTIVE_MQ: LiveData Active MQ connection information.
- STORM_DRPC: LiveData Storm DRPC connection information.
- AW_REST_API: Administration & Data Server (AW) Rest API
- SM_REST_API: Customer Collaboration Platform REST API. Requires a username and password.
- MR_PG_A: Connection information for Side A MR PG. Required for Customer Collaboration Platform machines.
- MR_PG_B: Connection information for the Side B MR PG. Required for Customer Collaboration Platform machines.
- MR_PG_CONNECTION: Connection information for the MR PG. Required for Customer Collaboration Platform machines.
- IDS: Indicates an Identity Server service. IDS contains the following parameters:
  - userName: The username of the IdS for the IDS_PUBLISHER machine.
  - 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.
  
  When you update the IDS_PRIMARY_REF service type of a machine, the IDS_SECONDARY_REF is automatically set to the other IdS in the cluster, if present.
- 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).
- PUBLISHER_REF: The <uri> parameter for this service refers to the publisher/primary machine's IP Address. This service is only applicable for subscriber/secondary machines.
- CLOUD_CONNECT_CREDINITIALS: Credinitial information for Cloud Connect Services.

Search and Sort Values

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


Search parameters	Sort parameters
name description hostName	name (default) description hostName

See Search and Sort.

Advanced search parameters

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

type:<machine type>: Returns only machines of the specified type. For example, type:EXTERNAL_CUSTOMER_COLLABORATION_PLATFORM returns only external Customer Collaboration Platform machines. The machine type is case-insensitive.
serviceType:<service type>: Returns only machines associated with the specified service type. For example, serviceType:IDS_PRIMARY_REF returns only SSO-capable machines.

Example Update Request

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

<machine>
  <name>myLiveDataMachine</name>
  <hostName>liveDataHostName</hostName>
  <type>LIVE_DATA</type>
  <networks>
    <network>
      <type>PUBLIC</type>
      <address>1.2.3.4</address>
      <services>
        <service>
          <type>ACTIVE_MQ</type>
          <port>61616</port>
          <pairing>1</pairing>
        </service>
        <service>
          <type>STORM_DRPC</type>
          <port>3772</port>
          <pairing>1</pairing>
        </service>
        <service>
          <type>LIVE_DATA_WEB_SOCKETS</type>
          <port>12008</port>
          <pairing>1</pairing>
        </service>
        <service>
          <type>LIVE_DATA_API</type>
          <port>12005</port>
          <pairing>1</pairing>
          <userName>user</userName>
          <password>password</password>
        </service>
        <service>
          <type>LIVE_DATA_CASSANDRA</type>
          <port>12000</port>
          <pairing>1</pairing>
        </service>
      </services>
    </network>
  </networks>
</machine>

Example Get Response

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

<machine>
  <changeStamp>3</changeStamp>
  <refURL>/unifiedconfig/config/machineinventory/5000</refURL>
  <networks>
    <network>
      <address>1.2.3.4</address>
      <services>
        <service>
          <autoGenerated>true</autoGenerated>
          <pairing>0</pairing>
          <port>40034</port>
          <type>TIP_ROUTER</type>
        </service>
        <service>
          <autoGenerated>true</autoGenerated>
          <pairing>0</pairing>
          <port>40035</port>
          <type>TIP_ROUTER_TOS</type>
        </service>
      </services>
      <type>PUBLIC</type>
    </network>
  </networks>
  <autoGenerated>true</autoGenerated>
  <hostName>routerA</hostName>
  <type>CCE_ROUTER</type>
  <name>routerA</name>
</machine>

Example Get Response for IdS

<machine>
  <changeStamp>1</changeStamp>
  <refURL>/unifiedconfig/config/machineinventory/5000</refURL>
  <name>IDS-PUB-A</name>
  <type>IDS_PUBLISHER</type>
  <networks>
    <network>
      <type>PUBLIC</type>
      <address>10.10.10.22</address>
      <services>
       <service>
        <type>IDS</type>
        <userName>Admin</userName>
        <components>
           <component>
              <refURL>/unifiedconfig/config/machineinventory/6000</refURL>
              <name>FIN-PUB-A</name>
           </component>
           <component>
              <refURL>/unifiedconfig/config/machineinventory/6001</refURL>
              <name>CUIC-PUB-A</name>
            </component>
         </components>
       </service>
      </services>
    </network>
  </networks>
</machine>

Example Update Request for Primary IdS

This example request updates the primary IdS for Finesse:

<machine>
  <changeStamp>1</changeStamp>
  <refURL>/unifiedconfig/config/machineinventory/5000</refURL>
  <name>Finesse primary</name>
  <type>FINESSE_PRIMARY</type>
  <networks>
    <network>
      <type>PUBLIC</type>
      <address>10.10.10.21</address>
      <services>
       <service>
        <type>IDS_PRIMARY_REF</type>
        <uri>/unifiedconfig/config/machineinventory/5001</uri>
       </service>
      </services>
    </network>
  </networks>
</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 updates the IDS_PRIMARY_REF and IDS_SECONDARY_REF of any SSO-capable components.

This operation also deassociates 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 was complete.

<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>

Bias-Free Language

Book Title

Cisco Unified Contact Center Enterprise Developer Reference, Release 12.6(1)

Chapter Title

Machine Inventory API

Results

Chapter: Machine Inventory API

Machine Inventory API

Machine Inventory API

URL

Operations

Parameters

Search and Sort Values

Example Update Request

Example Get Response

Example Get Response for IdS

Example Update Request for Primary IdS

Example Updating SSO-Capable Components Associated to an IdS

Was this Document Helpful?

Contact Cisco