Object Models

The Cumulocity Python API's object model provides object-oriented access to the Cumulocity REST API. Use it to create and modify single objects within the Database.

These objects can also be used directly within the Main API classes to modify data in bulk.

---

ManagedObject

Represent a managed object within the database.

Instances of this class are returned by functions of the corresponding Inventory API. Use this class to create new or update managed objects.

Within Cumulocity a managed object is used to hold virtually any additional (apart from measurements, events and alarms) information. This custom information is modelled in fragments, named elements of any structure.

Fragments are modelled as standard Python fields and can be accessed directly if the names & structures are known:

x = mo.c8y_CustomFragment.values.x

Managed objects can be changed and such updates are written as differences to the database. The API does the tracking of these differences automatically - just use the ManagedObject class like any other Python class.

mo.owner = 'admin@cumulocity.com'
mo.c8y_CustomFragment.region = 'EMEA'
mo.add_fragment('c8y_CustomValue', value=12, uom='units')

Note: This does not work if a fragment is actually a field, not a structure own its own. A direct assignment to such a value fragment, like

mo.c8y_CustomReferences = [1, 2, 3]

is currently not supported nicely as it will not be recognised as an update. A manual update flagging is required:

mo.c8y_CustomReferences = [1, 2, 3]
mo.flag_update('c8y_CustomReferences')

See also https://cumulocity.com/guides/reference/inventory/#managed-object

Fragment

Standard fragment names.

Resource

Standard resource names.

add_child_addition(child: ManagedObject | str | int)

Link a child addition to this managed object.

This operation is executed immediately. No additional call to the update method is required.

Parameters:

Name	Type	Description	Default
child	ManagedObject | str | int	Child addition or its object ID	required

add_child_asset(child: ManagedObject | str | int)

Link a child asset to this managed object.

This operation is executed immediately. No additional call to the update method is required.

Parameters:

Name	Type	Description	Default
child	ManagedObject | str | int	Child asset or its object ID	required

add_child_device(child: ManagedObject | str | int)

Link a child device to this managed object.

This operation is executed immediately. No additional call to the update method is required.

Parameters:

Name	Type	Description	Default
child	ManagedObject | str | int	Child device or its object ID	required

apply_to(other_id: str | int) -> ManagedObject

Apply the details of this object to another object in the database.

Note: This will take the full details, not just the updates.

Parameters:

Name	Type	Description	Default
other_id	str | int	Database ID of the event to update.	required

Returns: A fresh ManagedObject instance representing the updated object within the database.

See also function Inventory.apply_to which doesn't parse the result.

create() -> ManagedObject

Create a new representation of this object within the database.

This function can be called multiple times to create multiple instances of this object with different ID.

Returns:

Type	Description
ManagedObject	A fresh ManagedObject instance representing the created
ManagedObject	object within the database. This instance can be used to get
ManagedObject	at the ID of the new managed object.

See also function Inventory.create which doesn't parse the result.

delete(**_) -> None

Delete this object within the database.

Note: child additions, assets (and devices) are not implicitly deleted. The database ID must be defined for this to function.

See also function Inventory.delete to delete multiple objects.

delete_tree() -> None

Delete this managed object within the database including child. additions, devices and assets. This is equivalent to using the forceCascade parameter of the Cumulocity REST API.

The database ID must be defined for this to function.

See also function DeviceInventory.delete_trees to delete multiple objects.

from_json(json: dict) -> ManagedObject classmethod

Build a new ManagedObject instance from JSON.

The JSON is assumed to be in the format as it is used by the Cumulocity REST API.

Parameters:

Name	Type	Description	Default
json	dict	JSON object (nested dictionary) representing a managed object within Cumulocity	required

Returns:

Type	Description
ManagedObject	ManagedObject object

get_latest_availability() -> Availability

Retrieve the latest availability information of this object.

Return

DeviceAvailability object

get_supported_measurements() -> datetime | str

Retrieve all supported measurement names of this managed object.

Return

List of measurement fragment names.

get_supported_series() -> datetime | str

Retrieve all supported measurement series names of this managed object.

Return

List of measurement series names.

reload() -> ManagedObject

Reload this object's data from database.

Returns:

Type	Description
ManagedObject	New ManagedObject instance built from latest data.

to_json(only_updated=False) -> dict

unassign_child_addition(child: ManagedObject | str | int)

Remove the link to a child addition.

This operation is executed immediately. No additional call to the update method is required.

Parameters:

Name	Type	Description	Default
child	ManagedObject | str | int	Child device or its object ID	required

unassign_child_asset(child: ManagedObject | str | int)

Remove the link to a child asset.

This operation is executed immediately. No additional call to the update method is required.

Parameters:

Name	Type	Description	Default
child	ManagedObject | str | int	Child device or its object ID	required

unassign_child_device(child: Device | str | int)

Remove the link to a child device.

This operation is executed immediately. No additional call to the update method is required.

Parameters:

Name	Type	Description	Default
child	Device | str | int	Child device or its object ID	required

update() -> ManagedObject

Write changes to the database.

Returns:

Type	Description
ManagedObject	A fresh ManagedObject instance representing the updated
ManagedObject	object within the database.

See also function Inventory.update which doesn't parse the result.

Device

Represent an instance of a Device object within Cumulocity.

Instances of this class are returned by functions of the corresponding DeviceInventory API. Use this class to create new or update Device objects.

Device objects are regular managed objects with additional standardized fragments and fields.

See also https://cumulocity.com/guides/reference/inventory/#managed-object https://cumulocity.com/guides/reference/device-management/

delete(with_device_user=False, **_) -> None

Delete this device object within the database.

Note: child additions, assets (and devices) are not implicitly deleted. The database ID must be defined for this to function.

Parameters:

Name	Type	Description	Default
with_device_user	bool	Whether the device user is deleted as well.	False

See also function DeviceInventory.delete to delete multiple objects.

delete_tree(with_device_user=False) -> None

Delete this device object within the database including child. additions, devices and assets.

The database ID must be defined for this to function.

Parameters:

Name	Type	Description	Default
with_device_user	bool	Whether the device user is deleted as well.	False

See also function DeviceInventory.delete to delete multiple objects.

from_json(json: dict) -> Device classmethod

get_user() -> User

Return the device user.

Returns:

Type	Description
User	Device's user.

get_username() -> str

Return the device username.

Returns:

Type	Description
str	Username of the device's user.

reload() -> Device

Reload this object's data from database.

Returns:

Type	Description
Device	New Device instance built from latest data.

to_json(only_updated=False) -> dict

DeviceGroup

Represent a device group within Cumulocity.

Instances of this class are returned by functions of the corresponding DeviceGroupInventory API. Use this class to create new or update DeviceGroup objects.

DeviceGroup objects are regular managed objects with additional standardized fragments and fields.

See also https://cumulocity.com/guides/reference/inventory/#managed-object https://cumulocity.com/guides/users-guide/device-management/#grouping-devices

assign_child_group(child: DeviceGroup | str | int)

Link a child group to this device group.

This operation is executed immediately. No additional call to the update method is required.

Parameters:

Name	Type	Description	Default
child	DeviceGroup | str | int	Child device or its object ID	required

create() -> DeviceGroup

Create a new representation of this object within the database.

This operation will create the group and all added child groups within the database.

:returns: A fresh DeviceGroup instance representing the created object within the database. This instance can be used to get at the ID of the new object.

See also function DeviceGroupInventory.create which doesn't parse the result.

create_child(name: str, owner: str = None, **kwargs) -> DeviceGroup

Create and assign a child group.

This change is written to the database immediately.

Parameters:

Name	Type	Description	Default
name	str	Device name	required
owner	str	User ID of the owning user (can be left None to automatically assign to the connection user upon creation)	None
kwargs		Additional arguments are treated as custom fragments	{}

Returns:

Type	Description
DeviceGroup	The newly created DeviceGroup object

delete(**_) -> None

Delete this device group.

The child groups (if there are any) are left dangling. This is equivalent to using the cascade=false parameter in the Cumulocity REST API.

delete_tree() -> None

Delete this device group and its children.

This is equivalent to using the cascade=true parameter in the Cumulocity REST API.

from_json(json: dict) -> DeviceGroup classmethod

Build a new DeviceGroup instance from JSON.

The JSON is assumed to be in the format as it is used by the Cumulocity REST API.

Parameters:

Name	Type	Description	Default
json	dict	JSON object (nested dictionary) representing a device group within Cumulocity	required

Returns:

Type	Description
DeviceGroup	DeviceGroup instance

reload() -> DeviceGroup

Reload this object's data from database.

Returns:

Type	Description
DeviceGroup	New DeviceGroup instance built from latest data.

unassign_child_group(child: DeviceGroup | str | int)

Remove the link to a child group.

This operation is executed immediately. No additional call to the update method is required.

Parameters:

Name	Type	Description	Default
child	DeviceGroup | str | int	Child device or its object ID	required

update() -> DeviceGroup

Write changed to the database.

Note: Removing child groups is currently not supported.

:returns: A fresh DeviceGroup instance representing the updated object within the database.

ExternalId

Represents an instance of an ExternalID in Cumulocity.

Instances of this class are returned by functions of the corresponding Identity API. Use this class to create or remove external ID.

See also: https://cumulocity.com/api/core/#tag/External-IDs

create() -> ExternalId

Store the external ID to the database.

Returns:

Type	Description
ExternalId	self reference

delete(**_) -> None

Remove the external ID from the database.

Returns:

Type	Description
None	self reference

from_json(json: dict) -> ExternalId classmethod

Build a new ExternalId instance from JSON.

The JSON is assumed to be in the format as it is used by the Cumulocity REST API.

Parameters:

Name	Type	Description	Default
json	dict	JSON structure of an external ID object	required

Returns:

Type	Description
ExternalId	ExternalId object

get_id()

Read the referenced managed object ID from database.

Returns:

Type	Description
	Database ID referenced by the external_id and external_type
	of this instance.

get_object() -> ManagedObject

Read the referenced managed object from database.

Returns:

Type	Description
ManagedObject	ManagedObject instance.

to_json(only_updated: bool = False) -> dict

Binary

Represents a binary object/file within the Database.

See also: https://cumulocity.com/api/core/#tag/Binaries

create() -> Binary

Create a new representation of this object within the database.

This function can be called multiple times to create multiple instances of this object with different ID.

Returns:

Type	Description
Binary	A fresh Binary instance representing the created object
Binary	within the database. This instance can be used to get
Binary	at the ID of the new object.

Raises:

Type	Description
FileNotFoundError	if the file refers to an invalid path.

See also function Binaries.create which doesn't parse the result.

from_json(json: dict) -> Binary classmethod

Build a new Binary instance from JSON.

The JSON is assumed to be in the format as it is used by the Cumulocity REST API.

Parameters:

Name	Type	Description	Default
json	dict	JSON object (nested dictionary) representing a managed object within Cumulocity	required

Returns:

Type	Description
Binary	Binary object

read_file() -> bytes

Read the content of the binary attachment.

Returns:

Type	Description
bytes	The binary attachment's content as bytes.

update() -> Binary

Update the binary attachment.

Returns:

Type	Description
Binary	The Binary managed object.

Returns:

Type	Description
Binary	A fresh Binary instance representing the created object
Binary	within the database.

Raises:

Type	Description
FileNotFoundError	if the file refers to an invalid path.

Note: The binary metadata cannot be updated using this method. Only the binary attachment is updated.

Measurement

Represents an instance of a measurement object in Cumulocity.

Instances of this class are returned by functions of the corresponding Measurements API. Use this class to create new or update existing measurements.

See also: https://cumulocity.com/guides/reference/measurements/#measurement

create() -> Measurement

Store the Measurement within the database.

A fresh Measurement object representing what was

Type	Description
Measurement	created within the database (including the ID).

from_json(json) -> Measurement classmethod

Build a new Measurement instance from Cumulocity JSON.

The JSON is assumed to be in the format as it is used by the Cumulocity REST API.

Parameters:

Name	Type	Description	Default
json	dict	JSON object (nested dictionary) representing a measurement within Cumulocity	required

Returns:

Type	Description
Measurement	Measurement object

get_series() -> list[str]

Collect series names.

Collect series names defined in this measurement. Any top level fragment having a nested element featuring a value field is considered a series. Multiple such series could be defined.

{
    "c8y_Temperature": {
        "T": {
            "unit": "C",
            "value": 12.8
        }
    }
}

Returns:

Type	Description
list[str]	A list of series names (e.g. c8y_Temperature.T) defined in this measurement.

to_json(only_updated=False) -> dict

Convert the instance to JSON.

The JSON format produced by this function is what is used by the Cumulocity REST API.

Note: Measurements cannot be updated, hence this function does not feature an only_updated argument.

Returns:

Type	Description
dict	JSON object (nested dictionary)

update() -> Measurement

Not implemented for Measurements.

Event

Represent an instance of an event object in Cumulocity.

Instances of this class are returned by functions of the corresponding Events API. Use this class to create new or update Event objects.

See also: https://cumulocity.com/api/core/#tag/Events

apply_to(other_id: str) -> Event

Apply changes made to this object to another object in the database.

Parameters:

Name	Type	Description	Default
other_id	str	Database ID of the event to update.	required

Returns:

Type	Description
Event	A fresh Event instance representing the updated object
Event	within the database.

See also function Events.apply_to which doesn't parse the result.

create() -> Event

Create the Event within the database.

Returns:

Type	Description
Event	A fresh Event object representing what was
Event	created within the database (including the ID).

create_attachment(file: str | BinaryIO, content_type: str = None) -> dict

Create the binary attachment.

Parameters:

Name	Type	Description	Default
file	str | BinaryIO	File-like object or a file path	required
content_type	str	Content type of the file sent (default is application/octet-stream)	None

Returns:

Type	Description
dict	Attachment details as JSON object (dict).

delete_attachment() -> None

Remove the binary attachment.

download_attachment() -> bytes

Read the binary attachment.

Returns:

Type	Description
bytes	The event's binary attachment as bytes.

from_json(json: dict) -> Event classmethod

has_attachment() -> bool

Check whether the event has a binary attachment.

Event objects that have an attachment feature a c8y_IsBinary fragment. This function checks the presence of that fragment.

Note: This does not query the database. Hence, the information might be outdated if a binary was attached after the event object was last read from the database.

Returns:

Type	Description
bool	True if the event object has an attachment, False otherwise.

to_json(only_updated: bool = False) -> dict

update() -> Event

Update the Event within the database.

Note: This will only send changed fields to increase performance.

Returns:

Type	Description
Event	A fresh Event object representing what the updated
Event	state within the database (including the ID).

update_attachment(file: str | BinaryIO, content_type: str = None) -> dict

Update the binary attachment.

Parameters:

Name	Type	Description	Default
file	str | BinaryIO	File-like object or a file path	required
content_type	str	Content type of the file sent (default is application/octet-stream)	None

Returns:

Type	Description
dict	Attachment details as JSON object (dict).

Alarm

Represent an instance of an alarm object in Cumulocity.

Instances of this class are returned by functions of the corresponding Alarms API. Use this class to create new or update Alarm objects.

See also: https://cumulocity.com/api/core/#tag/Alarms

Severity

Alarm severity levels.

Status

Alarm statuses.

apply_to(other_id: str) -> Alarm

Apply changes made to this object to another object in the database.

Parameters:

Name	Type	Description	Default
other_id	str	Database ID of the Alarm to update.	required

Returns:

Type	Description
Alarm	A fresh Alarm instance representing the updated object
Alarm	within the database.

create() -> Alarm

Create the Alarm within the database.

Returns:

Type	Description
Alarm	A fresh Alarm instance representing the created object
Alarm	within the database. This instance can be used to get at the ID
Alarm	of the new Alarm object.

delete(**_) -> None

Delete this object within the database.

An alarm is identified through its type and source. These fields must be defined for this to function. This is always the case if the instance was built by the API.

See also functions Alarms.delete and Alarms.delete_by

from_json(json: dict) -> Alarm classmethod

Build a new Alarm instance from JSON.

The JSON is assumed to be in the format as it is used by the Cumulocity REST API.

Parameters:

Name	Type	Description	Default
json	dict	JSON object (nested dictionary) representing a managed object within Cumulocity	required

Returns:

Type	Description
Alarm	Alarm object

to_json(only_updated=False) -> dict

Convert the instance to JSON.

The JSON format produced by this function is what is used by the Cumulocity REST API.

Parameters:

Name	Type	Description	Default
only_updated	bool	Whether only updated fields should be included in the generated JSON	False

Returns:

Type	Description
dict	JSON object (nested dictionary)

update() -> Alarm

Update the Alarm within the database.

Note: This will only send changed fields to increase performance.

Returns:

Type	Description
Alarm	A fresh Alarm instance representing the updated object
Alarm	within the database.

Series

A wrapper for a series result.

See also: Measurements.get_series function

This class wraps the raw JSON result but can also be used to read result specs and collect result values conveniently.

See also: https://cumulocity.com/api/core/#operation/getMeasurementSeriesResource

SeriesSpec dataclass

Series specifications.

collect(series: str | Sequence[str] = None, value: str | Sequence[str] = None, timestamps: bool | str = None) -> List | List[tuple]

Collect series results.

Parameters:

Name	Type	Description	Default
series	str | Sequence[str]	Which series' values to collect. If multiple series are collected each element in the result will be a tuple. If omitted, all available series are collected.	None
value	str	Which value (min/max/avg/...) to collect. If omitted, both min/max values are collected, grouped as 2-tuples.	None
timestamps	bool | str	Whether each element in the result list will be prepended with the corresponding timestamp. If True, the timestamp string will be included; Use 'datetime' or 'epoch' to parse the timestamp string.	None

Returns:

Type	Description
List | List[tuple]	A simple list or list of tuples (potentially nested) depending on the
List | List[tuple]	parameter combination.

Subscription

Represent a Notification 2.0 subscription within the database.

Instances of this class are returned by functions of the corresponding Subscriptions API. Use this class to create new options.

See also: https://cumulocity.com/api/core/#tag/Subscriptions

ApiFilter

Notification API filter types.

Context

Notification context types.

create() -> Subscription

Create a new subscription within the database.

Returns:

Type	Description
Subscription	A fresh Subscription instance representing the created
Subscription	subscription within the database.

See also function Subscriptions.create which doesn't parse the result.

from_json(json: dict) -> Subscription classmethod

Create a Subscription instance from Cumulocity JSON format.

Parameters:

Name	Type	Description	Default
json	dict	The JSON to parse.	required

Returns:

Type	Description
Subscription	A Subscription instance.

Availability

Cumulocity availability status labels

ConnectionStatus

Connection status labels

DataStatus

Data status labels

from_json(object_json: dict) -> Availability classmethod

Create an object instance from Cumulocity JSON format.

Caveat: this function is primarily for internal use and does not return a full representation of the JSON. It is used for object creation and update within Cumulocity.

Parameters:

Name	Type	Description	Default
object_json	dict	The JSON to parse.	required

Returns:

Type	Description
Availability	A Availability instance.

Fragment

Represent a custom fragment within database objects.

This class is used by other classes to represent custom fragments within their data model.

For example, every measurement contains such a fragment, holding the actual data points:

"pt_current": {
    "CURR": {
        "unit": "A",
        "value": 50
    }
}

A fragment has a name (pt_current in above example) and can virtually define any substructure.

add_element(name, element)

Add an element.

:param name: Name of the element :param element: Value of the element, either a simple value or a complex substructure defined as nested dictionary. :returns: self

has(name: str) -> bool

Check whether a specific element is defined.

Parameters:

Name	Type	Description	Default
name	str	Name of the element	required

Returns:

Type	Description
bool	True if the element is present, False otherwise

NamedObject

Represent a named object within the database.

This class is used to model Cumulocity references.

from_json(object_json) classmethod

Build a new instance from JSON.

The JSON is assumed to be in the format as it is used by the Cumulocity REST API.

:param object_json: JSON object (nested dictionary) representing a named object within Cumulocity :returns: NamedObject instance

to_json()

Convert the instance to JSON.

The JSON format produced by this function is what is used by the Cumulocity REST API.

:returns: JSON object (nested dictionary)

User

Represents a User object within Cumulocity.

Notes

• Only a limited set of properties are actually updatable. Others must be set explicitly using the corresponding API (for example: global roles, permissions, owner, etc.)

assign_global_role(role_id: str)

Assign a global role.

This operation is executed immediately. No call to update is required.

Parameters:

Name	Type	Description	Default
role_id	str	Object ID of an existing global role	required

assign_inventory_roles(object_id: str | int, *roles: str | int | InventoryRole)

Assign an inventory role.

This operation is executed immediately. No call to update is required.

Parameters:

Name	Type	Description	Default
object_id	str	Object ID of an existing managed object (i.e. device group)	required
*roles	str | int | InventoryRole	Existing InventoryRole objects resp. the ID of existing inventory roles	()

create() -> User

Create the User within the database.

Returns:

Type	Description
User	A fresh User object representing what was
User	created within the database (including the ID).

from_json(json: dict) -> User classmethod

retrieve_global_roles() -> List[GlobalRole]

Retrieve user's global roles.

This operation is executed immediately. No call to update is required.

Returns:

Type	Description
List[GlobalRole]	A list of assigned global roles.

retrieve_inventory_role_assignments()

Retrieve the user's inventory roles.

This operation is executed immediately. No call to update is required.

Returns:

Type	Description
	A list of assigned inventory roles.

set_delegate(user_id: str)

Set the delegate for this user.

This operation is executed immediately. No additional call to the update function required.

Parameters:

Name	Type	Description	Default
user_id	str	ID of the delegate to set; can be None to remove a currently set delegate.	required

set_owner(user_id: str)

Set the owner for this user.

This operation is executed immediately. No additional call to the update function required.

Parameters:

Name	Type	Description	Default
user_id	str	ID of the owner to set; can be None to remove a currently set owner.	required

unassign_global_role(role_id)

Unassign a global role.

This operation is executed immediately. No call to update is required.

Parameters:

Name	Type	Description	Default
role_id	str	Object ID of an assigned global role	required

unassign_inventory_roles(*assignment_ids: str)

Unassign an inventory role.

This operation is executed immediately. No call to update is required.

Parameters:

Name	Type	Description	Default
*assignment_ids	str	Object ID of existing inventory role assignments (for this user)	()

update() -> User

Update the User within the database.

Returns:

Type	Description
User	A fresh User object representing what the updated
User	state within the database (including the ID).

CurrentUser

Represents a "current" User object within Cumulocity.

See also https://cumulocity.com/api/core/#tag/Current-User

TotpActivity

User's TOTP activity information.

from_json(object_json: dict) -> CurrentUser.TotpActivity classmethod

Create an object instance from Cumulocity JSON format.

Caveat: this function is primarily for internal use and does not return a full representation of the JSON. It is used for object creation and update within Cumulocity.

Parameters:

Name	Type	Description	Default
object_json	dict	The JSON to parse.	required

Returns:

Type	Description
TotpActivity	A TotpActivity instance.

to_json() -> dict

Create a representation of this object in Cumulocity JSON format.

Caveat: this function is primarily for internal use and does not return a full representation of the object. It is used for object creation and update within Cumulocity.

Returns:

Type	Description
dict	A JSON (nested dict) object.

disable_totp()

Enable the TOTP feature for the current user.

enable_totp()

Enable the TOTP feature for the current user.

from_json(json: dict) -> CurrentUser classmethod

generate_totp_secret() -> (str, str)

Generate a new TOTP secret for the current user.

Returns:

Type	Description
(str, str)	A (str, str) tuple of the raw secret token and the secret URL.

get_tfa_settings() -> TfaSettings

Read the TFA settings for the current user.

Returns:

Type	Description
TfaSettings	A TfaSettings instance.

get_totp_activity() -> TotpActivity

Read the TOTP activity details.

Returns:

Type	Description
TotpActivity	A TotpActivity instance.

get_totp_enabled() -> bool

Check whether the TOTP feature is enabled for the current user.

Returns:

Type	Description
bool	True if the feature is enabled, False otherwise.

is_valid_totp(code: str) -> bool

Verify a TFA/TOTP token.

Parameters:

Name	Type	Description	Default
code	str	A TOTP token	required

Returns:

Type	Description
bool	True if the token was valid, False otherwise,

revoke_totp_secret()

Revoke the currently set TFA/TOTP secret for the current user.

set_totp_activity(activity: TotpActivity)

Update the TFA feature activity details.

Parameters:

Name	Type	Description	Default
activity	TotpActivity	The TFA activity details.	required

update() -> CurrentUser

Update the current user within the database.

Returns:

Type	Description
CurrentUser	A fresh CurrentUser object representing what the updated
CurrentUser	state within the database (including the ID).

update_password(current_password: str, new_password: str)

Update the current user's password:

Parameters:

Name	Type	Description	Default
current_password	str	the current password	required
new_password	str	the new password to set	required

verify_totp(code: str)

Verify a TFA/TOTP token.

Parameters:

Name	Type	Description	Default
code	str	A TOTP token	required

Raises:

Type	Description
ValueError	if the token is invalid/could not be verified.

TfaSettings

TFA settings representation within Cumulocity.

from_json(object_json: dict) -> TfaSettings classmethod

Create an object instance from Cumulocity JSON format.

Caveat: this function is primarily for internal use and does not return a full representation of the JSON. It is used for object creation and update within Cumulocity.

Parameters:

Name	Type	Description	Default
object_json	dict	The JSON to parse.	required

Returns:

Type	Description
TfaSettings	A TfaSettings instance.

to_json() -> dict

Create a representation of this object in Cumulocity JSON format.

Caveat: this function is primarily for internal use and does not return a full representation of the object. It is used for object creation and update within Cumulocity.

Returns:

Type	Description
dict	A JSON (nested dict) object.

GlobalRole

Represents a Global Role object within Cumulocity.

Notes

• Global Roles are called 'groups' in the Cumulocity Standard REST API; However, 'global roles' is the official concept name and therefore used for consistency with the Cumulocity realm.

• Only a limited set of properties are actually updatable. Others must be set explicitly using the corresponding API (for example: permissions).

See also: https://cumulocity.com/api/core/#tag/Groups

add_permissions(*permissions: str)

Add permissions to a global role.

This operation is executed immediately.

Parameters:

Name	Type	Description	Default
*permissions	str	An Iterable of permission ID	()

add_users(*users: str)

Add users to a global role.

This operation is executed immediately.

Parameters:

Name	Type	Description	Default
*users	str	An Iterable of usernames	()

create() -> GlobalRole

Create the GlobalRole within the database.

Returns:

Type	Description
GlobalRole	A fresh GlobalRole object representing what was
GlobalRole	created within the database (including the ID).

from_json(json: dict) -> GlobalRole classmethod

remove_permissions(*permissions)

Remove permissions from a global role.

This operation is executed immediately.

Parameters:

Name	Type	Description	Default
*permissions	str	An Iterable of permission ID	()

remove_users(*users: str)

Remove users from a global role.

This operation is executed immediately.

Parameters:

Name	Type	Description	Default
*users	str	An Iterable of usernames	()

update() -> GlobalRole

Update the GlobalRole within the database.

Returns:

Type	Description
GlobalRole	A fresh GlobalRole object representing what the updated
GlobalRole	state within the database (including the ID).

Permission

Represents a Permission object within Cumulocity.

Notes

• Permissions are not created/deleted but only assigned to users or global roles

See also: https://cumulocity.com/api/core/#tag/Roles

Level

Permission levels.

Scope

Permission scopes.

from_json(json: dict) -> Permission classmethod

to_json(only_updated=False) -> dict

ReadPermission

Represents a read permission within Cumulocity.

WritePermission

Represents a write permission within Cumulocity.

AnyPermission

Represents a read/write permission within Cumulocity.

Operation

Represents an instance of an operation object in Cumulocity.

Instances of this class are returned by functions of the corresponding Operation API. Use this class to create new or update existing operation.

See also: https://cumulocity.com/api/core/#tag/Operations

Status

Operation statuses.

create() -> Operation

Store the Operation within the database.

A fresh Operation object representing what was

Type	Description
Operation	created within the database (including the ID).

from_json(json) -> Operation classmethod

Build a new Operation instance from Cumulocity JSON.

The JSON is assumed to be in the format as it is used by the Cumulocity REST API.

Parameters:

Name	Type	Description	Default
json	dict	JSON object (nested dictionary) representing an operation within Cumulocity	required

Returns:

Type	Description
Operation	Operation object

to_json(only_updated: bool = False) -> dict

update() -> Operation

Update the Operation within the database.

BulkOperation

Represents an instance of a bulk operation object in Cumulocity.

Instances of this class are returned by functions of the corresponding Bulk Operation API. Use this class to create new or update existing operation.

See also: https://cumulocity.com/api/core/#tag/Bulk-operations

GeneralStatus

Bulk Operation general statuses.

Status

Bulk Operation statuses.

create() -> BulkOperation

Store the Bulk Operation within the database.

A fresh BulkOperation object representing what was

Type	Description
BulkOperation	created within the database (including the ID).

from_json(json) -> BulkOperation classmethod

Build a new Operation instance from Cumulocity JSON.

The JSON is assumed to be in the format as it is used by the Cumulocity REST API.

Parameters:

Name	Type	Description	Default
json	dict	JSON object (nested dictionary) representing an operation within Cumulocity	required

Returns:

Type	Description
BulkOperation	Operation object

update() -> BulkOperation

Update the BulkOperation within the database.

A fresh BulkOperation object representing the updated

Type	Description
BulkOperation	object within the database (including the ID).

Application

Represent an instance of an application object in Cumulocity.

Instances of this class are returned by functions of the corresponding API. Use this class to create new or update objects.

See also: https://cumulocity.com/api/core/#tag/Application-API

create() -> Application

Create the Application within the database.

Returns:

Type	Description
Application	A fresh Application object representing what was
Application	created within the database (including the ID).

from_json(json: dict) -> Application classmethod

update() -> Application

Update the Application within the database.

Note: This will only send changed fields to increase performance.

Returns:

Type	Description
Application	A fresh Application object representing what the updated
Application	state within the database (including the ID).

ApplicationSetting

Represent current application settings within in Cumulocity.

Instances of this class are returned by functions of the Applications API. Use this class to create new or update objects.

See also: https://cumulocity.com/api/core/#tag/Current-application

ValueSchema dataclass

Defines a setting's value's schema.

from_json(json) -> ApplicationSetting classmethod

Create a ApplicationSetting instance from Cumulocity JSON format.

ApplicationSubscription

Represent current application subscriptions within in Cumulocity.

Instances of this class are returned by functions of the Applications API. Use this class to create new or update objects.

See also: https://cumulocity.com/api/core/#tag/Current-application

from_json(json) -> ApplicationSubscription classmethod

Create a ApplicationSubscription instance from Cumulocity JSON format.

TenantOption

Represent a tenant option within the database.

Instances of this class are returned by functions of the corresponding Tenant Option API. Use this class to create new or update options.

See also https://cumulocity.com/guides/latest/reference/tenants/#option

create() -> TenantOption

Create a new representation of this option within the database.

Returns:

Type	Description
TenantOption	A fresh TenantOption instance representing the created
TenantOption	option within the database.

See also function TenantOptions.create which doesn't parse the result.

from_json(json: dict) -> TenantOption classmethod

Build a new TenantOption instance from JSON.

The JSON is assumed to be in the format as it is used by the Cumulocity REST API.

Parameters:

Name	Type	Description	Default
json	dict	JSON object (nested dictionary) representing a tenant option within Cumulocity	required

Returns:

Type	Description
TenantOption	TenantOption object

update() -> TenantOption

Write changes to the database.

Returns:

Type	Description
TenantOption	A fresh TenantOption instance representing the updated
TenantOption	object within the database.

See also function TenantOptions.update which doesn't parse the result.

AuditRecord

Represents an Audit Record object within Cumulocity.

Instances of this class are returned by functions of the corresponding Audits API. Use this class to create new or update AuditRecord objects.

See also: https://cumulocity.com/api/core/#tag/Audits

Severity

Audit severity levels.

Type

Audit record source types.

create() -> AuditRecord

Create the AuditRecord within the database.

Returns:

Type	Description
AuditRecord	A fresh AuditRecord object representing what was
AuditRecord	created within the database (including the ID).

from_json(json: dict) -> AuditRecord classmethod

to_json(only_updated: bool = False) -> dict

Change dataclass

Change details fragment within an audit log.