Skip to content

Topology Service

ucmdb_rest.topology.Topology(server)

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

Source code in ucmdb_rest\topology.py 
14
15
16
17
18
def __init__(self, server):
    """
    Initialize the service with a reference to the main level UCMDB server
    """
    self.server = server

getChunk(res_id, index)

This method retrieves the values in each chunk (index).

Parameters:

Name Type Description Default
res_id str

The temporary result identifier (queryResultId) from the initial call.

 required
index int

Which chunk to get.

 required

Returns:

Type Description
Response

Can be converted to a dictionary containing the CIs and relations. For example: { "cis": [ { "ucmdbId": "4fc4d26b423c52bd99c3586017fd55e7", "globalId": null, "type": "nt", "properties": { "display_label": "pue01vm0040" }, "attributesDisplayNames": null, "attributesQualifiers": null, "attributesType": null, "classDefinition": null, "displayLabel": null, "label": "Windows" }, { "ucmdbId": "4fe8814b30be8ca4aeedcf1e4323fa62", "globalId": null, "type": "nt", "properties": { "display_label": "pue01vm1278" }, "attributesDisplayNames": null, "attributesQualifiers": null, "attributesType": null, "classDefinition": null, "displayLabel": null, "label": "Windows" }, { "ucmdbId": "4fee7d96a41be2f48f7fd343e815b6de", "globalId": null, "type": "nt", "properties": { "display_label": "bra03pc78" }, "attributesDisplayNames": null, "attributesQualifiers": null, "attributesType": null, "classDefinition": null, "displayLabel": null, "label": "Windows" } ], "relations": [] }
Source code in ucmdb_rest\topology.py 
 59
 60
 61
 62
 63
 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
111
112
113
114
115
116
117
118
119
120
121
122
123
def getChunk(self, res_id, index):
    '''
    This method retrieves the values in each chunk (index).

    Parameters
    ----------
    res_id : str
        The temporary result identifier (queryResultId) from the initial call.
    index : int
        Which chunk to get.

    Returns
    -------
    requests.Response
        Can be converted to a dictionary containing the CIs and relations. For example:
            {
            "cis": [
                {
                "ucmdbId": "4fc4d26b423c52bd99c3586017fd55e7",
                "globalId": null,
                "type": "nt",
                "properties": {
                    "display_label": "pue01vm0040"
                },
                "attributesDisplayNames": null,
                "attributesQualifiers": null,
                "attributesType": null,
                "classDefinition": null,
                "displayLabel": null,
                "label": "Windows"
                },
                {
                "ucmdbId": "4fe8814b30be8ca4aeedcf1e4323fa62",
                "globalId": null,
                "type": "nt",
                "properties": {
                    "display_label": "pue01vm1278"
                },
                "attributesDisplayNames": null,
                "attributesQualifiers": null,
                "attributesType": null,
                "classDefinition": null,
                "displayLabel": null,
                "label": "Windows"
                },
                {
                "ucmdbId": "4fee7d96a41be2f48f7fd343e815b6de",
                "globalId": null,
                "type": "nt",
                "properties": {
                    "display_label": "bra03pc78"
                },
                "attributesDisplayNames": null,
                "attributesQualifiers": null,
                "attributesType": null,
                "classDefinition": null,
                "displayLabel": null,
                "label": "Windows"
                }
            ],
            "relations": []
            }
    '''
    url_part = f'/topology/result/{res_id}/{index}'
    return self.server._request("GET",url_part)

getChunkForPath(state, execution_id, chunk)

Retrieves a chunk of data for a specific path from the UCMDB server.

This method makes a POST request to the UCMDB server to retrieve a chunk of data for a specific path.

Parameters:

Name Type Description Default
state str

The path element ID.

 required
execution_id str

The ID of the view execution.

 required
chunk int

The number of the chunk to retrieve.

 required

Returns:

Type Description
Response

Response object containing the requested chunk of data.
Source code in ucmdb_rest\topology.py 
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
def getChunkForPath(self, state, execution_id, chunk):
    """
    Retrieves a chunk of data for a specific path from the UCMDB server.

    This method makes a POST request to the UCMDB server to retrieve a 
    chunk of data for a specific path.

    Parameters
    ----------
    state : str
        The path element ID.
    execution_id : str
        The ID of the view execution.
    chunk : int
        The number of the chunk to retrieve.

    Returns
    -------
    requests.Response
        Response object containing the requested chunk of data.
    """
    body = {
        "viewExecutionId": execution_id,
        "path": [{"pathElementId": state, "pathElementType": state}],
        "chunkNumber": chunk
    }
    url_part = '/uiserver/modeling/views/result/chunkForPath'
    return self.server._request("POST",url_part,json=body)

get_all_view_results(view_name, chunkSize=10000)

Executes a view and automatically aggregates all paged chunks.

This is the recommended method for retrieving large views. It handles the initial request and iterates through all subsequent chunks to provide a single, unified result set.

Parameters:

Name Type Description Default
view_name str

The name of the view in UCMDB.

 required
chunkSize int

The number of CIs to retrieve per API call. Default is 10000.

 10000

Returns:

Type Description
dict

A combined dictionary containing 'cis' and 'relations' lists.
Source code in ucmdb_rest\topology.py 
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
def get_all_view_results(self, view_name, chunkSize=10000):
    """
    Executes a view and automatically aggregates all paged chunks.

    This is the recommended method for retrieving large views. It handles 
    the initial request and iterates through all subsequent chunks 
    to provide a single, unified result set.

    Parameters
    ----------
    view_name : str
        The name of the view in UCMDB.
    chunkSize : int, optional
        The number of CIs to retrieve per API call. Default is 10000.

    Returns
    -------
    dict
        A combined dictionary containing 'cis' and 'relations' lists.
    """
    data = self.runView(view_name, chunkSize=chunkSize).json()

    all_cis = data.get('cis') or []
    all_relations = data.get('relations') or []

    res_id = data.get('queryResultId')
    num_chunks = data.get('numberOfChunks', 0)

    if not res_id:
        return {"cis": all_cis, "relations": all_relations}

    for i in range(1, num_chunks + 1):
        chunk_data = self.getChunk(res_id, i).json()

        all_cis.extend(chunk_data.get('cis') or [])
        all_relations.extend(chunk_data.get('relations') or [])

    return {"cis": all_cis, "relations": all_relations}

queryCIs(query)

Retrieves the result of a query defined in UCMDB via a REST API POST call.

Parameters:

Name Type Description Default
query dict

JSON describing the query. For example: { "nodes": [ { "type": "node", "queryIdentifier": "node", "visible": "true", "includeSubtypes": "true", "layout": ["display_label"], "attributeConditions": [], "linkConditions": [], "ids": [] } ], "relations": [] }

 required

Returns:

Type Description
Response

Can be converted to a dictionary containing 2 entries, a list of CIs (dictionaries) and a list of relations (also dictionaries). For example: { "cis": [], "relations": [] }
Source code in ucmdb_rest\topology.py 
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
180
181
182
183
184
185
186
187
188
189
190
def queryCIs(self, query):
    '''
    Retrieves the result of a query defined in UCMDB via a REST API POST 
    call.

    Parameters
    ----------
    query : dict
        JSON describing the query. For example:
            {
                "nodes": [
                    {
                        "type": "node",
                        "queryIdentifier": "node",
                        "visible": "true",
                        "includeSubtypes": "true",
                        "layout": ["display_label"],
                        "attributeConditions": [],
                        "linkConditions": [],
                        "ids": []
                    }
                ],
                "relations": []
            }

    Returns
    -------
    requests.Response
        Can be converted to a dictionary containing 2 entries, a list of CIs (dictionaries)
        and a list of relations (also dictionaries). For example:
            {
                "cis": [],
                "relations": []
            }
    '''
    url_part = '/topologyQuery'
    return self.server._request("POST",url_part,json=query)

runView(view, includeEmptyLayout=False, chunkSize=10000)

Retrieves the result of a view defined in UCMDB via a REST API POST call

Parameters:

Name Type Description Default
view str

Name of a view on the UCMDB server.

 required
includeEmptyLayout bool

Should empty layouts be shown? Default is False.

 False
chunkSize int

The max number of nodes to return in each chunk.

 10000

Returns:

Type Description
Response

Can be converted to a dictionary contains 2 entries, CIs and Relations, each of which is a list of dictionaries. For example: { "cis": [], "relations": [] }
Source code in ucmdb_rest\topology.py 
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
def runView(self, view, includeEmptyLayout=False, chunkSize=10000):
    '''
    Retrieves the result of a view defined in UCMDB via a REST API POST 
    call

    Parameters
    ----------
    view : str
        Name of a view on the UCMDB server.
    includeEmptyLayout : bool
        Should empty layouts be shown? Default is False.
    chunkSize : int
        The max number of nodes to return in each chunk.

    Returns
    -------
    requests.Response
        Can be converted to a dictionary contains 2 entries, CIs and Relations, each of
        which is a list of dictionaries. For example:
            {
                "cis": [],
                "relations": []
            }
    '''
    url_part = '/topology'
    payload = {"includeEmptyLayoutProperties": includeEmptyLayout, "chunkSize": chunkSize}
    return self.server._request("POST", url_part, json=view, params=payload)