Sample payload for BYOL
Summarize
Summary of Sample payload for BYOL
This document provides a sample payload example to populate theSoftware Installation [cmdbsamswinstall]table in ServiceNow using discovery data collected through the Bring Your Own License (BYOL) licensing model. It is designed to work with Software Asset Connection as a third-party discovery source, ensuring proper integration and data relationships between cloud service accounts, datacenters, hosts, virtual machines, computers, and software installations.
Show less
The payload highlights the hierarchical dependencies and mandatory fields required for entities across AWS and Azure environments, ensuring accurate representation of cloud and virtual assets within ServiceNow's Configuration Management Database (CMDB).
Key Entities and Required Fields
- Cloud Service Account [cmdbcicloudserviceaccount]: Top-level entity, requires a unique
accountid. - AWS Datacenters [cmdbciawsdatacenter] and Azure Datacenters [cmdbciazuredatacenter]: Require unique
objectid. - Cloud Hosts [cmdbcicloudhost]: Required for dedicated hosts, with fields like
objectid,name, and platform-specific fields such ascpucorecountfor AWS andhosttypefor Azure. - Virtual Machine Instances [cmdbcivminstance]: Identified by
objectid. - Computers [cmdbcicomputer]: Fields include
name, CPU-related counts, and a booleanvirtualflag indicating VM status. - Software Installations [cmdbsamswinstall]: Includes software details like
publisher,version,displayname, and license information such ascloudlicensetypeset to BYOL and source set tothirdpartyintegration.
Entity Relationships for BYOL
Proper relationships between entities must be established in the payload to ensure data integrity:
- Hosted on::Hosts: Connects AWS/Azure Datacenters to Cloud Service Accounts, Cloud Hosts, and Virtual Machine Instances.
- Runs on::Runs: Links Virtual Machine Instances to Cloud Hosts.
- Virtualized by::Virtualizes: Associates Computers with Virtual Machine Instances.
Each dependent entity must include its parent entity and the relationship type within the same payload, even if the parent entity exists in the instance.
Sample Payload Usage
The payload example demonstrates how to send a dedicated virtual machine’s data, including:
- A computer record representing the VM with CPU details and virtual flag.
- Related software installations for that VM.
- Corresponding VM instance, cloud host, AWS datacenter, and cloud service account entries.
For multiple dedicated VMs, each requires a separate REST API call with a similar structured payload. All software installations on a dedicated VM can be included in a single payload’s related array.
Practical Application for ServiceNow Customers
This payload format enables customers to integrate BYOL licensing data from third-party discovery sources into ServiceNow’s Software Asset Management. By adhering to the required fields and relationships, customers can:
- Ensure accurate and consistent population of software installations and related cloud infrastructure in their CMDB.
- Maintain clear lineage and context between cloud accounts, datacenters, hosts, virtual machines, and software.
- Leverage the Software Asset Connection framework for unified license tracking and compliance.
The payload also demonstrates how to use the SNC.IdentificationEngineScriptableApi.createOrUpdateCIEnhanced API method to create or update CIs programmatically within ServiceNow.
A sample payload that populates the Software Installation [cmdb_sam_sw_install] table in the ServiceNow instance with discovery data collected by the BYOL licensing model.
Certain entities need to be populated for BYOL to work with software asset connection as a third party discovery source. The relationship between these entities is crucial for BYOL to work smoothly with software asset connections. For example, some values required for populating Cloud Hosts is different for AWS and Azure. Though the object ID and the name of the host is required for both AWS and Azure, for AWS, the CPU core count is required and for Azure, the host type value is required. For details on entities and their relationships, refer to Entities for BYOL and Relationships between the entities for BYOL.
In this example, Cloud Service Account is the topmost entity. All the other entities listed in the Entities for BYOL table are dependent entities of Cloud Service Account. If an entity is marked as a dependent entity, then the parent entity and the relationship between that entity and it's parent needs to be mentioned in the same payload. For example, if you want to create an AWS data center on Cloud Service Account, you need to include the Cloud Service Account entity in the same payload; even if Cloud Service Account already exists in your instance. Similarly, when you create software installations, you need to include all the dependent entities for software installations all through the hierarchy in the same payload.
Entities for BYOL
| Entities | Required fields |
|---|---|
| Cloud Service Account [cmdb_ci_cloud_service_account] | account_id – Unique identifier |
| AWS Datacenters [cmdb_ci_aws_datacenter] | object_id – Unique identifier |
| Azure Datacenters [cmdb_ci_azure_datacenter] | object_id – Unique identifier |
| Cloud Hosts [cmdb_ci_cloud_host] Note: Not needed for shared
VMs. |
|
| Virtual Machine Instances [cmdb_ci_vm_instance] | object_id – Unique identifier |
| Computers [cmdb_ci_computer] |
|
Software Installations [cmdb_sam_sw_install] Note: Software Installations [cmdb_sam_sw_install] is a related entry for
Computers [cmdb_ci_computer] |
|
Relationships between the entities for BYOL
| Entity relationships | Type | Parent | Child |
|---|---|---|---|
| AWS/Azure Datacenters – Cloud Service Account | Hosted on::Hosts | AWS/Azure Datacenters | Cloud Service Account |
| AWS/Azure Datacenters – Cloud Hosts | Hosted on::Hosts | Cloud Hosts | AWS/Azure Datacenters |
| AWS/Azure Datacenters – Virtual Machine Instances | Hosted on::Hosts | Virtual Machine Instances | AWS/Azure Datacenters |
| Cloud Hosts - Virtual Machine Instances | Runs on::Runs | Virtual Machine Instances | Cloud Hosts |
| Computers - Virtual Machine Instances | Virtualized by::Virtualizes | Computers | Virtual Machine Instances |
Sample payload for Computer and Installations for dedicated VM (similar for AWS and Azure)
In this sample payload, a dedicated computer record is being passed. This computer record has a related array that contains all the software installations. A VM instance corresponds to the computer record. Cloud host is the dedicated host on which the virtual machine resides and the AWS datacenter is to be created on the Cloud Service Account. If you have multiple dedicated virtual machines, you can send one REST API for each dedicated virtual machine. For example, if you have 50 dedicated VMs, you need to send 50 REST API calls each having the same payload. All the software installations on a dedicated VM can be sent in a single payload in the related array.
var payload = {
'items': [{
'className': 'cmdb_ci_computer',
'values': {
'name': 'Comp - Dedicated AWS - 1',
'cpu_count': 1,
'cpu_core_count': 4,
'cpu_core_thread': 1,
'virtual': true
},
'related': [{
'className': 'cmdb_sam_sw_install',
'values': {
'publisher': 'Microsoft',
'display_name': 'SQL Server',
'version': '2017',
'cloud_license_type': 'BYOL',
'cloud_license_type_source': 'third_party_integration'
}
}]
}, {
'className': 'cmdb_ci_vm_instance',
'values': {
'object_id': 'sample_object_id_aws_vm_dedicated',
'name': 'VM Dedicated AWS - 1',
}
}, {
'className': 'cmdb_ci_cloud_host',
'values': {
'object_id': 'sample_object_id_aws_host',
'name': 'AWS Dedicated Host - 1',
'cpu_core_count': 32
}
}, {
'className': 'cmdb_ci_aws_datacenter',
'values': {
'object_id': 'sample_object_id_aws_dc',
'name': 'AWS DataCenter - 1'
}
}, {
'className': 'cmdb_ci_cloud_service_account',
'values': {
'account_id': 'sample_account_id_aws_service_account',
'name': 'Cloud Service Account AWS - 1'
}
}],
'relations': [{
'type': 'Virtualized by::Virtualizes',
'parent': 0,
'child': 1
}, {
'type': 'Runs on::Runs',
'parent': 1,
'child': 2
},
{
'type': 'Hosted on::Hosts',
'parent': 2,
'child': 3
}, {
'type': 'Hosted on::Hosts',
'parent': 3,
'child': 4
}
]
}
var jsonUntil = new JSON();
var input = jsonUntil.encode(payload);
gs.info("Input: " + input.toString());
var options = {
"partial_payloads": false,
"deduplicate_payloads": true
};
var output = SNC.IdentificationEngineScriptableApi.createOrUpdateCIEnhanced('ServiceNow', input, options);
gs.print("Output:" + output);