Skip to content

Data Model

ucmdb_rest.datamodel.DataModel(server)

Service module for interacting with the UCMDB Class Model and Data Model.

This module provides methods to create, update, and delete Configuration Items (CIs) and Relationships, as well as tools to inspect the CI Type (Class) definitions and identification rules.

Initialize the service with a reference to the main level UCMDB client

Source code in ucmdb_rest\datamodel.py 
37
38
39
40
41
def __init__(self, server):
    """
    Initialize the service with a reference to the main level UCMDB client
    """
    self.server = server

addCIs(ciToCreate, isGlobalId=False, forceTemporaryID=False, ignoreExisting=False, returnIdsMap=False, ignoreWhenCantIdentify=False)

Adds or updates a bulk collection of CIs and Relationships.

Parameters:

Name Type Description Default
ciToCreate dict

A dictionary defining the CIs and relations. Example: { "cis": [{"ucmdbId": "1", "type": "node", "properties": {"name": "Test"}}], "relations": [{"type": "containment", "end1Id": "1", "end2Id": "2"}] }

 required
isGlobalId bool

Whether IDs in the payload are global UCMDB IDs. Default is False.

 False
forceTemporaryID bool

Whether to treat provided IDs as temporary identifiers. Default is False.

 False
ignoreExisting bool

If True, existing CIs will not be updated. Default is False.

 False
returnIdsMap bool

If True, returns a mapping of temporary IDs to actual UCMDB IDs. Default is False.

 False
ignoreWhenCantIdentify bool

If True, skips CIs that do not match identification rules instead of failing. Default is False.

 False

Returns:

Type Description
Response

A response containing lists of added, removed, updated, or ignored IDs.
Source code in ucmdb_rest\datamodel.py 
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
def addCIs(
    self,
    ciToCreate,
    isGlobalId=False,
    forceTemporaryID=False,
    ignoreExisting=False,
    returnIdsMap=False,
    ignoreWhenCantIdentify=False,
):
    """
    Adds or updates a bulk collection of CIs and Relationships.

    Parameters
    ----------
    ciToCreate : dict
        A dictionary defining the CIs and relations.
        Example:
        {
            "cis": [{"ucmdbId": "1", "type": "node", "properties": {"name": "Test"}}],
            "relations": [{"type": "containment", "end1Id": "1", "end2Id": "2"}]
        }
    isGlobalId : bool, optional
        Whether IDs in the payload are global UCMDB IDs. Default is False.
    forceTemporaryID : bool, optional
        Whether to treat provided IDs as temporary identifiers. Default is False.
    ignoreExisting : bool, optional
        If True, existing CIs will not be updated. Default is False.
    returnIdsMap : bool, optional
        If True, returns a mapping of temporary IDs to actual UCMDB IDs. Default is False.
    ignoreWhenCantIdentify : bool, optional
        If True, skips CIs that do not match identification rules instead of failing.
        Default is False.

    Returns
    -------
    requests.Response
        A response containing lists of added, removed, updated, or ignored IDs.
    """
    query_params = {
        "isGlobalId": str(isGlobalId).lower(),
        "forceTemporaryId": str(forceTemporaryID).lower(),
        "ignoreExisting": str(ignoreExisting).lower(),
        "returnIdsMap": str(returnIdsMap).lower(),
        "ignoreWhenCantIdentify": str(ignoreWhenCantIdentify).lower(),
    }
    url_part = "/dataModel"
    return self.server._request("POST",url_part, json=ciToCreate, params=query_params)

convertFromBase64(stringToDecode) staticmethod

The function takes a Base64-encoded string, converts it to bytes, decodes it using Base64 decoding, and then converts the resulting bytes back into a UTF-8 string, which is then returned.

Parameters:

Name Type Description Default
stringToDecode

A Base 64 encoded string

 required

Returns:

Name Type Description
decoded_string str

A UTF-8 string
Source code in ucmdb_rest\datamodel.py 
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
@staticmethod
def convertFromBase64(stringToDecode):
    """
    The function takes a Base64-encoded string, converts it to bytes, decodes
    it using Base64 decoding, and then converts the resulting bytes back into
    a UTF-8 string, which is then returned.

    Parameters
    ----------
    stringToDecode: base64 string
        A Base 64 encoded string
    Returns
    -------
    decoded_string: str
        A UTF-8 string
    """
    base64_bytes = stringToDecode.encode("utf-8")
    sample_string_bytes = base64.b64decode(base64_bytes)
    decoded_string = sample_string_bytes.decode("utf-8")
    return decoded_string

deleteCIs(id_to_delete, isGlobalId=False)

Deletes a specific CI by its ID.

Parameters:

Name Type Description Default
id_to_delete str

The UCMDB ID (local or global) to delete.

 required
isGlobalId bool

Set to True if the ID provided is a Global ID. Default is False.

 False

Returns:

Type Description
Response

A summary of the deletion result.
Source code in ucmdb_rest\datamodel.py 
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
def deleteCIs(self, id_to_delete, isGlobalId=False):
    """
    Deletes a specific CI by its ID.

    Parameters
    ----------
    id_to_delete : str
        The UCMDB ID (local or global) to delete.
    isGlobalId : bool, optional
        Set to True if the ID provided is a Global ID. Default is False.

    Returns
    -------
    requests.Response
        A summary of the deletion result.
    """
    url_part = f"/dataModel/ci/{id_to_delete}"
    params = {"isGlobalId": str(isGlobalId).lower()}
    return self.server._request("DELETE",url_part,params=params)

getClass(CIT)

Retrieves the definition of a class (CI Type) from the UCMDB server.

This method makes a GET request to the UCMDB server to fetch the definition of the specified class.

Parameters:

Name Type Description Default
CIT str

The class name (e.g., "node").

 required

Returns:

Type Description
Response

A JSON object describing the CI Type, with attributes such as: - name - displayName - superClass - description - allAttributes (list of dictionaries, each representing an attribute) - classAttributes (list of dictionaries, each representing an attribute defined in this class) - iconName - children - parents - qualifiers - classType - classQualifiers - defaultLabel - validLinks - identification (dictionary with identification details) - editable - scope - deletable - createdByFactory - modifiedByUser
Example

CIT = 'node' class_def = getClass(CIT) print(class_def['name']) 'node'

Source code in ucmdb_rest\datamodel.py 
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
def getClass(self, CIT):
    """
    Retrieves the definition of a class (CI Type) from the UCMDB server.

    This method makes a GET request to the UCMDB server to fetch the
    definition of the specified class.

    Parameters
    ----------
    CIT : str
        The class name (e.g., "node").

    Returns
    -------
    requests.Response
        A JSON object describing the CI Type, with attributes such as:
        - name
        - displayName
        - superClass
        - description
        - allAttributes (list of dictionaries, each representing an
                        attribute)
        - classAttributes (list of dictionaries, each representing an
                        attribute defined in this class)
        - iconName
        - children
        - parents
        - qualifiers
        - classType
        - classQualifiers
        - defaultLabel
        - validLinks
        - identification (dictionary with identification details)
        - editable
        - scope
        - deletable
        - createdByFactory
        - modifiedByUser

    Example
    -------
    >>> CIT = 'node'
    >>> class_def = getClass(CIT)
    >>> print(class_def['name'])
    'node'
    """
    url_part = f"/classModel/citypes/{CIT}"
    return self.server._request("GET",url_part)

retrieveIdentificationRule(cit='node')

Retrieves the XML identification rule for a specific CI Type.

Parameters:

Name Type Description Default
cit str

The CI Type name. Default is 'node'.

 'node'

Returns:

Type Description
Response

The response containing the Base64 encoded ruleXml.

Examples:

>>> response = model.retrieveIdentificationRule('node')
>>> rule_b64 = response.json()["identification"]["ruleXml"]
>>> xml = model.convertFromBase64(rule_b64)
Source code in ucmdb_rest\datamodel.py 
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
def retrieveIdentificationRule(self, cit="node"):
    """
    Retrieves the XML identification rule for a specific CI Type.

    Parameters
    ----------
    cit : str, optional
        The CI Type name. Default is 'node'.

    Returns
    -------
    requests.Response
        The response containing the Base64 encoded `ruleXml`.

    Examples
    --------
    >>> response = model.retrieveIdentificationRule('node')
    >>> rule_b64 = response.json()["identification"]["ruleXml"]
    >>> xml = model.convertFromBase64(rule_b64)
    """
    url_part = f"/classModel/citypes/{cit}?withAffectedResources=false"
    return self.server._request("GET",url_part)

updateCI(id_to_update, update_ci)

Updates a CI by ID via a PUT REST API call.

Parameters:

Name Type Description Default
id_to_update str

The global CI identifier (or LOCAL CI identifier).

 required
update_ci dict

A dictionary containing the update.

 required

Returns:

Type Description
Response

The results of the update. For example: { "addedCis": [], "removedCis": [], "updatedCis": [ "44c93b1d0230dd02b013364a7b8c635f" ], "ignoredCis": [] }
Source code in ucmdb_rest\datamodel.py 
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
def updateCI(self, id_to_update, update_ci):
    """
    Updates a CI by ID via a PUT REST API call.

    Parameters
    ----------
    id_to_update : str
        The global CI identifier (or LOCAL CI identifier).
    update_ci : dict
        A dictionary containing the update.

    Returns
    -------
    requests.Response
        The results of the update. For example:
        {
            "addedCis": [],
            "removedCis": [],
            "updatedCis": [
                "44c93b1d0230dd02b013364a7b8c635f"
            ],
            "ignoredCis": []
        }
    """
    url_part = f"/dataModel/ci/{id_to_update}"
    return self.server._request("PUT",url_part,json=update_ci)