Entities

Once you've configured your API instances, you can start making requests to retrieve and manipulate Entity records.

Here are a few examples on how to retrieve one or many Entity records.

import bruce_models as BM

# Getting an Entity by ID.
entity = BM.Entity.get(bruce, "entity-id")

# Getting an Entity by ID with a specific scenario.
entity = BM.Entity.get(bruce, "entity-id", scenario="scenario-id-or-key")

# Getting a list of Entities under a specific Entity Type.
entities = BM.Entity.get_list(bruce, entity_type_id="entity-type-id", skip=0, take=50).get("Items")

# Getting a list of Entities under a specific Entity Type with a specific scenario.
entities = BM.Entity.get_list(bruce, entity_type_id="entity-type-id", scenario="scenario-id-or-key", skip=0, take=50).get("Items")

Here is how you can update or create Entity records.

import bruce_models as BM

# If the ID inside the Entity record is not supplied (Bruce/ID), then a new record will be created.
# New records require an Entity Type ID to be specified (Bruce/EntityType.ID).

# Updating an Entity record.
updated = BM.Entity.update(bruce, entity)

# Updating an Entity with a specific scenario.
# Note that a scenario can be specified within the Entity JSON itself.
# The parameter takes precedence over the JSON.
updated = BM.Entity.update(bruce, entity, scenario="scenario-id-or-key")

# Updating a list of Entities.
updated = BM.Entity.update_list(bruce, entities).get("Items")

# Updating a list of Entities with a specific scenario.
# Note that a scenario can be specified within the Entity JSON itself.
# The parameter takes precedence over the JSON.
updated = BM.Entity.update_list(bruce, entities, scenario="scenario-id-or-key").get("Items")

API responses typically include trace, warnings, and errors alongside the returned data. For singular Entity requests, these are available under the Bruce property, for lists they are available at the root level as the Entity data is underneath the Items property.

import bruce_models as BM

entity = BM.Entity.get(bruce, "entity-id")

# Please note that these properties are only available when there is something to report.
# Access them directly when it comes to lists of Entities. Eg: response.get("Error").

# Errors encountered that didn't stop the request.
# This usually includes errors related to propagating changes to external data sources.
errors = entity.get("Bruce").get("Error")

# Warnings encountered that didn't stop the request.
# An example is failing to create/update a Historic record because the date couldn't be resolved.
warnings = entity.get("Bruce").get("Warning")

# Trace information to see how long certain operations took.
# If you are experiencing slowness, this can give insight into where the bottleneck is.
# Eg: an external source update was slow.
trace = entity.get("Bruce").get("Trace")