Use > How to write JSON Files for services and resources import

How to write JSON files for services and resources import

You can import your own business services and resources into HPE ITOC using a JSON file. This topic provides information about the syntax and semantics for this JSON file.

Limitations

The import request must be in the JSON format. To export and import resources, services, or relationships from a different data source, such as UCMDB/CSA, you must first create this JSON file with the desired input.

Security

The import of business services and resources requires the following permissions:

  • Write Business Services
  • Read and Write Resources

Input JSON format

The following example shows a simple API request body:

{
	"canUpdate": true,
	"defaultSourceURI" : "https://ucmdb.hp.com",
	"resources" : [
        {
            "type": "SLES 11",
            "name": "Alpha",
            "ref" : { "sourceRef": "Alpha" },
            "attributes" : [ {"name" : "Hostname", "value" : "Alpha.qa.itoc.com"} ]
        }
	],
	"services" : [
        {
            "name": "Service1Alpha",
            "ref" : { "sourceRef": "Service1Alpha" },
			"priority" : "Silver",
			"relationships" : [
				{
					"target" : { "sourceRef" : "Alpha" },
					"type" : "contains"
				}
			]
        }
	]
}

The request body contains the following four major components:

  • canUpdate - This field specifies if the preexisting entities (such as resources and services) can be updated during the progressive import. If specified as true and if the reference of a preexisting resource or service matches the reference specified in the request body, that preexisting entity will be updated to reflect the new values specified in the request body. If specified as false, that preexisting entity will NOT be updated, and a skipped message is generated for the import results.
  • defaultSourceURI - The uniform resource identifier (URI) must be valid and is used to abbreviate the references of the referred entities (for resources and services) in the request body. The resource and service references have two parts: sourceURI and sourceRef. If the sourceURI matches the defaultSourceURI, then the sourceURI can be omitted from the reference.
  • List of resources - This list specifies all the resources that are to be imported or updated (if canUpdate is true). The resources must be uniquely identified by their references, which consist of a sourceURI and a sourceRef, as mentioned above. If there is a duplicate reference for a resource found in the database, the preexisting resource is updated if canUpdate is true. If canUpdate is false, the resource is skipped and reported as such in the response body.

    If the reference is not found in the database, a new resource is created. If the resource definition contains errors, it is reported as failed in the response body, along with a list of errors specifying what is wrong with the import. If a resource reference is specified multiple times in the resources section, the repeating references will be reported as failed, as they can neither be created nor updated (a maximum of only one update is allowed).

  • List of services - This list specifies all the services that are to be imported or updated (if canUpdate is true). Just like resources, the services too must be uniquely identified by their references, which consist of a sourceURI and a sourceRef, as mentioned above.

    If the reference is not found in the database, a new service is created. If the service definition contains errors, it is reported as failed in the response, along with a list of errors specifying what is wrong with the import. If a service reference is specified multiple times in the services section, the repeating references will be reported as failed, as they can neither be created nor updated (a maximum of only one update is allowed).

Results

If you try the sample request (above) in the HPE ITOC UI, you will get following result:

If you try the same import a second time, the subsequent response changes to:

The message for the subsequent import has changed to “Updated” because the first import created the resources and services, and the subsequent import could only update the definitions for the preexisting resources and services.

If you change the canUpdate value to false and retry the import, you will receive the following response:

In general, for any import, the Results contains up to three sections (which may be applicable depending on the JSON request):

  • Errors - This list shows the errors for the defaultSourceURI specification. Errors messages are as follows:
    { 1, "defaultSourceURI exceeds 255 characters" },
{ 2, "Malformed defaultSourceURI" },
{ 3, "A resource definition does not have a ref specified." },
{ 4, "A service definition does not have a ref specified." }
  • Resources - Resources are divided into the following categories. If the canUpdate field is false, the updated list will be empty.
    • Created
    • Skipped
    • Updated
    • Failed
  • Services – Services too are divided into the same categories as Resources. If the canUpdate field is false, the updated list will be empty.
    • Created
    • Skipped
    • Updated
    • Failed

Failed error codes

If a service or resource import fails, one of the following messages can specify exactly what may have failed:

For resources

{ 101, "'name' {0} exceeds 255 characters" },
{ 102, "'sourceURI' {0} exceeds 255 characters" },
{ 103, "'sourceURI' {0} is malformed" },
{ 104, "'sourceRef' {0} exceeds 255 characters" },
{ 105, "'type' {0} is invalid" },
{ 106, "attribute 'name' {0} exceeds 255 characters" },
{ 107, "attribute 'name' {0} is not valid for 'type' {1}" },
{ 108, "attribute 'value' {0} exceeds 4000 characters" },
{ 109, "attribute 'name' {0} is already specified" },
{ 110, "Missing mandatory attribute 'name' {0} for 'type' {1}" },
{ 111, "'accessThroughRef' {0} is invalid" },
{ 112, "Duplicate ref {0} in the request body, subsequent definitions are being ignored" },
{ 113, "A cyclic or incomplete chain of 'accessThroughRef' relationship was detected on adding or updating {0} which has an accessRef of {1}" },
{ 114, "An unexpected error was detected on adding or updating {0}, exception is {1}, trace is {2}" },
{ 115, "accessThroughRef 'sourceURI' {0} exceeds 255 characters" },
{ 116, "accessThroughRef 'sourceURI' {0} is malformed" },
{ 117, "accessThroughRef 'sourceRef' {0} exceeds 255 characters" },
{ 118, "The organization for resource {0} does not allow read access to this resource." },
{ 119, "The organization for resource {0} does not allow write access to this resource." },
{ 120, "One of the attributes for resource does not have a name." },
{ 121, "Resource name must be specified" },
{ 122, "'sourceRef' value is missing for the resource" },
{ 123, "'sourceRef' value is missing for the accessRef" }
{ 124, "'name' {0} preexists for a non obsolete resource" }
{ 125, "'name' {0} is defined multiple times for resources in the request body." }

For services

{ 201, "'name' {0} exceeds 255 characters" },
{ 202, "'description' {0} exceeds 4000 characters" },
{ 203, "'sourceURI' {0} exceeds 255 characters" },
{ 204, "'sourceURI' {0} is malformed" },
{ 205, "'sourceRef' {0} exceeds 255 characters" },
{ 206, "'rootRef' {0} is invalid" },
{ 207, "Duplicate ref {0} in the request body, subsequent definitions are being ignored" },
{ 208, "'relationship' {0} is already defined" },
{ 209, "'source' {0} unreachable from the 'rootRef' {1}" },
{ 210, "'type' {0} invalid for relationship {1}" },
{ 211, "A cyclic 'relationship' was detected on adding {0}" },
{ 212, "'priority' {0} is invalid" },
{ 213, "relationship 'sourceURI' {0} exceeds 255 characters" },
{ 214, "relationship 'sourceURI' {0} is malformed" },
{ 215, "relationship 'sourceRef' {0} exceeds 255 characters" },
{ 216, "root 'sourceURI' {0} exceeds 255 characters" },
{ 217, "root 'sourceURI' {0} is malformed" },
{ 218, "root 'sourceRef' {0} exceeds 255 characters" },
{ 219, "'source' {0} is invalid" },
{ 220, "'target' {0} is invalid" },
{ 221, "'target' {0} is same as 'root' {1} in relationship {2}" },
{ 222, "An unexpected error was detected on adding or updating {0}, exception is {1}, trace is {2}" },
{ 223, "'source' and 'target' can not be same in relation {0}" },
{ 224, "'name' {0} preexists for a non obsolete service" },
{ 225, "The organization for service {0} does not allow read access to this service." },
{ 226, "The organization for service {0} does not allow write access to this service." },
{ 227, "The organization for resource {0} does not allow read access to this resource." },
{ 228, "A relationship {0} can not have a null target" },
{ 229, "An unexpected error was detected on processing organization for resource {0}, exception is {1}, trace is {2}" },
{ 230, "Service name must be specified" },
{ 231, "'sourceRef' value is missing for the service relation's constituent ref" },
{ 232, "'sourceRef' value is missing for the rootRef" },
{ 233, "'sourceRef' value is missing for the service" }
{ 234, "'name' {0} is defined multiple times for services in the request body. " }

Users can fix the errors and then try reimporting.

JSON example

The following example imports a list of resources, along with a list of services based on those resources. 

{
    "canUpdate" : true,
    "defaultSourceURI" : "https://ucmdb.hp.com", 
    
    "resources" : [
        {
            "type": "SLES 11",
            "name": "Alpha",
            "ref" : { "sourceRef": "Alpha" },
            "attributes" : [ {"name" : "Hostname", "value" : "Alpha.qa.itoc.com"} ]
        },
        {
            "type": "RHEL 6",
            "name": "Beta",
            "ref" : { "sourceURI" : "https://csa.hp.com", "sourceRef": "Beta" },
            "attributes" : [ {"name" : "Hostname", "value": "Beta.qa.itoc.com"} ]
        },
        {
            "type": "RHEL 6",
            "name": "Gama",
            "ref" : { "sourceURI" : "https://csa2.hp.com", "sourceRef": "Gama" },
            "attributes" : [ {"name" : "Hostname", "value": "Gama.qa.itoc.com"} ],
			"accessThroughRef" : { "sourceRef": "Alpha" }
        },
        {
            "type": "RHEL 6",
            "name": "Delta",
            "ref" : { "sourceRef": "Delta" },
            "attributes" : [ {"name" : "Hostname", "value": "Delta.qa.itoc.com"} ],
			"accessThroughRef" : { "sourceRef": "Psi" }
        },
		{
            "type": "RHEL 6",
            "name": "Charlie",
            "ref" : { "sourceRef": "Charlie" },
            "attributes" : [ {"name" : "Hostname", "value": "Charlie.qa.itoc.com"} ],
			"accessThroughRef" : { "sourceRef": "Bravo" }
        },
        {
            "type": "RHEL 6",
            "name": "Bravo",
            "ref" : { "sourceRef": "Bravo" },
            "attributes" : [ {"name" : "Hostname", "value": "Bravo.qa.itoc.com"} ],
			"accessThroughRef" : { "sourceURI" : "https://csa.hp.com", "sourceRef": "Beta" }
        }
	],
	
    "services" : [
        {
            "name": "ServiceAlpha",
            "ref" : { "sourceURI" : "https://ucmdb.hp.com", "sourceRef": "ServiceAlpha" },
			"relationships" : [
				{
					"source" : { "sourceRef" : "Alpha" },
					"target" : { "sourceRef" : "Beta" },
					"type" : "contains"
				}
			]
        },
        {
            "name": "ServiceAlpha",
            "ref" : { "sourceURI" : "https://ucmdb.hp.com", "sourceRef": "ServiceAlpha" },
			"priority" : "Silver",
			"relationships" : [
				{
					"source" : { "sourceRef" : "Alpha" },
					"target" : { "sourceURI" : "https://csa.hp.com", "sourceRef" : "Beta" },
					"type" : "contains"

	}
			]
        },
        {
            "name": "ServiceQ",
            "ref" : { "sourceURI" : "https://ucmdb.hp.com", "sourceRef": "ServiceQ" },
			"priority" : "Silver",
			"relationships" : [
				{
					"source" : { "sourceRef" : "Alpha" },
					"target" : { "sourceURI" : "https://csa.hp.com", "sourceRef" : "Beta" },
					"type" : "contains"
				}
			]
        },
		{
            "name": "ServiceR",
            "ref" : { "sourceURI" : "https://ucmdb.hp.com", "sourceRef": "ServiceR" },
			"priority" : "Silver",
			"relationships" : [
				{
					"source" : { "sourceRef" : "Alpha" },
					"target" : { "sourceURI" : "https://csa.hp.com", "sourceRef" : "Beta" },
					"type" : "contains"
				},
				{
					"source" : { "sourceURI" : "https://csa.hp.com", "sourceRef" : "Beta" },
					"target" : { "sourceURI" : "https://csa2.hp.com", "sourceRef" : "Gama" },
					"type" : "contains"
				},
				{
					"source" : { "sourceURI" : "https://csa2.hp.com", "sourceRef" : "Gama" },
					"target" : { "sourceRef" : "Delta" },
					"type" : "contains"
				}
			]
        }
	]
}
  • Because the Alpha resource has already been imported, that resource is updated. The rest of the resources are created or have failed (if there were any errors in their definitions).
  • Similarly, services are either created or listed as failed (if there were any errors in their definitions).
  • Because none of the listed services were created previously, there is no updated section for the services.

    The following example shows results for this test case:

JSON attributes for resources

The following JSON attributes describe the resources in input JSON:

  • type: this is the resourceType of the resource being imported. See Specify attributes for resources being imported for a complete list of resource types and applicable resource attributes that can be specified. Note that resource attribute types are different from the JSON attributes described here.
  • name: A unique name qualifying the resource. This name is visible in the UI. The name must be unique across all the organizations in which the resource is visible.
  • ref: A unique URI/string pair to identify the resource globally throughout the ITOC. Unlike name, the ref must be unique across all organizations irrespective of the service being visible or invisible for a given organization.
  • accessThroughRef: Some of the resources do not have corresponding applicable hardware. They must rely on some other resource to be accessed through. accessThroughRef specifies the ref of the resource through which the specified resource is accessed. If this field is not specified, the accessThrough resource of a given resource is assumed to be itself.
  • attributes: A name,value pair listing the applicable attributes of the resource (see Specify attributes for resources being imported).

Specify attributes for resources being imported

This section describes how to specify attribute names for resources.

Each resource has a resource type, and each resource type has a set of predefined attributes. The attribute and its value must be specified while defining the resource in the JSON script. An error occurs if an applicable attribute for a resource type is not specified.

The following list shows attributes for each resource type. This list is organized in hierarchical form. All parent attributes are apply to their children. For example, Device has Vendor attributes, therefore, all its children also have Vendor attributes.

{
"resourcetypes":
[
    {"name":"Business Service"
    },
    {"name":"Device",
     "attributes": "Vendor",
     "children":
     [
        {"name":"Compute",
         "attributes": "BiosUUID",
         "children":
         [
            {"name":"Server"}
         ]
        },
     ]
    },
    {"name":"Platform"
     "attributes":"Hostname",
     "children":
     [
        {"name":"Microsoft (MS) Windows",
         "children":
         [
            {"name":"MS Windows 7"},
            {"name":"MS Windows 8"},
            {"name":"MS Windows 8.1"},
            {"name":"MS Windows Server 2008 R2"}
            {"name":"MS Windows Server 2012"},
            {"name":"MS Windows Server 2012 R2"}
         ]
        },
        {"name":"Unix",
         "children":
         [
            {"name":"Linux",
             "children":
             [
                {"name":"RHEL Compatibles"
                 "children":
                 [
                    {"name":"RHEL 5 Compatibles",
                     "children":
                     [
                        {"name":"CentOS 5"},
                        {"name":"OEL 5"},
                        {"name":"RHEL 5"}
                     ]
                    },
                    {"name":"RHEL 6 Compatibles",
                     "children":
                     [
                        {"name":"CentOS 6"},
                        {"name":"OEL 6"},
                        {"name":"RHEL 6"}
                     ]
                    },
                    {"name":"RHEL 7 Compatibles",
                     "children":
                     [
                        {"name":"CentOS 7"},
                        {"name":"OEL 7"},
                        {"name":"RHEL 7"}
                     ]
                    }
                 ]
                },
                { "name":"SUSE Compatibles",
                  "children":
                    [
                        {"name":"OpenSUSE",
                         "children":
                         [
                            {"name":"OpenSUSE 12"},
                            {"name":"OpenSUSE 13"}
                         ]
                        },
                        {"name":"SUSE Linux Enterprise Server (SLES)",
                         "children":
                         [
                            {"name":"SLES 10"},
                            {"name":"SLES 11"}
                         ]
                        }
                    ]
                },
                { "name":"Ubuntu Compatibles",
                  "children":
                    [
                        {"name":"Ubuntu",
                         "children":
                         [
                            {"name":"Ubuntu 12.04 LTS"},
                            {"name":"Ubuntu 14.04 LTS"}
                         ]
                        },
                        {"name":"Debian",
                         "children":
                         [
                            {"name":"Debian 7"}
                         ]
                        }
                    ]
                }
             ]
            },
            {"name":"Oracle Solaris",
             "children":
             [
                {"name":"Oracle Solaris 11"},
                {"name":"Oracle Solaris 11.1"}
             ]
            }
         ]
        }
     ]
    },
    {"name":"Software",
     "children":
     [
        {"name":"Web Server",
         "children":
         [
            {"name":"Apache HTTP Server",
             "attributes":"APACHE_PREFIX;DOCROOT;HTTPD_ROOT",
             "children":
             [
                {"name":"Apache HTTP Server 2.4"}
             ]
            },
            {"name":"Apache Tomcat",
             "attributes":"CATALINA_HOME;CATALINA_BASE",
             "children":
             [
                {"name":"Apache Tomcat 6"}
             ]
            },
            {"name":"NGINX"}
         ]
        },
        {"name":"Database",
         "children":
         [
           { "name":"DB2 Database Server",
             "attributes":"dbUser;dbName;dbPassword;DASUser;latestVersion(withFixPack)",
             "children":
             [
                {"name":"DB2 Database Server 8"},
                {"name":"DB2 Database Server 9"},
                {"name":"DB2 Database Server 9.5"},
                {"name":"DB2 Database Server 10.5"}
            ]
           },
           { "name":"MYSQL",
             "attributes":"dbUser;dbPassword;dbName",
             "children":
             [
                {"name":"MySQL Community Server 5.6"}
            ]
           },
           { "name":"MS SQL Server",
             "attributes":"dbUser;dbPassword;instanceName;latestVersion(withServicePack)",
             "children":
             [
                {"name":"MSSQL Server 2005"}
            ]
           },
           { "name":"Oracle",
             "attributes":"instanceName;instanceHome",
             "children":
             [
                {"name":"Oracle 10g"},
                {"name":"Oracle 11g"}
            ]
           },
         ]
        },
        {"name":"Application Server",
         "children":
         [
            {"name":"J2EE Server",
             "children":
             [
                {"name":"JBoss",
                 "attributes":"JBOSS_HOME",
                 "children":
                 [
                    {"name":"JBoss Application Server 7"}
                 ]
                },
                {"name":"WebLogic"},
                {"name":"Websphere"}
            ]
           }
         ]
        }
     ]
    },
]
}

JSON attributes for services

  • name: A unique name qualifying the service. This name is visible in the UI. The name must be unique across all the organizations in which the service is visible.
  • ref: A unique URI/string pair to identify the service globally throughout the ITOC. Unlike name, the ref must be unique across all organizations irrespective of the service being visible or invisible for a given organization.
  • description: A brief description of the service.
  • priority: Can be one of the following three values: Gold, Silver, Bronze.
  • rootRef and relationships: See Specify topologies for services being imported.

Specify topologies for services being imported

This section describes how to specify topologies for services.

Every service that has a topology specified for it has a relationships field specified for it. This field uses the references specified for the predefined resources to populate the service topology. A rootRef can be explicitly specified or, if left unspecified, uses a built-in resource called BUSINESS SERVICE as the root.

The relationships create the edges in the topology graph. There are two types of relationships: contains and depends_on.

In the following example, a service is created with an explicit root specified to be a predefined resource -
{ "sourceURI" : "https://csa.hp.com", "sourceRef" : "Beta" }. The relationships then specify an edge from this root reference to another resource - { "sourceRef" : "Alpha" }. 

{
    "canUpdate" : true,
    "defaultSourceURI" : "https://ucmdb.hp.com", 
    
    "services" : [
        {
            "name": "ServiceAlpha",
            "ref" : { "sourceURI" : "https://ucmdb.hp.com", "sourceRef": "ServiceAlpha" },
			"priority" : "Silver",
			"rootRef" : { "sourceURI" : "https://csa.hp.com", "sourceRef" : "Beta" },
			"relationships" : [
				{
					"target" : { "sourceRef" : "Alpha" },
					"type" : "contains"
				}
			]
        }
	]
}

In the following example, rootRef is not specified, so the script uses the implicit root. All the three resources specified in the relationships (Alpha, Gama, and Charlie) will connect to this implicit root.

{
    "canUpdate" : true,
    "defaultSourceURI" : "https://ucmdb.hp.com", 
    
    "services" : [
        {
            "name": "ServiceAlpha",
            "ref" : { "sourceURI" : "https://ucmdb.hp.com", "sourceRef": "ServiceAlpha" },
			"priority" : "Silver",
			"relationships" : [
				{
					"target" : { "sourceRef" : "Alpha" },
					"type" : "contains"
				},
				{
					"target" : { "sourceURI" : "https://csa2.hp.com", "sourceRef" : "Gama" },
					"type" : "contains"
				},
				{
					"target" : { "sourceRef" : "Charlie" },
					"type" : "contains"
				}
			]
        }
	]
}

The following example does not specify the root, so the implicit root is used. However, the relationships include the source attribute as well as the target attribute. The source is connected to the implicit root, and the target is then connected to the source.

{
    "canUpdate" : true,
    "defaultSourceURI" : "https://ucmdb.hp.com", 
    
    "services" : [
        {
            "name": "ServiceQ",
            "ref" : { "sourceURI" : "https://ucmdb.hp.com", "sourceRef": "ServiceQ" },
			"priority" : "Silver",
			"relationships" : [
				{
					"source" : { "sourceRef" : "Alpha" },
					"target" : { "sourceURI" : "https://csa.hp.com", "sourceRef" : "Beta" },
					"type" : "contains"
				}
			]
        }
	]
}

In the following example, the implicit root resource connects to Alpha, which in turn connected to Beta. Because Beta is also specified as the source in the next relationship, it directly connects to the root.

{
    "canUpdate" : true,
    "defaultSourceURI" : "https://ucmdb.hp.com", 
    "services" : [
        {
            "name": "ServiceR",
            "ref" : { "sourceURI" : "https://ucmdb.hp.com", "sourceRef": "ServiceR" },
			"priority" : "Silver",
			"relationships" : [
				{
					"source" : { "sourceRef" : "Alpha" },
					"target" : { "sourceURI" : "https://csa.hp.com", "sourceRef" : "Beta" },
					"type" : "contains"
				},
				{
					"source" : { "sourceURI" : "https://csa.hp.com", "sourceRef" : "Beta" },
					"target" : { "sourceURI" : "https://csa2.hp.com", "sourceRef" : "Gama" },
					"type" : "contains"
				},
				{
					"target" : { "sourceURI" : "https://csa.hp.com", "sourceRef" : "Beta" },
					"type" : "contains"
				}
			]
        }
	]
}

The following figure shows the visual representation of the hierarchy shown above:

Using the relationships (source, target) as well as rootRef (implicit or explicit root), it is possible to create arbitrary and complex hierarchies.

Some rules of thumb to remember are:

  • Root can be specified implicitly or explicitly.
  • If source is not specified in a relationship, root is assumed to be the source.
  • It is an error to specify cyclic relationships.

Send Help Center feedback