core

core

DomoGroup dataclass

DomoGroup(
    auth: DomoAuth,
    id: str,
    raw: dict,
    name: str = None,
    type: str = None,
    is_system: bool = None,
    description: str = None,
    members_id_ls: list[str] = list(),
    owner_id_ls: list[str] = list(),
    members_ls: list[dict] = list(),
    owner_ls: list[dict] = list(),
    custom_attributes: dict = dict(),
)

Bases: DomoEntity

Represents a Domo group.

A group in Domo can contain multiple users and has properties like name, type, and ownership. System groups are automatically created and managed by Domo.

Attributes:

Name	Type	Description
id	str	The unique identifier of the group.
name	str	The name of the group.
type	str	The group type (e.g., "open", "system").
is_system	bool	Whether this is a system-managed group.
description	str	A description of the group.
members_id_ls	list[str]	List of user IDs that are members of this group.
owner_id_ls	list[str]	List of user IDs that own this group.
members_ls	list[dict]	List of member objects with full details.
owner_ls	list[dict]	List of owner objects with full details.
custom_attributes	dict	Custom attributes associated with the group.

display_url property

display_url: str

Generate the URL to display this group in the Domo admin interface.

create_from_name async classmethod

create_from_name(
    auth: DomoAuth,
    group_name: str | None = None,
    group_type: GroupType_Enum | str = "open",
    description: str | None = None,
    is_include_manage_groups_role: bool = True,
    *,
    context: RouteContext | None = None,
    **context_kwargs: Any
) -> DomoGroup

Create a new group in Domo.

Creates a new group with the specified name and optional type and description.

Parameters:

Name	Type	Description	Default
auth	DomoAuth	Authentication object for Domo API access.	required
group_name	str | None	The name of the group to create.	None
group_type	GroupType_Enum | str	The type of the group (e.g., "open", "system"). Defaults to "open". Should use GroupType_Enum for type safety.	'open'
description	str | None	Optional description for the group.	None
is_include_manage_groups_role	bool	Whether to include the manage groups role. Defaults to True. (This parameter is not passed to the API call.)	True
context	RouteContext | None	Optional RouteContext for configuring the request.	None
**context_kwargs	Any	Additional keyword arguments passed to RouteContext.build_context().	{}

Returns:

Type	Description
DomoGroup	A DomoGroup instance representing the newly created group.

Source code in src/crew_dcs/classes/DomoGroup/core.py

@classmethod
async def create_from_name(
    cls,
    auth: DomoAuth,
    group_name: str | None = None,
    group_type: GroupType_Enum | str = "open",  # use GroupType_Enum
    description: str | None = None,
    is_include_manage_groups_role: bool = True,
    *,
    context: RouteContext | None = None,
    **context_kwargs: Any,
) -> "DomoGroup":
    """Create a new group in Domo.

    Creates a new group with the specified name and optional type and description.

    Args:
        auth: Authentication object for Domo API access.
        group_name: The name of the group to create.
        group_type: The type of the group (e.g., "open", "system"). Defaults to "open".
            Should use GroupType_Enum for type safety.
        description: Optional description for the group.
        is_include_manage_groups_role: Whether to include the manage groups role.
            Defaults to True. (This parameter is not passed to the API call.)
        context: Optional RouteContext for configuring the request.
        **context_kwargs: Additional keyword arguments passed to RouteContext.build_context().

    Returns:
        A DomoGroup instance representing the newly created group.
    """
    context = RouteContext.build_context(context=context, **context_kwargs)

    res = await group_routes.create_group(
        auth=auth,
        group_name=group_name,
        group_type=group_type,
        description=description,
        context=context,
    )

    domo_group = cls.from_dict(auth=auth, obj=res.response)

    return domo_group  # noqa: RET504

delete async

delete(
    *,
    context: RouteContext | None = None,
    **context_kwargs: Any
) -> ResponseGetData

Delete this group from Domo.

Removes the group from Domo via the API. The API response is returned with the parent class name attached.

Parameters:

Name	Type	Description	Default
context	RouteContext | None	Optional RouteContext for configuring the request.	None
**context_kwargs	Any	Additional keyword arguments passed to RouteContext.build_context().	{}

Returns:

Type	Description
ResponseGetData	The API response object with parent_class set to self.class.name
ResponseGetData	(typically "DomoGroup", or a subclass's name if called on one).

Source code in src/crew_dcs/classes/DomoGroup/core.py

async def delete(
    self,
    *,
    context: RouteContext | None = None,
    **context_kwargs: Any,
) -> rgd.ResponseGetData:
    """Delete this group from Domo.

    Removes the group from Domo via the API. The API response is returned with
    the parent class name attached.

    Args:
        context: Optional RouteContext for configuring the request.
        **context_kwargs: Additional keyword arguments passed to RouteContext.build_context().

    Returns:
        The API response object with parent_class set to self.__class__.__name__
        (typically "DomoGroup", or a subclass's name if called on one).
    """
    context = RouteContext.build_context(context=context, **context_kwargs)

    res = await group_routes.delete_groups(
        auth=self.auth,
        group_ids=[str(self.id)],
        context=context,
    )

    res.parent_class = self.__class__.__name__

    return res

from_dict classmethod

from_dict(auth: DomoAuth, obj: dict[str, Any]) -> DomoGroup

Create a DomoGroup instance from a dictionary.

Extracts group data from various API response formats and creates a DomoGroup object. Handles both "id" and "groupId" keys, and both "type" and "groupType" keys.

Parameters:

Name	Type	Description	Default
auth	DomoAuth	Authentication object for Domo API access.	required
obj	dict[str, Any]	Dictionary containing group data from the Domo API response.	required

Returns:

Type	Description
DomoGroup	A DomoGroup instance initialized from the provided dictionary.

Source code in src/crew_dcs/classes/DomoGroup/core.py

@classmethod
def from_dict(cls, auth: DomoAuth, obj: dict[str, Any]) -> "DomoGroup":
    """Create a DomoGroup instance from a dictionary.

    Extracts group data from various API response formats and creates a DomoGroup
    object. Handles both "id" and "groupId" keys, and both "type" and "groupType" keys.

    Args:
        auth: Authentication object for Domo API access.
        obj: Dictionary containing group data from the Domo API response.

    Returns:
        A DomoGroup instance initialized from the provided dictionary.
    """
    return cls(
        auth=auth,
        id=obj.get("id") or obj.get("groupId"),
        name=obj.get("name"),
        description=obj.get("description"),
        type=obj.get("type") or obj.get("groupType"),
        members_id_ls=obj.get("userIds"),
        owner_ls=obj.get("owners"),
        raw=obj,
    )

get_by_id async classmethod

get_by_id(
    auth: DomoAuth,
    group_id: str,
    return_raw: bool = False,
    *,
    context: RouteContext | None = None,
    **context_kwargs: Any
) -> ResponseGetData | DomoGroup

Fetch a group by its ID from the Domo API.

Retrieves group details from Domo using the provided group ID and authentication.

Parameters:

Name	Type	Description	Default
auth	DomoAuth	Authentication object for Domo API access.	required
group_id	str	The unique identifier of the group to fetch.	required
return_raw	bool	If True, return the raw API response; otherwise return a DomoGroup instance. Defaults to False.	False
context	RouteContext | None	Optional RouteContext for configuring the request.	None
**context_kwargs	Any	Additional keyword arguments passed to RouteContext.build_context().	{}

Returns:

Type	Description
ResponseGetData | DomoGroup	The fetched group, or the raw API response if return_raw is True.

Source code in src/crew_dcs/classes/DomoGroup/core.py

@classmethod
async def get_by_id(
    cls,
    auth: DomoAuth,
    group_id: str,
    return_raw: bool = False,
    *,
    context: RouteContext | None = None,
    **context_kwargs: Any,
) -> "rgd.ResponseGetData | DomoGroup":
    """Fetch a group by its ID from the Domo API.

    Retrieves group details from Domo using the provided group ID and authentication.

    Args:
        auth: Authentication object for Domo API access.
        group_id: The unique identifier of the group to fetch.
        return_raw: If True, return the raw API response; otherwise return a
            DomoGroup instance. Defaults to False.
        context: Optional RouteContext for configuring the request.
        **context_kwargs: Additional keyword arguments passed to RouteContext.build_context().

    Returns:
        The fetched group, or the raw API response if return_raw is True.
    """
    context = RouteContext.build_context(context=context, **context_kwargs)

    res = await group_routes.get_group_by_id(
        auth=auth,
        group_id=group_id,
        context=context,
    )
    if return_raw:
        return res

    dg = cls.from_dict(auth=auth, obj=res.response)

    # await dg.Membership.get_owners()
    # await dg.Membership.get_members() # disabled because causes recursion

    return dg  # noqa: RET504

get_entity_by_id async classmethod

get_entity_by_id(entity_id, **kwargs)

Internal method to get an entity by ID.

Source code in src/crew_dcs/classes/DomoGroup/core.py

@classmethod
async def get_entity_by_id(cls, entity_id, **kwargs):
    """
    Internal method to get an entity by ID.
    """
    return await cls.get_by_id(auth=cls.auth, group_id=entity_id, **kwargs)

get_membership async

get_membership(
    return_raw: bool = False,
    *,
    context: RouteContext | None = None,
    **context_kwargs: Any
)

Load this group's member list.

Returns raw route response when return_raw=True; otherwise returns the member payload list and updates members_ls / members_id_ls.

Source code in src/crew_dcs/classes/DomoGroup/core.py

async def get_membership(
    self,
    return_raw: bool = False,
    *,
    context: RouteContext | None = None,
    **context_kwargs: Any,
):
    """Load this group's member list.

    Returns raw route response when return_raw=True; otherwise returns the
    member payload list and updates ``members_ls`` / ``members_id_ls``.
    """
    context = RouteContext.build_context(context=context, **context_kwargs)

    res = await group_routes.get_group_membership(
        auth=self.auth,
        group_id=self.id,
        context=context,
    )

    if return_raw:
        return res

    self.members_ls = res.response or []
    self.members_id_ls = [str(member.get("id")) for member in self.members_ls]
    return self.members_ls

update_metadata async

update_metadata(
    auth: DomoAuth = None,
    group_name: str | None = None,
    group_type: str | None = None,
    description: str | None = None,
    additional_params: dict | None = None,
    return_raw: bool = False,
    *,
    context: RouteContext | None = None,
    **context_kwargs: Any
) -> ResponseGetData | DomoGroup

Update the group's metadata (name, type, description).

Updates the group in Domo and refreshes the current instance with the latest values. If the update fails due to a group type change, raises DomoGroupError with a helpful message.

Parameters:

Name	Type	Description	Default
auth	DomoAuth	Authentication object for Domo API access. If None, uses self.auth.	None
group_name	str | None	New name for the group. If None, name is not updated.	None
group_type	str | None	New type for the group. If None, type is not updated. Should use GroupType_Enum for type safety.	None
description	str | None	New description for the group. If None, description is not updated.	None
additional_params	dict | None	Additional parameters to pass to the API.	None
return_raw	bool	If True, return the raw API response; otherwise return self. Defaults to False.	False
context	RouteContext | None	Optional RouteContext for configuring the request.	None
**context_kwargs	Any	Additional keyword arguments passed to RouteContext.build_context().	{}

Returns:

Type	Description
ResponseGetData | DomoGroup	If return_raw is True, returns the raw API response. Otherwise, returns self
ResponseGetData | DomoGroup	with updated name, description, and type attributes.

Raises:

Type	Description
DomoGroupError	If the group type change fails, with a message suggesting to use additional_params instead.
Group_CRUD_Error	Other CRUD operation errors from the API.

Source code in src/crew_dcs/classes/DomoGroup/core.py

async def update_metadata(
    self,
    auth: DomoAuth = None,
    group_name: str | None = None,
    group_type: str | None = None,  # use GroupType_Enum
    description: str | None = None,
    additional_params: dict | None = None,
    return_raw: bool = False,
    *,
    context: RouteContext | None = None,
    **context_kwargs: Any,
) -> "rgd.ResponseGetData | DomoGroup":
    """Update the group's metadata (name, type, description).

    Updates the group in Domo and refreshes the current instance with the latest
    values. If the update fails due to a group type change, raises DomoGroupError
    with a helpful message.

    Args:
        auth: Authentication object for Domo API access. If None, uses self.auth.
        group_name: New name for the group. If None, name is not updated.
        group_type: New type for the group. If None, type is not updated.
            Should use GroupType_Enum for type safety.
        description: New description for the group. If None, description is not updated.
        additional_params: Additional parameters to pass to the API.
        return_raw: If True, return the raw API response; otherwise return self.
            Defaults to False.
        context: Optional RouteContext for configuring the request.
        **context_kwargs: Additional keyword arguments passed to RouteContext.build_context().

    Returns:
        If return_raw is True, returns the raw API response. Otherwise, returns self
        with updated name, description, and type attributes.

    Raises:
        DomoGroupError: If the group type change fails, with a message suggesting
            to use additional_params instead.
        Group_CRUD_Error: Other CRUD operation errors from the API.
    """
    auth = auth or self.auth
    context = RouteContext.build_context(context=context, **context_kwargs)

    res = None
    try:
        res = await group_routes.update_group(
            auth=auth,
            group_id=self.id,
            group_name=group_name,
            group_type=group_type,
            description=description,
            additional_params=additional_params,
            context=context,
        )

        if return_raw:
            return res

        updated_group = await DomoGroup.get_by_id(
            auth=auth, group_id=self.id, context=context
        )

        self.name = updated_group.name or self.name
        self.description = updated_group.description or self.description
        self.type = updated_group.type or self.type

    except Group_CRUD_Error as e:
        if group_type != self.type:
            raise DomoGroupError(
                cls_instance=self,
                entity_name=self.name,
                entity_id=self.id,
                message=f"probably cannot change group_type to '{group_type}' from current type '{self.type}' consider passing `addtional_parameters`",
            ) from e

        raise

    return self

DomoGroups dataclass

DomoGroups(
    auth: DomoAuth,
    is_hide_system_groups: bool = None,
    groups: list[DomoGroup] = None,
)

Bases: DomoManager

Manager for Domo groups.

Provides methods to retrieve, search, and manage multiple Domo groups. Handles operations on collections of groups including toggling system group visibility.

Attributes:

Name	Type	Description
is_hide_system_groups	bool	Tracks whether system groups are currently hidden.
groups	list[DomoGroup]	List of DomoGroup instances.

get async

get(
    is_hide_system_groups: bool = True,
    return_raw: bool = False,
    *,
    context: RouteContext | None = None,
    **context_kwargs: Any
) -> ResponseGetData | list[DomoGroup]

Fetch all groups from Domo.

Retrieves all groups from the Domo API, optionally hiding or showing system groups. First toggles the system group visibility setting, then fetches all groups and converts them to DomoGroup instances.

Parameters:

Name	Type	Description	Default
is_hide_system_groups	bool	If True, hide system groups in the results. Defaults to True.	True
return_raw	bool	If True, return the raw API response; otherwise return a list of DomoGroup instances. Defaults to False.	False
context	RouteContext | None	Optional RouteContext for configuring the request.	None
**context_kwargs	Any	Additional keyword arguments passed to RouteContext.build_context().	{}

Returns:

Type	Description
ResponseGetData | list[DomoGroup]	If return_raw is True, returns the raw API response. Otherwise, returns
ResponseGetData | list[DomoGroup]	a list of DomoGroup instances (possibly empty).

Source code in src/crew_dcs/classes/DomoGroup/core.py

async def get(
    self,
    is_hide_system_groups: bool = True,
    return_raw: bool = False,
    *,
    context: RouteContext | None = None,
    **context_kwargs: Any,
) -> "rgd.ResponseGetData | list[DomoGroup]":
    """Fetch all groups from Domo.

    Retrieves all groups from the Domo API, optionally hiding or showing system groups.
    First toggles the system group visibility setting, then fetches all groups and
    converts them to DomoGroup instances.

    Args:
        is_hide_system_groups: If True, hide system groups in the results.
            Defaults to True.
        return_raw: If True, return the raw API response; otherwise return a list
            of DomoGroup instances. Defaults to False.
        context: Optional RouteContext for configuring the request.
        **context_kwargs: Additional keyword arguments passed to RouteContext.build_context().

    Returns:
        If return_raw is True, returns the raw API response. Otherwise, returns
        a list of DomoGroup instances (possibly empty).
    """
    context = RouteContext.build_context(context=context, **context_kwargs)

    await self.toggle_show_system_groups(
        is_hide_system_groups=is_hide_system_groups,
        context=context,
    )

    res = await group_routes.get_all_groups(
        auth=self.auth,
        context=context,
    )

    if return_raw:
        return res

    if len(res.response):
        self.groups = self._groups_to_domo_group(
            json_list=res.response, auth=self.auth
        )

    else:
        self.groups = []

    return self.groups

get_is_system_groups_visible async

get_is_system_groups_visible(
    return_raw: bool = False,
    *,
    context: RouteContext | None = None,
    **context_kwargs: Any
) -> ResponseGetData | bool

Check if system groups are currently visible.

Fetches the current visibility setting for system groups from the Domo API and updates is_hide_system_groups.

Parameters:

Name	Type	Description	Default
return_raw	bool	If True, return the raw API response; otherwise return the boolean visibility value. Defaults to False.	False
context	RouteContext | None	Optional RouteContext for configuring the request.	None
**context_kwargs	Any	Additional keyword arguments passed to RouteContext.build_context().	{}

Returns:

Type	Description
ResponseGetData | bool	If return_raw is True, returns the raw API response. Otherwise, returns
ResponseGetData | bool	a boolean indicating whether system groups are hidden (is_hide_system_groups).

Source code in src/crew_dcs/classes/DomoGroup/core.py

async def get_is_system_groups_visible(
    self,
    return_raw: bool = False,
    *,
    context: RouteContext | None = None,
    **context_kwargs: Any,
) -> "rgd.ResponseGetData | bool":
    """Check if system groups are currently visible.

    Fetches the current visibility setting for system groups from the Domo API
    and updates is_hide_system_groups.

    Args:
        return_raw: If True, return the raw API response; otherwise return the
            boolean visibility value. Defaults to False.
        context: Optional RouteContext for configuring the request.
        **context_kwargs: Additional keyword arguments passed to RouteContext.build_context().

    Returns:
        If return_raw is True, returns the raw API response. Otherwise, returns
        a boolean indicating whether system groups are hidden (is_hide_system_groups).
    """
    context = RouteContext.build_context(context=context, **context_kwargs)

    res = await group_routes.is_system_groups_visible(
        auth=self.auth,
        context=context,
    )

    if return_raw:
        return res

    # res.response["value"] is the `groups.system.enabled` (i.e. visible)
    # flag, same field toggle_show_system_groups below inverts for the
    # same reason — is_hide_system_groups must track its own negation.
    self.is_hide_system_groups = not res.response["value"]

    return self.is_hide_system_groups

search_by_name async

search_by_name(
    group_name: list[str],
    is_hide_system_groups: bool | None = None,
    only_allow_one: bool = True,
    return_raw: bool = False,
    *,
    context: RouteContext | None = None,
    **context_kwargs: Any
) -> DomoGroup | list[DomoGroup]

Search for groups by name.

Fetches all groups and filters them by name (case-insensitive). Can return a single matching group or a list of matches depending on only_allow_one.

Parameters:

Name	Type	Description	Default
group_name	list[str]	Group name or list of group names to search for (case-insensitive).	required
is_hide_system_groups	bool | None	Whether to hide system groups. If None, uses the current setting. Defaults to None.	None
only_allow_one	bool	If True, return only the first matching group and raise DomoGroupError if none found. If False, return all matching groups. Defaults to True.	True
return_raw	bool	If True, return the raw API response from get(). Defaults to False.	False
context	RouteContext | None	Optional RouteContext for configuring the request.	None
**context_kwargs	Any	Additional keyword arguments passed to RouteContext.build_context().	{}

Returns:

Type	Description
DomoGroup | list[DomoGroup]	If return_raw is True, returns the raw API response from get(). If only_allow_one
DomoGroup | list[DomoGroup]	is True, returns a single DomoGroup. Otherwise, returns a list of DomoGroup instances.

Raises:

Type	Description
DomoGroupError	If no groups match the search criteria and only_allow_one is True.

Source code in src/crew_dcs/classes/DomoGroup/core.py

async def search_by_name(
    self,
    group_name: list[str],
    is_hide_system_groups: bool | None = None,
    only_allow_one: bool = True,
    return_raw: bool = False,
    *,
    context: RouteContext | None = None,
    **context_kwargs: Any,
) -> (
    DomoGroup | list[DomoGroup]
):  # by default returns one DomoGroup, but can return a list of DomoGroups
    """Search for groups by name.

    Fetches all groups and filters them by name (case-insensitive). Can return
    a single matching group or a list of matches depending on only_allow_one.

    Args:
        group_name: Group name or list of group names to search for (case-insensitive).
        is_hide_system_groups: Whether to hide system groups. If None, uses the
            current setting. Defaults to None.
        only_allow_one: If True, return only the first matching group and raise
            DomoGroupError if none found. If False, return all matching groups.
            Defaults to True.
        return_raw: If True, return the raw API response from get(). Defaults to False.
        context: Optional RouteContext for configuring the request.
        **context_kwargs: Additional keyword arguments passed to RouteContext.build_context().

    Returns:
        If return_raw is True, returns the raw API response from get(). If only_allow_one
        is True, returns a single DomoGroup. Otherwise, returns a list of DomoGroup instances.

    Raises:
        DomoGroupError: If no groups match the search criteria and only_allow_one is True.
    """
    context = RouteContext.build_context(context=context, **context_kwargs)

    domo_groups = await self.get(
        is_hide_system_groups=is_hide_system_groups,
        return_raw=return_raw,
        context=context,
    )

    if return_raw:
        return domo_groups

    filter_groups = None
    if isinstance(group_name, str):
        filter_groups = [
            dg for dg in domo_groups if dg.name.lower() == group_name.lower()
        ]

    if isinstance(group_name, list):
        filter_groups = [
            dg
            for dg in domo_groups
            if dg.name.lower() in [gname.lower() for gname in group_name]
        ]

    if not filter_groups:
        raise DomoGroupError(
            cls_instance=self,
            entity_id=self.auth.domo_instance,
            message=f"{len(domo_groups)} retrieved.  unable to find a group matching {group_name}",
        )

    if only_allow_one:
        return filter_groups[0]

    return filter_groups

toggle_show_system_groups async

toggle_show_system_groups(
    is_hide_system_groups: bool,
    return_raw: bool = False,
    *,
    context: RouteContext | None = None,
    **context_kwargs: Any
) -> ResponseGetData | bool

Toggle the visibility of system groups.

Sets whether system groups should be hidden or shown. If the setting matches the current state, returns without making an API call. The actual value returned is the inverse of the response value.

Parameters:

Name	Type	Description	Default
is_hide_system_groups	bool	If True, hide system groups; if False, show them.	required
return_raw	bool	If True, return the raw API response; otherwise return the new visibility state. Defaults to False.	False
context	RouteContext | None	Optional RouteContext for configuring the request.	None
**context_kwargs	Any	Additional keyword arguments passed to RouteContext.build_context().	{}

Returns:

Type	Description
ResponseGetData | bool	If return_raw is True, returns the raw API response. Otherwise, returns
ResponseGetData | bool	the updated is_hide_system_groups value (the inverse of res.response["value"]).

Source code in src/crew_dcs/classes/DomoGroup/core.py

async def toggle_show_system_groups(
    self,
    is_hide_system_groups: bool,
    return_raw: bool = False,
    *,
    context: RouteContext | None = None,
    **context_kwargs: Any,
) -> "rgd.ResponseGetData | bool":
    """Toggle the visibility of system groups.

    Sets whether system groups should be hidden or shown. If the setting matches
    the current state, returns without making an API call. The actual value returned
    is the inverse of the response value.

    Args:
        is_hide_system_groups: If True, hide system groups; if False, show them.
        return_raw: If True, return the raw API response; otherwise return the
            new visibility state. Defaults to False.
        context: Optional RouteContext for configuring the request.
        **context_kwargs: Additional keyword arguments passed to RouteContext.build_context().

    Returns:
        If return_raw is True, returns the raw API response. Otherwise, returns
        the updated is_hide_system_groups value (the inverse of res.response["value"]).
    """
    if self.is_hide_system_groups == is_hide_system_groups:
        return self.is_hide_system_groups

    context = RouteContext.build_context(context=context, **context_kwargs)

    res = await group_routes.toggle_system_group_visibility(
        auth=self.auth,
        is_hide_system_groups=is_hide_system_groups,
        context=context,
    )

    if return_raw:
        return res

    self.is_hide_system_groups = not res.response["value"]

    return self.is_hide_system_groups

upsert async

upsert(
    group_name: str,
    group_type: str | None = None,
    description: str | None = None,
    additional_params: dict | None = None,
    *,
    context: RouteContext | None = None,
    **context_kwargs: Any
) -> DomoGroup

Create a new group or update an existing one by name.

Searches for a group with the given name. If found, updates its metadata. If not found, creates a new group. If update_metadata fails, falls back to a plain update_group call with name/description/additional_params — that fallback does not retry the group_type change, so a type-change failure leaves the group's type unchanged.

Parameters:

Name	Type	Description	Default
group_name	str	The name of the group to create or update.	required
group_type	str | None	The type for a new group or to update to. Should use GroupType_Enum for type safety. Defaults to None. Not applied by the fallback path if update_metadata fails.	None
description	str | None	Description for the group. Defaults to None.	None
additional_params	dict | None	Additional parameters for the API call, used as a fallback if update_metadata fails. Defaults to None.	None
context	RouteContext | None	Optional RouteContext for configuring the request.	None
**context_kwargs	Any	Additional keyword arguments passed to RouteContext.build_context().	{}

Returns:

Type	Description
DomoGroup	The created or updated DomoGroup instance.

Source code in src/crew_dcs/classes/DomoGroup/core.py

async def upsert(
    self,
    group_name: str,
    group_type: str
    | None = None,  # if create_group, use routes.class.GroupType_Enum
    description: str | None = None,
    additional_params: dict | None = None,
    *,
    context: RouteContext | None = None,
    **context_kwargs: Any,
) -> "DomoGroup":
    """Create a new group or update an existing one by name.

    Searches for a group with the given name. If found, updates its metadata.
    If not found, creates a new group. If update_metadata fails, falls back to
    a plain update_group call with name/description/additional_params — that
    fallback does not retry the group_type change, so a type-change failure
    leaves the group's type unchanged.

    Args:
        group_name: The name of the group to create or update.
        group_type: The type for a new group or to update to. Should use
            GroupType_Enum for type safety. Defaults to None. Not applied by
            the fallback path if update_metadata fails.
        description: Description for the group. Defaults to None.
        additional_params: Additional parameters for the API call, used as a
            fallback if update_metadata fails. Defaults to None.
        context: Optional RouteContext for configuring the request.
        **context_kwargs: Additional keyword arguments passed to RouteContext.build_context().

    Returns:
        The created or updated DomoGroup instance.
    """
    context = RouteContext.build_context(context=context, **context_kwargs)

    domo_group = None
    try:
        domo_group = await self.search_by_name(
            group_name=group_name, only_allow_one=True, context=context
        )

        await logger.info(
            f"Updating group '{group_name}' (id: {domo_group.id}) because group already exists"
        )

    except DomoGroupError:
        await logger.info(
            f"Creating group '{group_name}' because no existing group found"
        )

        return await DomoGroup.create_from_name(
            auth=self.auth,
            group_name=group_name,
            group_type=group_type,
            description=description,
            context=context,
        )

    try:
        await domo_group.update_metadata(
            group_type=group_type,
            description=description,
            context=context,
        )

    except (Group_CRUD_Error, DomoGroupError):
        await group_routes.update_group(
            auth=self.auth,
            group_id=domo_group.id,
            group_name=group_name,
            # group_type=group_type,
            description=description,
            additional_params=additional_params,
            context=context,
        )

    return domo_group