Turbonomic Actions REST API

Edit online

To communicate with the Turbonomic Actions application from an external application, use the Turbonomic Actions REST API. You can run these operations:

  • Create Action Records (POST)

  • Create Action Approvals (POST)

  • Update Action Approvals (POST)

  • Search Action Approvals (PUT)

  • Get Application Settings API (GET)

Note:

API request payloads and the API responses are in jSON format.

Create action records

Adds new entries into the Turbonomic Actions records table. Use this API for Turbonomic actions that are recommended or are already run.

API request

POST
        /api/x_turbo_turbonomic/v1/action/records

Sample body

{
    "turbonomicInstance": 
    {
        "hostOrIP": "10.10.200.80",
        "status": "ONLINE",
        "version": "6.4.0-SNAPSHOT"
    },
    "actionRecords": [
        {
            "actionOid": "A1234567890",
            "details": "Hyper-V VM 1 Right Size Action Details",
            "targetEntity": 
            {
                "uuid": "vm-345",
                "name": "ACM-Hyper-V-VM-1",
                "type": "VIRTUAL_MACHINE",
                "targetName": "10.10.172.10",
                "targetIP": "10.10.172.10",
                "targetType": "hyper-v"
            },
            "actionLifeCycleEvent": "On Generation"
            … // Extra fields removed

        },
       {
            "actionOid": "B1234567890",
            "details": "vCenter VM 2 Right Size Action Details",
            "targetEntity": 
            {
                "uuid": "vm-367",
                "name": "ACM-L-Tomcat-VM-2",
                "type": "VIRTUAL_MACHINE",
                "targetName": "10.10.172.25",
                "targetIP": "10.10.172.25",
                "targetType": "vCenter"
            },
            "actionLifeCycleEvent": "On Generation"
            … // Extra fields removed
        }
    ]
}

Sample response

{
    "result": {
        "succeeded": [
            {
                "oid": "A1234567890"
            },
            {
                "oid": "B1234567890"
            }
        ],
        "failed": []
    }
}

Create action approvals

Create Turbonomic action approval records in ServiceNow for each Turbonomic action that requires approval. By default, this API creates a corresponding CR.

API request

POST
        /api/x_turbo_turbonomic/v1/action/approvals

Sample body

{
    "turbonomicInstance": 
    {
        "hostOrIP": "10.10.200.80",
        "status": "ONLINE",
        "version": "6.4.0-SNAPSHOT"
    },
    "actionApprovals": [
        {
            "oid": "A1234567890",
            "description": "vCenter VM 1 Right Size Action Description",
            "category": "Efficiency",
            "commodityName": "VMEM",
            "from": “2GB",
            "to": "1GB",
            "risk": "Action Risk Description",
            "savings": 123.45,
            "state": "PENDING_ACCEPT",
            "type": "RIGHT_SIZE",
            "timestampMsec": 123456789,
            "targetEntity":
            {
                "uuid": "vm-367",
                "name": "ACM-L-Tomcat1-172.25",
                "type": "VIRTUAL_MACHINE",
                "targetName": "vsphere-dc1.corp",
                "targetType": "vCenter"
            }
        }
        … // Extra fields removed
    ]
}

Sample Response

{
    "result": {
        "succeeded": [
            {
                "oid": " A1234567890",
                "changeRequestId": "eda81daedbcbb3005e691fe9689619e1",
                "changeRequestNumber": "CHG0049469",
                "state": "PENDING_APPROVAL"
            }
        ],
        "failed": []
    }
}

Update action approvals

Modify existing action approval records created by Turbonomic Actions.

API request

PUT
        /api/x_turbo_turbonomic/v1/action/approvals

Sample body

{
    "turbonomicInstance": 
    {
        "hostOrIP": "10.10.200.80",
        "status": "ONLINE",
        "version": "6.4.0-SNAPSHOT"
    },
    "actionApprovalUpdates": [
        {
            "oid": "A1234567890",
            "description": "vCenter VM 1 Right Size Action Description",
            "category": "Efficiency",
            "commodityName": "VMEM",
            "from": “2GB",
            "to": "1GB",
            "risk": "Action Risk Description",
            "savings": 123.45,
            "state": "PENDING_ACCEPT",
            "type": "RIGHT_SIZE",
            "timestampMsec": 123456789,
            "targetEntity":
            {
                "uuid": "vm-367",
                "name": "ACM-L-Tomcat1-172.25",
                "type": "VIRTUAL_MACHINE",
                "targetName": "vsphere-dc1.corp",
                "targetType": "vCenter"
            }
        }
    ]
}

Sample response

{
    "result": {
        "succeeded": [
            {
                "oid": " A1234567890",
                "changeRequestId": "eda81daedbcbb3005e691fe9689619e1",
                "changeRequestNumber": "CHG0049469",
                "state": "PENDING_APPROVAL"
            
        ],
        "failed": []
    }
}

Search action approvals

Find a Turbonomic action approval record in ServiceNow.

You can include the addAllApprovalsInTransition parameter in the Search call. If you set it to true, the search result includes all approvals that are in one of these states:

  • APPROVED
  • IN_PROGRESS
  • WAITING_FOR_EXEC
  • WAITING_FOR_CR_SCHEDULE

API request

POST
        /api/x_turbo_turbonomic/v1/action/search/approvals?addAllApprovalsInTransition=false

Sample body

{
    "turbonomicInstance": 
    {
        "hostOrIP": "10.10.200.80",
        "status": "ONLINE",
        "version": "6.4.0-SNAPSHOT"
    },
      "oids": 
    [
        "A1234567890”, "B1234567890”
    ]
}

Sample response

{
    "result": {
        "succeeded": [
            {
                "oid": " A1234567890",
                "state": "PENDING_APPROVAL"
            },
            {
                "oid": " B1234567890",
                "state": "PENDING_APPROVAL"
            }
        ],
        "failed": []
    }
}

Get application settings API

Use this API to retrieve application settings, including general configuration settings, CI matching definitions, and application table statistics. This information can be used to review the current application configuration and monitor table usage.

API request

GET
        /api/x_turbo_turbonomic/action/settings

Sample body

{
     "turbonomicInstance":
 {
 "hostOrIp": "10.10.204.62",
 "status": "ONLINE",
 "version": "8.20.2"
 }
}

Sample response

{
    "result": {
 "general": [
 {
 "MatchingCRType": "normal",
 "CRClosedCodeForMissedApprovals": "unsuccessful",
 "PopulateUserAndGroupForCR": "false",
 "AssignedCRUser": "",
 "AssignedCRGroup": "",
 "ApprovedCRState": "-2",
 "ImplementCRState": "-1",
 "ClosedCRState": "3",
 "CancelledCRState": "4"
 }
 ],
 "ci_matchings": [
 {
 "Name": "CI matching for HyperV VM",
 "TargetTypeId": "b2f9aae78713965074f08666cebb35b2",
 "TargetTypeName": "Hyper-V",
 "EntityTypeId": "757ae22b8713965074f08666cebb3581",
 "EntityTypeName": "VirtualMachine",
 "CITableName": "cmdb_ci_hyper_v_instance",
 "CITableColumn": "correlation_id",
 "IsUserProvidedTableName": "false",
 "UserTableName": ""
 }
 ],
 "tables": [
 {
 "Name": "x_turbo_turbonomic_turbonomic_action_approval",
 "NrOfRecords": "460835"
 },
 {
 "Name": "x_turbo_turbonomic_turbonomic_action_record",
 "NrOfRecords": "7872"
 }
 ]
 }
}