collibra-connector 1.0.19__py3-none-any.whl → 1.1.1__py3-none-any.whl

collibra_connector/api/Attribute.py

@@ -0,0 +1,204 @@
+"""
+Attribute API module for Collibra Connector.
+
+Provides methods for working with asset attributes.
+"""
+from __future__ import annotations
+
+import uuid
+from typing import Any, Dict, List, Optional, TYPE_CHECKING
+
+from .Base import BaseAPI
+
+if TYPE_CHECKING:
+    pass
+
+
+class Attribute(BaseAPI):
+    """API class for attribute operations."""
+
+    def __init__(self, connector: Any) -> None:
+        """Initialize the Attribute API."""
+        super().__init__(connector)
+        self.__base_api = connector.api + "/attributes"
+
+    def get_attributes(
+        self,
+        asset_id: str,
+        type_ids: Optional[List[str]] = None,
+        limit: int = 100,
+        offset: int = 0
+    ) -> Dict[str, Any]:
+        """
+        Get all attributes for an asset.
+
+        Args:
+            asset_id: The UUID of the asset.
+            type_ids: Optional list of attribute type IDs to filter by.
+            limit: Maximum number of results.
+            offset: Offset for pagination.
+
+        Returns:
+            Dictionary with 'results' list of attributes.
+
+        Example:
+            >>> attrs = connector.attribute.get_attributes("asset-uuid")
+            >>> for attr in attrs['results']:
+            ...     print(f"{attr['type']['name']}: {attr['value']}")
+        """
+        if not asset_id:
+            raise ValueError("asset_id is required")
+        if not isinstance(asset_id, str):
+            raise ValueError("asset_id must be a string")
+
+        try:
+            uuid.UUID(asset_id)
+        except ValueError as exc:
+            raise ValueError("asset_id must be a valid UUID") from exc
+
+        params: Dict[str, Any] = {
+            "assetId": asset_id,
+            "limit": limit,
+            "offset": offset
+        }
+
+        if type_ids:
+            params["typeIds"] = type_ids
+
+        response = self._get(url=self.__base_api, params=params)
+        return self._handle_response(response)
+
+    def get_attribute(self, attribute_id: str) -> Dict[str, Any]:
+        """
+        Get a specific attribute by ID.
+
+        Args:
+            attribute_id: The UUID of the attribute.
+
+        Returns:
+            Attribute details.
+        """
+        if not attribute_id:
+            raise ValueError("attribute_id is required")
+
+        try:
+            uuid.UUID(attribute_id)
+        except ValueError as exc:
+            raise ValueError("attribute_id must be a valid UUID") from exc
+
+        response = self._get(url=f"{self.__base_api}/{attribute_id}")
+        return self._handle_response(response)
+
+    def add_attribute(
+        self,
+        asset_id: str,
+        type_id: str,
+        value: Any
+    ) -> Dict[str, Any]:
+        """
+        Add an attribute to an asset.
+
+        Args:
+            asset_id: The UUID of the asset.
+            type_id: The UUID of the attribute type.
+            value: The value of the attribute.
+
+        Returns:
+            Created attribute details.
+        """
+        if not asset_id or not type_id:
+            raise ValueError("asset_id and type_id are required")
+
+        for param_name, param_value in [("asset_id", asset_id), ("type_id", type_id)]:
+            try:
+                uuid.UUID(param_value)
+            except ValueError as exc:
+                raise ValueError(f"{param_name} must be a valid UUID") from exc
+
+        data = {
+            "assetId": asset_id,
+            "typeId": type_id,
+            "value": value
+        }
+
+        response = self._post(url=self.__base_api, data=data)
+        return self._handle_response(response)
+
+    def change_attribute(
+        self,
+        attribute_id: str,
+        value: Any
+    ) -> Dict[str, Any]:
+        """
+        Update an attribute value.
+
+        Args:
+            attribute_id: The UUID of the attribute.
+            value: The new value.
+
+        Returns:
+            Updated attribute details.
+        """
+        if not attribute_id:
+            raise ValueError("attribute_id is required")
+
+        try:
+            uuid.UUID(attribute_id)
+        except ValueError as exc:
+            raise ValueError("attribute_id must be a valid UUID") from exc
+
+        data = {
+            "id": attribute_id,
+            "value": value
+        }
+
+        response = self._patch(url=f"{self.__base_api}/{attribute_id}", data=data)
+        return self._handle_response(response)
+
+    def remove_attribute(self, attribute_id: str) -> Dict[str, Any]:
+        """
+        Remove an attribute.
+
+        Args:
+            attribute_id: The UUID of the attribute to remove.
+
+        Returns:
+            Response from the removal operation.
+        """
+        if not attribute_id:
+            raise ValueError("attribute_id is required")
+
+        try:
+            uuid.UUID(attribute_id)
+        except ValueError as exc:
+            raise ValueError("attribute_id must be a valid UUID") from exc
+
+        response = self._delete(url=f"{self.__base_api}/{attribute_id}")
+        return self._handle_response(response)
+
+    def get_attributes_as_dict(self, asset_id: str) -> Dict[str, Any]:
+        """
+        Get all attributes for an asset as a simple dictionary.
+
+        Convenience method that returns attribute values keyed by attribute type name.
+
+        Args:
+            asset_id: The UUID of the asset.
+
+        Returns:
+            Dictionary mapping attribute type names to values.
+
+        Example:
+            >>> attrs = connector.attribute.get_attributes_as_dict("asset-uuid")
+            >>> print(attrs['Description'])
+            >>> print(attrs['Personal Data Classification'])
+        """
+        result = self.get_attributes(asset_id, limit=500)
+        attrs_dict: Dict[str, Any] = {}
+
+        for attr in result.get('results', []):
+            type_name = attr.get('type', {}).get('name', 'Unknown')
+            value = attr.get('value')
+            attrs_dict[type_name] = value
+
+        return attrs_dict

collibra_connector/api/Base.py

@@ -123,9 +123,9 @@ class BaseAPI:
         :param response: The response object from the API request.
         :return: The JSON content of the response if successful, otherwise raises an error.
         """
-        if response.status_code in [200, 201]:
+        if response.status_code in [200, 201, 204]:
             # Check if response has content before trying to parse JSON
-            if response.text.strip():
+            if response.status_code != 204 and response.text.strip():
                 try:
                     return response.json()
                 except ValueError as e:

collibra_connector/api/Relation.py

@@ -204,3 +204,219 @@ class Relation(BaseAPI):
 
         response = self._patch(url=f"{self.__base_api}/{relation_id}", data=data)
         return self._handle_response(response)
+
+    def find_relations(
+        self,
+        source_id: str = None,
+        target_id: str = None,
+        type_id: str = None,
+        source_type_id: str = None,
+        target_type_id: str = None,
+        limit: int = 100,
+        offset: int = 0
+    ):
+        """
+        Find relations matching the given criteria.
+
+        Args:
+            source_id: Filter by source asset ID.
+            target_id: Filter by target asset ID.
+            type_id: Filter by relation type ID.
+            source_type_id: Filter by source asset type ID.
+            target_type_id: Filter by target asset type ID.
+            limit: Maximum results to retrieve (max 1000).
+            offset: First result to retrieve.
+
+        Returns:
+            List of relations matching criteria.
+
+        Example:
+            >>> # Get all outgoing relations from an asset
+            >>> relations = connector.relation.find_relations(source_id="asset-uuid")
+            >>> # Get all incoming relations to an asset
+            >>> relations = connector.relation.find_relations(target_id="asset-uuid")
+        """
+        params = {
+            "limit": limit,
+            "offset": offset
+        }
+
+        # Validate and add source_id
+        if source_id is not None:
+            if not isinstance(source_id, str):
+                raise ValueError("source_id must be a string")
+            try:
+                uuid.UUID(source_id)
+            except ValueError as exc:
+                raise ValueError("source_id must be a valid UUID") from exc
+            params["sourceId"] = source_id
+
+        # Validate and add target_id
+        if target_id is not None:
+            if not isinstance(target_id, str):
+                raise ValueError("target_id must be a string")
+            try:
+                uuid.UUID(target_id)
+            except ValueError as exc:
+                raise ValueError("target_id must be a valid UUID") from exc
+            params["targetId"] = target_id
+
+        # Validate and add type_id
+        if type_id is not None:
+            if not isinstance(type_id, str):
+                raise ValueError("type_id must be a string")
+            try:
+                uuid.UUID(type_id)
+            except ValueError as exc:
+                raise ValueError("type_id must be a valid UUID") from exc
+            params["typeId"] = type_id
+
+        # Add optional type filters
+        if source_type_id is not None:
+            params["sourceTypeId"] = source_type_id
+        if target_type_id is not None:
+            params["targetTypeId"] = target_type_id
+
+        response = self._get(url=self.__base_api, params=params)
+        return self._handle_response(response)
+
+    def get_relation_type(self, relation_type_id: str):
+        """
+        Get relation type details by ID.
+
+        Args:
+            relation_type_id: The UUID of the relation type.
+
+        Returns:
+            Relation type details including role and coRole names.
+        """
+        if not relation_type_id:
+            raise ValueError("relation_type_id is required")
+
+        try:
+            uuid.UUID(relation_type_id)
+        except ValueError as exc:
+            raise ValueError("relation_type_id must be a valid UUID") from exc
+
+        url = self._BaseAPI__connector.api + f"/relationTypes/{relation_type_id}"
+        response = self._get(url=url)
+        return self._handle_response(response)
+
+    def get_asset_relations(
+        self,
+        asset_id: str,
+        direction: str = "BOTH",
+        limit: int = 500,
+        include_type_details: bool = True
+    ):
+        """
+        Get all relations for an asset, grouped by direction and type.
+
+        Convenience method that returns a structured view of all relations.
+
+        Args:
+            asset_id: The UUID of the asset.
+            direction: "OUTGOING", "INCOMING", or "BOTH".
+            limit: Maximum relations per direction.
+            include_type_details: If True, fetches relation type names (slower but more informative).
+
+        Returns:
+            Dictionary with 'outgoing' and 'incoming' keys, each containing
+            relations grouped by relation type name.
+
+        Example:
+            >>> relations = connector.relation.get_asset_relations("asset-uuid")
+            >>> print(relations['outgoing'])  # Relations where asset is source
+            >>> print(relations['incoming'])  # Relations where asset is target
+        """
+        if not asset_id:
+            raise ValueError("asset_id is required")
+
+        try:
+            uuid.UUID(asset_id)
+        except ValueError as exc:
+            raise ValueError("asset_id must be a valid UUID") from exc
+
+        result = {
+            "outgoing": {},
+            "incoming": {},
+            "outgoing_count": 0,
+            "incoming_count": 0
+        }
+
+        # Cache for relation type details
+        type_cache = {}
+
+        def get_type_name(type_id, is_source=True):
+            """Get relation type name, using cache."""
+            if not include_type_details or not type_id:
+                return "Unknown"
+
+            if type_id not in type_cache:
+                try:
+                    type_details = self.get_relation_type(type_id)
+                    type_cache[type_id] = type_details
+                except Exception:
+                    type_cache[type_id] = {}
+
+            cached = type_cache.get(type_id, {})
+            if is_source:
+                return cached.get("role", "Unknown")
+            else:
+                return cached.get("coRole", "Unknown")
+
+        # Get outgoing relations
+        if direction in ("BOTH", "OUTGOING"):
+            outgoing = self.find_relations(source_id=asset_id, limit=limit)
+            result["outgoing_count"] = outgoing.get("total", 0)
+
+            for rel in outgoing.get("results", []):
+                rel_type = rel.get("type", {})
+                type_id = rel_type.get("id")
+                type_name = get_type_name(type_id, is_source=True)
+                target = rel.get("target", {})
+
+                # Get target asset type by looking up the relation type
+                target_type_name = None
+                if type_id in type_cache:
+                    target_type_name = type_cache[type_id].get("targetType", {}).get("name")
+
+                if type_name not in result["outgoing"]:
+                    result["outgoing"][type_name] = []
+
+                result["outgoing"][type_name].append({
+                    "id": rel.get("id"),
+                    "target_id": target.get("id"),
+                    "target_name": target.get("name"),
+                    "target_type": target_type_name or target.get("type", {}).get("name"),
+                    "target_status": target.get("status", {}).get("name") if target.get("status") else "N/A"
+                })
+
+        # Get incoming relations
+        if direction in ("BOTH", "INCOMING"):
+            incoming = self.find_relations(target_id=asset_id, limit=limit)
+            result["incoming_count"] = incoming.get("total", 0)
+
+            for rel in incoming.get("results", []):
+                rel_type = rel.get("type", {})
+                type_id = rel_type.get("id")
+                type_name = get_type_name(type_id, is_source=False)
+                source = rel.get("source", {})
+
+                # Get source asset type by looking up the relation type
+                source_type_name = None
+                if type_id in type_cache:
+                    source_type_name = type_cache[type_id].get("sourceType", {}).get("name")
+
+                if type_name not in result["incoming"]:
+                    result["incoming"][type_name] = []
+
+                result["incoming"][type_name].append({
+                    "id": rel.get("id"),
+                    "source_id": source.get("id"),
+                    "source_name": source.get("name"),
+                    "source_type": source_type_name or source.get("type", {}).get("name"),
+                    "source_status": source.get("status", {}).get("name") if source.get("status") else "N/A"
+                })
+
+        return result

collibra_connector/api/Responsibility.py

@@ -182,13 +182,13 @@ class Responsibility(BaseAPI):
             raise ValueError(f"type must be one of: {', '.join(valid_types)}")
 
         # Validate that globalOnly and type are mutually exclusive
-        if global_only is not None and type is not None:
+        if global_only is not None and _type is not None:
             raise ValueError("globalOnly and type parameters are mutually exclusive")
 
         # Validate owner_ids if provided
         if owner_ids is not None:
             if not isinstance(owner_ids, list):
-                raise ValueError("owner_ids must be a list")
+                raise ValueError("owner_id must be a list")
             for owner_id in owner_ids:
                 if not isinstance(owner_id, str):
                     raise ValueError("owner_id must be a string")
@@ -246,10 +246,10 @@ class Responsibility(BaseAPI):
             params["sortField"] = sort_field
         if sort_order != "DESC":
             params["sortOrder"] = sort_order
-        if type is not None:
-            params["type"] = type
+        if _type is not None:
+            params["type"] = _type
 
-        response = self._get(params=params)
+        response = self._get(url=self.__base_api, params=params)
         return self._handle_response(response)
 
     def get_asset_responsibilities(self, asset_id: str, role_ids: list = None):

collibra_connector/api/Search.py

@@ -0,0 +1,102 @@
+from typing import Any, Dict, List, Optional
+from .Base import BaseAPI
+
+
+class Search(BaseAPI):
+    """
+    Search API implementation.
+    Wraps the /search endpoint of Collibra DGC.
+    """
+
+    def __init__(self, connector):
+        super().__init__(connector)
+        self.__base_api = connector.api + "/search"
+
+    def find(
+        self,
+        query: str,
+        limit: int = 10,
+        offset: int = 0,
+        filter_options: Optional[Dict[str, Any]] = None,
+        sort_options: Optional[Dict[str, Any]] = None,
+        highlight_options: Optional[Dict[str, Any]] = None,
+        search_fields: Optional[List[str]] = None,
+    ) -> Dict[str, Any]:
+        """
+        Perform a search query.
+
+        Args:
+            query: The search query string (can use wildcards like *).
+            limit: Max number of results.
+            offset: Offset for pagination.
+            filter_options: Dictionary of filters (e.g., {'category': 'ASSET', 'typeIds': [...]}).
+            sort_options: Dictionary of sort options (e.g., {'field': 'name', 'order': 'ASC'}).
+            highlight_options: Dictionary of highlight options.
+            search_fields: List of fields to search in.
+
+        Returns:
+            Search results dictionary with 'results', 'total', etc.
+        """
+        data = {
+            "keywords": query,
+            "limit": limit,
+            "offset": offset,
+        }
+
+        if filter_options:
+            data.update(filter_options)
+        
+        if sort_options:
+            data["sort"] = [sort_options]  # API expects a list of sorts
+        
+        if highlight_options:
+            data["highlights"] = [highlight_options]
+            
+        if search_fields:
+            data["searchFields"] = search_fields
+
+        # Default to ASSET category if not specified, usually what users want
+        # But maybe better to leave it open. The API defaults to all.
+        
+        response = self._post(url=self.__base_api, data=data)
+        return self._handle_response(response)
+
+    def find_assets(
+        self,
+        query: str,
+        limit: int = 10,
+        offset: int = 0,
+        type_ids: Optional[List[str]] = None,
+        domain_ids: Optional[List[str]] = None,
+        community_ids: Optional[List[str]] = None,
+        status_ids: Optional[List[str]] = None,
+    ) -> Dict[str, Any]:
+        """
+        Helper specifically for searching assets.
+        
+        Args:
+            query: Search text.
+            limit: Max results.
+            offset: Pagination offset.
+            type_ids: Filter by asset type IDs.
+            domain_ids: Filter by domain IDs.
+            community_ids: Filter by community IDs.
+            status_ids: Filter by status IDs.
+            
+        Returns:
+            Search results.
+        """
+        filters = {
+            "category": "ASSET"
+        }
+        
+        if type_ids:
+            filters["typeIds"] = type_ids
+        if domain_ids:
+            filters["domainIds"] = domain_ids
+        if community_ids:
+            filters["communityIds"] = community_ids
+        if status_ids:
+            filters["statusIds"] = status_ids
+            
+        return self.find(query=query, limit=limit, offset=offset, filter_options=filters)

collibra_connector/api/Workflow.py

@@ -10,15 +10,26 @@ class Workflow(BaseAPI):
     def start_workflow_instance(
         self,
         workflow_definition_id: str,
-        asset_id: str = None,
+        business_item_ids: list[str] = None,
+        business_item_type: str = None,
+        form_properties: dict[str, str] = None,
+        guest_user_id: str = None,
+        send_notification: bool = False,
         return_all: bool = False
     ):
         """
-        Start a workflow instance.
-        :param workflow_definition_id: The ID of the workflow definition.
-        :param asset_id: Optional asset ID to associate with the workflow.
+        Start multiple workflow instances based on the provided request.
+
+        :param workflow_definition_id: The ID of the workflow definition (required).
+        :param business_item_ids: The list of IDs for the business items (optional).
+        :param business_item_type: The resource type of the passed in business items.
+                                   Allowed values: ASSET, DOMAIN, COMMUNITY, GLOBAL, USER (optional).
+        :param form_properties: The properties of the workflow as a dictionary (optional).
+        :param guest_user_id: The ID of the guest user starting the workflow (optional).
+        :param send_notification: Whether a mail notification on starting the workflows should be sent.
+                                 This notification is only used in the asynchronous api version (optional).
         :param return_all: Whether to return all workflow data or just the ID.
-        :return: Workflow instance ID or full response data.
+        :return: Workflow instance ID or full response data (array of workflow instances).
         """
         if not workflow_definition_id:
             raise ValueError("workflow_definition_id is required")
@@ -32,21 +43,44 @@ class Workflow(BaseAPI):
 
         data = {
             "workflowDefinitionId": workflow_definition_id,
-            "sendNotification": True
+            "sendNotification": send_notification
         }
 
-        if asset_id:
-            if not isinstance(asset_id, str):
-                raise ValueError("asset_id must be a string")
+        if business_item_ids is not None:
+            if not isinstance(business_item_ids, list):
+                raise ValueError("business_item_ids must be a list")
+            if not all(isinstance(item_id, str) for item_id in business_item_ids):
+                raise ValueError("All business_item_ids must be strings")
+            for item_id in business_item_ids:
+                try:
+                    uuid.UUID(item_id)
+                except ValueError as exc:
+                    raise ValueError(f"business_item_id '{item_id}' must be a valid UUID") from exc
+            data["businessItemIds"] = business_item_ids
+
+        if business_item_type is not None:
+            if not isinstance(business_item_type, str):
+                raise ValueError("business_item_type must be a string")
+            valid_types = ["ASSET", "DOMAIN", "COMMUNITY", "GLOBAL", "USER"]
+            if business_item_type not in valid_types:
+                raise ValueError(f"business_item_type must be one of: {', '.join(valid_types)}")
+            data["businessItemType"] = business_item_type
+
+        if form_properties is not None:
+            if not isinstance(form_properties, dict):
+                raise ValueError("form_properties must be a dictionary")
+            if not all(isinstance(k, str) and isinstance(v, str) for k, v in form_properties.items()):
+                raise ValueError("All form_properties keys and values must be strings")
+            data["formProperties"] = form_properties
+
+        if guest_user_id is not None:
+            if not isinstance(guest_user_id, str):
+                raise ValueError("guest_user_id must be a string")
             try:
-                uuid.UUID(asset_id)
+                uuid.UUID(guest_user_id)
             except ValueError as exc:
-                raise ValueError("asset_id must be a valid UUID") from exc
-
-            data.update({
-                "businessItemIds": [asset_id],
-                "businessItemType": "ASSET",
-            })
+                raise ValueError("guest_user_id must be a valid UUID") from exc
+            data["guestUserId"] = guest_user_id
 
         response = self._post(url=f"{self.__base_api}/workflowInstances", data=data)
         result = self._handle_response(response)