# Central Management Environments

In this sub-section, you will learn how to programmatically create, modify, delete and view Central Management Environment entries.

The CME provides a single point of access for Akixi Administrators to view, manage and administrate all their Akixi customers from within a single environment.

The CME also has the added benefit of allowing Akixi Administrators to access billing for all customer sites from a single location.

A CME is a container environment, that can hold any number of Telephony Servers, Application Users and even other CMEs, with each CME having the ability to be associated to a single company. The top-level CME is known as the Primary CME, this is where Administrators can sign in to manage their entire Akixi estate.

# Supported Operations

The list of currently supported Central Management Environment Server operations is provided below. Operations related to Akixi Central Management Environment entries start with a “CMEnvironment” prefix. They will be referred to as “CM Environment Operations” interchangeably hereafter.

Please note that depending on your assigned CM Environment system privileges you may only have access to view and configure one particular CM Environment entry. Refer back to the application administrator that created your particular User account in order to gain additional privileges.

# Central Management Environment Request Parameters

Parameters used within both CMEnvironmentAdd and CMEnvironmentChange requests can be found in the table below.

# Read-Only Properties After Initial Creation

# CMEnvironmentAdd

CM Environments are added via CMEnvironmentAdd request. The main purpose of this request is to create a new central management environment that is later used to group other CM Environments and telephony servers.

# CMEnvironmentAdd Request

The following request body shows an example of a CMEnvironmentAdd operation. This request includes all parameters supported by CMEnvironmentAdd operation invoked in order to create new CM Environment.

<Request Operation="CMEnvironmentAdd">
    <InvokeID>2334</InvokeID>
    <SessionID>EF5AF612C0A711112446BC9BE4B1BB94</SessionID>
    <OperationPayload>
        <Property Name="Description">New Central Management Environment</Property>
        <Property Name="CommunicationActivated">True</Property>
        <Property Name="ServerIPAddress">127.0.0.1</Property>
        <Property Name="ServerTCPPort">8099</Property>
        <Property Name="FromAddressEmail">test@test.com</Property>
        <Property Name="FromAddressName">From Test Address</Property>
        <Property Name="CompanyName">Test Company Name</Property>
        <Property Name="UseAuthentication">true</Property>
        <Property Name="AuthUsername">Test AuthUsername</Property>
        <Property Name="AuthPassword">PnmVkSF9HmGdcBFn/38Bbg==aaaa</Property>
        <Property Name="Domain">unknown.akixi.com</Property>
        <!-- Parent cannot be subsequently changed. -->
        <Property Name="ParentCMEnvironmentID">d6d6c5a5f0f90d60:-15617a00:169f533f6d5:5613</Property>
        <Property Name="BillingTag">Test billing tag</Property>
        <Container Name="ProvisioningConfig">
            <Container Name="BroadworksProvisioning">
                <ListContainer Name="ServicePacks">
                    <Container Name="ServicePacksEntry">
                        <Property Name="Enabled">true</Property>
                        <Property Name="ItemType">EXTENSION</Property>
                        <Property Name="TelSysIDs">1</Property>
                        <Property Name="Value">Test ServicePackValue</Property>
                    </Container>
                    <Container Name="ServicePacksEntry">
                        <Property Name="Enabled">true</Property>
                        <Property Name="ItemType">HOSPITALITY</Property>
                        <Property Name="TelSysIDs">1-11</Property>
                        <Property Name="Value">Test ServicePackValue</Property>
                    </Container>
                </ListContainer>
            </Container>
        </Container>
        <!-- Applicable only for MS Teams server. -->
        <Container Name="LicenseCapManagement">
            <Property Name="EssentialsCap">20</Property>
            <Property Name="ProfessionalCap">15</Property>
            <Property Name="EnterpriseCap">10</Property>
        </Container>
        <Property Name="Capabilities">1795</Property>
        <Property Name="MaxTelsysCount">-1</Property>
    </OperationPayload>
</Request>

Depending on your initial requirements, your actual request might be shorter than the sample request above. For example, it is normally not required to specify billing ID or Provisioning Config.

You can specify a service pack value for "ItemType" property within "BroadworksProvisioning" container from the ones listed below:

1. EXTENSION
2. HOSPITALITY
3. ACD_AGENT
4. ESSENTIALS
5. PROFESSIONAL
6. ENTERPRISE
7. CALL_CENTRE_AGENT
8. CALL_CENTRE_SUPERVISOR

Note: Service packs ESSENTIALS, PROFESSIONAL, ENTERPRISE, CALL_CENTRE_AGENT and CALL_CENTRE_SUPERVISOR require TelSysID(s) containing Enterprise sites.

# CMEnvironmentAdd Response

If your operation was successful, you will receive a response similar to the following:

<Response Result="Success">
    <InvokeID>2334</InvokeID>
</Response>

You will now be able to access the newly created Central Management Environment entry by invoking other CMEnvironmentXXX requests that will include its unique identifier (CMEnvironmentID). The Central Management Environment can also be viewed & modified under the Administration “CM Environments” area of the Akixi Service administration portal.

If the request was unsuccessful (i.e. the response’s Result attribute depicts the “Fail” value), then the response’s error code and the message description values should be parsed by the client application and then handled accordingly. Some common errors returned by this operation are provided in the table below:

Please refer to the “Error Codes” chapter for further details on specific error codes and their meaning.

# CMEnvironmentChange

Central Management Environment components can be modified via CMEnvironmentChange request. To modify parameters of an existing Central Management Environment, you must build a request that will include corresponding component’s unique identifier CMEnvironmentID, as well as the Properties to actually update.

# CMEnvironmentChange Request Parameters

Please note that certain CMEnvironmentChange parameters are read-only after creation - therefore, you are not able to update them.

Parameters used within the CMEnvironmentChange request can be found in the table previously given against the “Central Management Environment Request Parameters” sub-heading.

# CMEnvironmentChange Request

The following request body shows an example of a CMEnvironmentChange operation.

<Request Operation="CMEnvironmentChange">
    <InvokeID>2334</InvokeID>
    <SessionID>EF5AF612C0A711112446BC9BE4B1BB94</SessionID>
    <OperationPayload>
        <Property Name="CMEnvironmentID">d6d6c5a5f0f90d60:-15617a00:169fd0b0646:3045</Property>
        <Property Name="Description">Updated Central Management Environment</Property>
        <Property Name="CommunicationActivated">True</Property>
        <Property Name="ServerIPAddress">127.0.0.1</Property>
        <Property Name="ServerTCPPort">8099</Property>
        <Property Name="FromAddressEmail">test@test.com</Property>
        <Property Name="FromAddressName">From Test Address</Property>
        <Property Name="CompanyName">Test Company Name</Property>
        <Property Name="UseAuthentication">true</Property>
        <Property Name="AuthUsername">Test AuthUsername</Property>
        <Property Name="AuthPassword">PnmVkSF9HmGdcBFn/38Bbg==aaaa</Property>
        <Property Name="Domain">unknown.akixi.com</Property>
        <Property Name="BillingTag">Test billing tag</Property>
        <Container Name="ProvisioningConfig">
            <Container Name="BroadworksProvisioning">
                <ListContainer Name="ServicePacks">
                    <Container Name="ServicePacksEntry">
                        <Property Name="Enabled">true</Property>
                        <Property Name="ItemType">EXTENSION</Property>
                        <Property Name="TelSysIDs">1,2,3</Property>
                        <Property Name="Value">Test ServicePackValue</Property>
                    </Container>
                </ListContainer>
            </Container>
        </Container>
        <Property Name="Capabilities">1795</Property>
        <Property Name="MaxTelsysCount">-1</Property>
        <!-- Applicable only for MS Teams server. -->
        <Container Name="LicenseCapManagement">
            <Property Name="EssentialsCap">3</Property>
            <Property Name="ProfessionalCap">2</Property>
            <Property Name="EnterpriseCap">5</Property>
        </Container>
    </OperationPayload>
</Request>

Depending on your initial requirements, your actual request might be shorter than the sample request above.

You can specify a service pack value for "ItemType" property within "BroadworksProvisioning" container from the ones listed below:

1. EXTENSION
2. HOSPITALITY
3. ACD_AGENT
4. ESSENTIALS
5. PROFESSIONAL
6. ENTERPRISE
7. CALL_CENTRE_AGENT
8. CALL_CENTRE_SUPERVISOR

Note: Service packs ESSENTIALS, PROFESSIONAL, ENTERPRISE, CALL_CENTRE_AGENT and CALL_CENTRE_SUPERVISOR require TelSysID(s) containing Enterprise sites.

# CMEnvironmentChange Response

If your operation was successful, you will receive a response similar to the following:

<Response Result="Success">
    <InvokeID>2334</InvokeID>
</Response>

If the request was unsuccessful (i.e. the response’s Result attribute depicts the “Fail” value), then the response’s error code and the message description values should be parsed by the client application and then handled accordingly. Some common errors returned by this operation are provided in the table below:

Please refer to the “Error Codes” chapter for further details on specific error codes and their meaning.

# CMEnvironmentDelete

Akixi Central Management Environment component can be removed via CMEnvironmentDelete request. To delete a specific Central Management Environment entry, you must build a request that will include the corresponding entry’s unique identifier value (CMEnvironmentID), as well as any required optional deletion parameters.

Only empty (i.e. no child CM Environments, no telephony servers) Central Management Environment components can be deleted.

# CMEnvironmentDelete Request

The example request below is an example of a CM Environment deletion operation. This request includes all parameters supported by CMEnvironment operation invoked in order to delete an existing entry (where CMEnvironmentID=67111f4833d46afc:13698559:178111e794b:-7f4c).

<Request Operation="CMEnvironmentDelete">
    <InvokeID>2334</InvokeID>
    <SessionID>60C7FEA78894398D635C76F4ACB473CB</SessionID>
    <OperationPayload>
        <Property Name="CMEnvironmentID">67111f4833d46afc:13698559:178111e794b:-7f4c</Property>
    </OperationPayload>
</Request>

# CMEnvironmentDelete Response

If your operation was successful, you will receive a response similar to the following:

<Response Result="Success">
    <InvokeID>2334</InvokeID>
</Response>

If the request was unsuccessful (i.e. the response’s Result attribute depicts the “Fail” value), then the response’s error code and the message description values should be parsed by the client application and then handled accordingly. Some common errors returned by this operation are provided in the table below:

Please refer to the “Error Codes” chapter for further details on specific error codes and their meaning.

# CMEnvironmentList

CMEnvironmentList operation can be used to list all CM Environment components that are configured against a certain Administrative account.

# CMEnvironmentList Request

By default, the CMEnvironmentList request body is quite minimalistic: you can simply provide correct SessionID and InvokeID values in order to obtain CMEnvironmentID and Description parameters of CM Environment components configured against your Administrative account:

<Request Operation="CMEnvironmentList">
    <InvokeID>2334</InvokeID>
    <SessionID>5F433E65DBB2F619AF7FDC8F1D1EB5FD</SessionID>
</Request>

You can obtain additional CMEnvironment-related parameters by providing their names within a CMEnvironmentFields Payload Property (as a comma-separated string). If you want to only list CM Environments containing a specific CMEnvironmentID or Description, you can request for it via SearchQuery Payload Property. The Offset and Limit parameters can also be specified to request a specific subsection of the listed entries (if not specified these values are assumed to be 0 and 1000 respectively). Offset defines how many entries to skip over (i.e. which entry to start on if the first entry is entry 0) and Limit defines how many entries to retrieve. The example below will return all additional parameters supported by the CMEnvironmentList operation (as well as default parameters, i.e. CMEnvironmentID and Description), and retrieve 20 entries after skipping the first 100.

<Request Operation="CMEnvironmentList">
    <InvokeID>2334</InvokeID>
    <SessionID>5F433E65DBB2F619AF7FDC8F1D1EB5FD</SessionID>
    <Offset>100</Offset>
    <Limit>20</Limit>
    <OperationPayload>
        <Property Name="CMEnvironmentFields">Domain,CompanyName,ParentCMEnvironmentID</Property>
        <!-- Optional property to list CM Environments containing a specific CMEnvironmentID or Description. -->
        <Property Name="SearchQuery">Add CMEnvironmentID or Description to query</Property>
    </OperationPayload>
</Request>

The CMEnvironmentList operation can only return the following CM Environment Server component Properties:

• CMEnvironmentID *
• Description *
• Domain
• CompanyName
• ParentCMEnvironmentID

Parameters marked with an asterisk (*) are returned by default (i.e. it is not required to specify them via the CMEnvironmentFields Property).

# CMEnvironmentList Response

If a CMEnvironmentList operation was successful, you will receive a list of CM Environments and their properties. If additional parameters were not provided within your request, you will receive default properties of all CM Environments (i.e. CMEnvironmentID and Description). If additional fields were requested (via the CMEnvironmentFields Property), corresponding values will also be returned in operation’s response. If SearchQuery Payload Property was request for, then operation's response will only contain CM Environments whose default properties match the search query provided:

        <Response Result="Success">
    <InvokeID>2334</InvokeID>
    <Success>
        <Container>
            <Property Name="CMEnvironmentID">d6d6c5a5f0f90d60:-15617a00:169f533f6d5:5613</Property>
            <Property Name="Description">Akixi</Property>
            <Property Name="Domain">unknown.akixi.com</Property>
            <Property Name="CompanyName">Akixi</Property>
            <Property Name="ParentCMEnvironmentID"/>
        </Container>
        <Container>
            <Property Name="CMEnvironmentID">75eb9ce1505c6636:4df14859:17eb55fcea6:-7882</Property>
            <Property Name="Description">Central Management Environment</Property>
            <Property Name="Domain">unknown.akixi.com</Property>
            <Property Name="CompanyName">Akixi</Property>
            <Property Name="ParentCMEnvironmentID">d6d6c5a5f0f90d60:-15617a00:169f533f6d5:5613</Property>
        </Container>
    </Success>
</Response>

If the request was unsuccessful (i.e. the response’s Result attribute depicts the “Fail” value), then the response’s error code and the message description values should be parsed by the client application and then handled accordingly. Some common errors returned by this operation are provided in the table below:

Please refer to the “Error Codes” chapter for further details on specific error codes and their meaning.

# CMEnvironmentInfo

The CMEnvironmentInfo request can be used to obtain information related to a specific CM Environment entry. You must simply provide a correct component identifier number value (CMEnvironmentID) within your request in order to get all underlying parameters of the corresponding Central Management Environment entry.

# CMEnvironmentInfo Request

The TelSysInfo request body is quite minimalistic: it includes two operation-specific parameters, as shown below:

<Request Operation="CMEnvironmentInfo">
    <InvokeID>2334</InvokeID>
    <SessionID>4AC9C2064E168EF0E9BDFD16E760E844</SessionID>
    <OperationPayload>
        <Property Name="CMEnvironmentID">aed4ee70b31854c9:-2d3a82d0:17e6cab5279:-7dde</Property>
    </OperationPayload>
</Request>

# CMEnvironmentInfo Response

If a CMEnvironmentInfo operation is successful, you will receive a list of all the corresponding Central Management Environment component’s property values.

<Response Result="Success">
    <InvokeID>2334</InvokeID>
    <Success>
        <Property Name="CMEnvironmentID">aed4ee70b31854c9:-2d3a82d0:17e6cab5279:-7dde</Property>
        <Property Name="Domain">unknown.akixi.com</Property>
        <Property Name="Description">Akixi</Property>
        <Property Name="CommunicationActivated">True</Property>
        <Property Name="ServerIPAddress">127.0.0.1</Property>
        <Property Name="ServerTCPPort">25</Property>
        <Property Name="FromAddressEmail">do_not_reply@akixi.com</Property>
        <Property Name="FromAddressName">Akixi Application Mailer (Do Not Reply)</Property>
        <Property Name="CompanyName">Akixi</Property>
        <Property Name="UseAuthentication">False</Property>
        <Property Name="AuthUsername"/>
        <Property Name="ParentCMEnvironmentID">d6d6c5a5f0f90d60:-15617a00:169f533f6d5:5613</Property>
        <Property Name="BillingTag"/>
        <Container Name="ProvisioningConfig">
            <Container Name="BroadworksProvisioning"/>
        </Container>
        <Property Name="Capabilities">1795</Property>
        <Property Name="MaxTelsysCount">-1</Property>
    </Success>
</Response>

If the request was unsuccessful (i.e. the response’s Result attribute depicts the “Fail” value), then the response’s error code and the message description values should be parsed by the client application and then handled accordingly. Some common errors returned by this operation are provided in the table below:

Please refer to the “Error Codes” chapter for further details on specific error codes and their meaning.