Skip to main content

Handling entity data

The SDK API can be used to read, create and modify entity data.

The starting point for navigating entities is an Entity (or EntityList) object. An Entity object can be obtained in one of the following ways:

  • By means of an entity_id:
entity = api.get_workspace(workspace_id).get_entity(entity_id)
entity = api.get_entity_children(entity_id)
entity = api.get_entity_siblings(entity_id)
entity = api.get_entity_parent(entity_id)
  • By entity type:
entities = api.get_workspace(workspace_id).get_entities_by_type('MyType')
  • Start from the root entities:
entities = api.get_workspace(workspace_id).get_root_entities()
entity = params.entity_field
tip

When using the API to obtain entity data from the current workspace from within an app, you can drop the workspace part and the current workspace will automatically be selected. For example:

entity = api.get_entity(entity_id)  # only works if entity with this id is in the current workspace

Having an Entity object, navigating to relatives is easy, by making use of the below methods:

entity.parent()
entity.children()
entity.siblings()

It's also possible to chain these methods, to navigate even further:

grand_parent = entity.parent().parent()

Or filter on entity type:

gef_children = entity.children(entity_type_names=['GEF'])

Exclude params​

By default, the params of an entity are obtained along with the entity, in all of the above mentioned API calls. In case only the id, name or type of an Entity is desired, the performance of the call can be improved by setting the include_params flag to False. This will exclude the params from being sent during the call:

gef_children = entity.children(entity_type_names=['GEF'], include_params=False)

Obtaining entity data​

Historical revisions of an entity can be obtained by:

revisions = api.get_entity_revisions(entity_id)
revisions = entity.get_revisions()

The params from a certain Revision can be obtained by:

revision = revisions[0]  # e.g. first revision
params = revision.params

Often, you only need the last saved params/summary of an entity. This can be obtained by directly reading the corresponding property on the Entity object:

params = entity.last_saved_params
summary = entity.last_saved_summary

File-type entity​

In case the entity is of file-type, the underlying File can be obtained by:

revisions = api.get_entity_file(entity_id)
revisions = entity.get_file()

Modifying entity data​

The API supports the following methods to create/modify entity data:

api.rename_entity(entity_id, new_name)
api.delete_entity(entity_id)
api.set_entity_params(entity_id, new_params)
api.create_child_entity(parent_entity_id, entity_type_name, new_entity_name)

And corresponding methods on the Entity object:

entity.rename(new_name)
entity.delete()
entity.set_entity_params(new_params)
entity.create_child(entity_type_name, new_entity_name)

List-object​

Some methods return a series of objects in a list-object, instead of an actual list of instances (e.g. EntityList, instead of List[Entity]). This has been done for performance reasons and has little effect on handling, as most normal list operations are still allowed:

children = entity.children()  # children is of type `EntityList`

len(children)  # ok
children[0]  # positive indexing: ok
children[-1]  # negative indexing: ok
for child in children:  # iterating: ok
    # do something with child
note

Slicing of a list-object (e.g. children[0:5]) is not supported.