Entity Types

albert.collections.entity_types.EntityTypeCollection

EntityTypeCollection(*, session: AlbertSession)

Bases: BaseCollection

Manage Entity Types in the Albert platform.

An Entity Type is a configurable definition that determines how a particular kind of entity (a Task, Inventory Item, Project, Data Template, Parameter Group, or Lot) looks and behaves. It groups together the custom category the entity falls under, which CustomField values appear on it, how the standard Notes/Tags/Due Date fields are shown or required, and how searches for related entities are built.

Entity Types come in two flavors (see EntityTypeType): system types ship with the platform, while custom types are defined by an organization to model its own categories of work. Each type is scoped to a single service (see EntityServiceType), such as tasks or inventories.

Entity Types are referenced by their Entity Type ID (format ETT...). This is configuration/schema-level data; most users read Entity Types to understand how their platform is set up rather than creating them frequently.

This collection is accessed as client.entity_types.

Example

from albert import Albert
from albert.resources.entity_types import EntityServiceType
client = Albert()
# List the entity types configured for Tasks
for et in client.entity_types.get_all(service=EntityServiceType.TASKS):
    print(et.id, et.label)

Parameters:

Name	Type	Description	Default
session	AlbertSession	The authenticated Albert session used for API calls.	required

Attributes:

Name	Type	Description
base_path	str	The base API route for entity type requests.

Methods:

Name	Description
create	Create a new entity type.
get_by_id	Get a single entity type by its ID.
get_all	Iterate over entity types, optionally filtered by service.
update	Update an existing entity type.
delete	Delete an entity type by its ID.
get_rules	Get the conditional field rules configured for an entity type.
set_rules	Create or replace the conditional field rules for an entity type.
delete_rules	Remove the conditional field rules for an entity type.

Parameters:

Name	Type	Description	Default
session	AlbertSession	The authenticated Albert session used for API calls.	required

Source code in src/albert/collections/entity_types.py

def __init__(self, *, session: AlbertSession):
    """Initialize an EntityTypeCollection.

    Parameters
    ----------
    session : AlbertSession
        The authenticated Albert session used for API calls.
    """
    super().__init__(session=session)
    self.base_path = f"/api/{EntityTypeCollection._api_version}/entitytypes"

base_path

base_path = (
    f"/api/{EntityTypeCollection._api_version}/entitytypes"
)

get_by_id

get_by_id(*, id: EntityTypeId) -> EntityType

Get a single entity type by its ID.

Example

et = client.entity_types.get_by_id(id="ETT1")
et.label
# 'Formulation Task'

Parameters:

Name	Type	Description	Default
id	EntityTypeId	The Entity Type ID (format ETT...).	required

Returns:

Type	Description
EntityType	The fully populated entity type.

Source code in src/albert/collections/entity_types.py

@validate_call
def get_by_id(self, *, id: EntityTypeId) -> EntityType:
    """Get a single entity type by its ID.

    !!! example
        ```python
        et = client.entity_types.get_by_id(id="ETT1")
        et.label
        # 'Formulation Task'
        ```

    Parameters
    ----------
    id : EntityTypeId
        The Entity Type ID (format ``ETT...``).

    Returns
    -------
    EntityType
        The fully populated entity type.
    """
    response = self.session.get(f"{self.base_path}/{id}")
    return EntityType(**response.json())

create

create(*, entity_type: EntityType) -> EntityType

Create a new entity type.

Example

from albert import Albert
from albert.resources.entity_types import (
    EntityCategory,
    EntityServiceType,
    EntityType,
)
client = Albert()
new_type = EntityType(
    label="Stability Task",
    service=EntityServiceType.TASKS,
    category=EntityCategory.PROPERTY,
)
created = client.entity_types.create(entity_type=new_type)
created.id
# 'ETT1'

Parameters:

Name	Type	Description	Default
entity_type	EntityType	The entity type to create. label and service are required, and category is required when the service is tasks or inventories.	required

Returns:

Type	Description
EntityType	The newly created entity type, populated with its assigned Entity Type ID.

Source code in src/albert/collections/entity_types.py

def create(self, *, entity_type: EntityType) -> EntityType:
    """Create a new entity type.

    !!! example
        ```python
        from albert import Albert
        from albert.resources.entity_types import (
            EntityCategory,
            EntityServiceType,
            EntityType,
        )
        client = Albert()
        new_type = EntityType(
            label="Stability Task",
            service=EntityServiceType.TASKS,
            category=EntityCategory.PROPERTY,
        )
        created = client.entity_types.create(entity_type=new_type)
        created.id
        # 'ETT1'
        ```

    Parameters
    ----------
    entity_type : EntityType
        The entity type to create. ``label`` and ``service`` are required, and
        ``category`` is required when the service is ``tasks`` or
        ``inventories``.

    Returns
    -------
    EntityType
        The newly created entity type, populated with its assigned Entity
        Type ID.
    """
    response = self.session.post(
        self.base_path, json=entity_type.model_dump(by_alias=True, exclude_none=True)
    )
    return EntityType(**response.json())

update

update(*, entity_type: EntityType) -> EntityType

Update an existing entity type.

Fetch the entity type (e.g. with get_by_id), modify the updatable fields on the returned object, then pass it here. Only the fields listed in Notes are applied; changes to other fields are ignored.

Example

et = client.entity_types.get_by_id(id="ETT1")
et.label = "Updated label"
updated = client.entity_types.update(entity_type=et)
updated.label
# 'Updated label'

Parameters:

Name	Type	Description	Default
entity_type	EntityType	The entity type to update. Must have a valid id.	required

Returns:

Type	Description
EntityType	The updated entity type.

Notes

The following fields can be updated: custom_fields, label, locked_template, search_query_string, standard_field_required, standard_field_visibility, template_based.

Source code in src/albert/collections/entity_types.py

def update(self, *, entity_type: EntityType) -> EntityType:
    """Update an existing entity type.

    Fetch the entity type (e.g. with [`get_by_id`][albert.collections.entity_types.EntityTypeCollection.get_by_id]), modify the updatable
    fields on the returned object, then pass it here. Only the fields listed
    in Notes are applied; changes to other fields are ignored.

    !!! example
        ```python
        et = client.entity_types.get_by_id(id="ETT1")
        et.label = "Updated label"
        updated = client.entity_types.update(entity_type=et)
        updated.label
        # 'Updated label'
        ```

    Parameters
    ----------
    entity_type : EntityType
        The entity type to update. Must have a valid ``id``.

    Returns
    -------
    EntityType
        The updated entity type.

    Notes
    -----
    The following fields can be updated: ``custom_fields``, ``label``,
    ``locked_template``, ``search_query_string``, ``standard_field_required``,
    ``standard_field_visibility``, ``template_based``.
    """
    current_entity_type = self.get_by_id(id=entity_type.id)
    patch = self._generate_patch_payload(
        existing=current_entity_type,
        updated=entity_type,
        generate_metadata_diff=False,
        stringify_values=False,
    )

    # Add special attribute updates to the patch
    special_patches = self._generate_special_attribute_patches(
        existing=current_entity_type, updated=entity_type
    )
    patch.data.extend(special_patches)

    self.session.patch(
        f"{self.base_path}/{entity_type.id}",
        json=patch.model_dump(mode="json", by_alias=True, exclude_none=True),
    )
    return self.get_by_id(id=entity_type.id)

delete

delete(*, id: EntityTypeId) -> None

Delete an entity type by its ID.

Example

client.entity_types.delete(id="ETT1")

Parameters:

Name	Type	Description	Default
id	EntityTypeId	The Entity Type ID to delete (format ETT...).	required

Returns:

Type	Description
None

Source code in src/albert/collections/entity_types.py

@validate_call
def delete(self, *, id: EntityTypeId) -> None:
    """Delete an entity type by its ID.

    !!! example
        ```python
        client.entity_types.delete(id="ETT1")
        ```

    Parameters
    ----------
    id : EntityTypeId
        The Entity Type ID to delete (format ``ETT...``).

    Returns
    -------
    None
    """
    self.session.delete(f"{self.base_path}/{id}")

get_rules

get_rules(*, id: EntityTypeId) -> list[EntityTypeRule]

Get the conditional field rules configured for an entity type.

A rule (see EntityTypeRule) makes one field's behavior depend on the value of another: for example, showing, hiding, requiring, or setting default options on a target field when a trigger custom field takes a certain value.

Example

rules = client.entity_types.get_rules(id="ETT1")
[r.id for r in rules]
# ['RUL1', 'RUL2']

Parameters:

Name	Type	Description	Default
id	EntityTypeId	The Entity Type ID to get the rules for (format ETT...).	required

Returns:

Type	Description
list[EntityTypeRule]	The configured rules for the entity type.

Source code in src/albert/collections/entity_types.py

@validate_call
def get_rules(self, *, id: EntityTypeId) -> list[EntityTypeRule]:
    """Get the conditional field rules configured for an entity type.

    A rule (see [`EntityTypeRule`][albert.resources.entity_types.EntityTypeRule]) makes
    one field's behavior depend on the value of another: for example, showing,
    hiding, requiring, or setting default options on a target field when a
    trigger custom field takes a certain value.

    !!! example
        ```python
        rules = client.entity_types.get_rules(id="ETT1")
        [r.id for r in rules]
        # ['RUL1', 'RUL2']
        ```

    Parameters
    ----------
    id : EntityTypeId
        The Entity Type ID to get the rules for (format ``ETT...``).

    Returns
    -------
    list[EntityTypeRule]
        The configured rules for the entity type.
    """
    response = self.session.get(f"{self.base_path}/rules/{id}")
    return [EntityTypeRule(**rule) for rule in response.json()]

set_rules

set_rules(
    *, id: EntityTypeId, rules: list[EntityTypeRule]
) -> list[EntityTypeRule]

Create or replace the conditional field rules for an entity type.

This replaces the entity type's full set of rules with the ones provided. To read the current rules first, use get_rules; to remove all rules, use delete_rules.

Example

existing = client.entity_types.get_rules(id="ETT1")
updated = client.entity_types.set_rules(id="ETT1", rules=existing)

Parameters:

Name	Type	Description	Default
id	EntityTypeId	The Entity Type ID to set the rules for (format ETT...).	required
rules	list[EntityTypeRule]	The rules to apply to the entity type.	required

Returns:

Type	Description
list[EntityTypeRule]	The updated rules as registered in Albert.

Source code in src/albert/collections/entity_types.py

@validate_call
def set_rules(self, *, id: EntityTypeId, rules: list[EntityTypeRule]) -> list[EntityTypeRule]:
    """Create or replace the conditional field rules for an entity type.

    This replaces the entity type's full set of rules with the ones provided.
    To read the current rules first, use [`get_rules`][albert.collections.entity_types.EntityTypeCollection.get_rules]; to remove all
    rules, use [`delete_rules`][albert.collections.entity_types.EntityTypeCollection.delete_rules].

    !!! example
        ```python
        existing = client.entity_types.get_rules(id="ETT1")
        updated = client.entity_types.set_rules(id="ETT1", rules=existing)
        ```

    Parameters
    ----------
    id : EntityTypeId
        The Entity Type ID to set the rules for (format ``ETT...``).
    rules : list[EntityTypeRule]
        The rules to apply to the entity type.

    Returns
    -------
    list[EntityTypeRule]
        The updated rules as registered in Albert.
    """
    response = self.session.put(
        f"{self.base_path}/rules/{id}",
        json=[rule.model_dump(exclude_none=True, by_alias=True) for rule in rules],
    )
    return [EntityTypeRule(**rule) for rule in response.json()]

delete_rules

delete_rules(*, id: EntityTypeId) -> None

Delete all conditional field rules for an entity type.

Example

client.entity_types.delete_rules(id="ETT1")

Parameters:

Name	Type	Description	Default
id	EntityTypeId	The Entity Type ID to remove rules from (format ETT...).	required

Returns:

Type	Description
None

Source code in src/albert/collections/entity_types.py

@validate_call
def delete_rules(self, *, id: EntityTypeId) -> None:
    """Delete all conditional field rules for an entity type.

    !!! example
        ```python
        client.entity_types.delete_rules(id="ETT1")
        ```

    Parameters
    ----------
    id : EntityTypeId
        The Entity Type ID to remove rules from (format ``ETT...``).

    Returns
    -------
    None
    """
    self.session.delete(f"{self.base_path}/rules/{id}")

get_all

get_all(
    *,
    service: EntityServiceType | None = None,
    start_key: str | None = None,
    order: OrderBy | None = None,
    max_items: int | None = None,
) -> Iterator[EntityType]

Iterate over entity types matching the given filters.

Results are returned as a lazily paginated iterator, so iterating fetches additional pages on demand.

Example

from albert.resources.entity_types import EntityServiceType
for et in client.entity_types.get_all(
    service=EntityServiceType.INVENTORIES,
    max_items=25,
):
    print(et.id, et.label)

Parameters:

Name	Type	Description	Default
service	EntityServiceType	Only return entity types associated with this service (e.g. tasks or inventories). Defaults to all services.	None
start_key	str	Provide the lastKey from a previous request to resume pagination.	None
order	OrderBy	Sort direction (ascending or descending). Defaults to the server order.	None
max_items	int	Maximum number of items to return in total. If None, iterates over all matches.	None

Returns:

Type	Description
Iterator[EntityType]	A lazily paginated iterator of matching entity types.

Source code in src/albert/collections/entity_types.py

def get_all(
    self,
    *,
    service: EntityServiceType | None = None,
    start_key: str | None = None,
    order: OrderBy | None = None,
    max_items: int | None = None,
) -> Iterator[EntityType]:
    """Iterate over entity types matching the given filters.

    Results are returned as a lazily paginated iterator, so iterating fetches
    additional pages on demand.

    !!! example
        ```python
        from albert.resources.entity_types import EntityServiceType
        for et in client.entity_types.get_all(
            service=EntityServiceType.INVENTORIES,
            max_items=25,
        ):
            print(et.id, et.label)
        ```

    Parameters
    ----------
    service : EntityServiceType, optional
        Only return entity types associated with this service (e.g. ``tasks``
        or ``inventories``). Defaults to all services.
    start_key : str, optional
        Provide the ``lastKey`` from a previous request to resume pagination.
    order : OrderBy, optional
        Sort direction (ascending or descending). Defaults to the server order.
    max_items : int, optional
        Maximum number of items to return in total. If None, iterates over all
        matches.

    Returns
    -------
    Iterator[EntityType]
        A lazily paginated iterator of matching entity types.
    """
    params = {
        "service": service,
        "limit": max_items,
        "startKey": start_key,
        "orderBy": order,
    }
    return AlbertPaginator(
        mode=PaginationMode.KEY,
        path=self.base_path,
        params=params,
        session=self.session,
        deserialize=lambda items: [EntityType(**item) for item in items],
        max_items=max_items,
    )