Organization

An Organization resource is used to represent a whole or a part of an enterprise or company, and serves as the foundation of your resource hierarchy. It is important to note that although multiple Organization resources can exist, they cannot reference each other's resources.

Apart from serving as the root of the resource hierarchy, the Organization resource also contains crucial information for compliance reporting, such as in the case of a data map or a Record of Processing Activities (RoPA).

The organization is defined in the catalogue/\<organization name\>/organization.yml. The organization.yml file accepts all arguments defined in the Organization model with the expection of:

1. The key is created using the catalogue folder structure.
2. The systems dictionary is created using the catalogue folder strucutre.

Example

# organization.yaml

organization:
  key: organization_key
  tags:
  - foo
  - bar
  name: organization_foo
  description: organization description
  controller:
    name: Bob
    address: Museumplein 10, 1071 DJ Amsterdam, Netherlands
    email: bob@organization.com
    phone: 020 573 2911
  data_protection_officer:
    name: Alice
    address: Museumplein 10, 1071 DJ Amsterdam, Netherlands
    email: alice@organization.com
    phone: 020 573 2911
  representative:
    name: Carol [optional]
    address: Museumplein 10, 1071 DJ Amsterdam, Netherlands
    email: carol@organization.com
    phone: 020 573 2911

Models

blackline.models.catalogue.Organization

Bases: BlacklineModel

The Organization resource model.

This resource is used as a way to organize all other resources.

Parameters:

Name	Type	Description	Default
controller	Optional[ContactDetails]		None
data_protection_officer	Optional[ContactDetails]		None
representative	Optional[ContactDetails]		None
security_policy	Optional[HttpUrl]	Am optional URL to the organization security policy.	None
children	Optional[dict[str, System]]	System dict	None
stem			required
children_stem			required
children_cls			required

Source code in BAR /opt/hostedtoolcache/Python/3.10.12/x64/lib/python3.10/site-packages/blackline/models/catalogue.py

class Organization(BlacklineModel):
    """
    The Organization resource model.

    This resource is used as a way to organize all other resources.
    """

    controller: Optional[ContactDetails] = Field(
        description=ContactDetails.__doc__,
    )
    data_protection_officer: Optional[ContactDetails] = Field(
        description=ContactDetails.__doc__,
    )
    representative: Optional[ContactDetails] = Field(
        description=ContactDetails.__doc__,
    )
    security_policy: Optional[HttpUrl] = Field(
        description="Am optional URL to the organization security policy."
    )
    children: Optional[dict[str, System]] = Field(description="System dict", alias="systems")  # type: ignore[assignment]

    stem = "organization"
    children_stem = "systems"
    children_cls = System

blackline.models.catalogue.BlacklineModel

Bases: BaseModel

The base model for all Resources.

Parameters:

Name	Type	Description	Default
key	Key	A unique key used to identify this resource.	required
tags	Optional[list[str]]	A list of tags for this resource.	None
name	Optional[str]		None
description	Optional[str]		None
children	Optional[dict[str, Type[BlacklineModel]]]	The children resources.	None
stem	str	The stem of the resource.	required
children_stem	Optional[str]		required
children_cls	Optional[type[BlacklineModel]]		required

Source code in BAR /opt/hostedtoolcache/Python/3.10.12/x64/lib/python3.10/site-packages/blackline/models/catalogue.py

class BlacklineModel(BaseModel):
    """The base model for all Resources."""

    key: Key = Field(description="A unique key used to identify this resource.")
    tags: Optional[list[str]] = Field(description="A list of tags for this resource.")
    name: Optional[str] = name_field
    description: Optional[str] = description_field
    children: Optional[dict[str, Type[BlacklineModel]]] = Field(
        None, description="The children resources."
    )
    stem: ClassVar[str] = Field(description="The stem of the resource.")
    children_stem: ClassVar[Optional[str]] = None
    children_cls: ClassVar[Optional[type[BlacklineModel]]] = None

    class Config:
        "Config for the BlacklineModel"
        extra = "forbid"
        orm_mode = True

    def __getitem__(self, key: str) -> Type[BlacklineModel]:
        parts = key.split(".")
        key = ".".join([self.key, parts[0]])
        if self.children is None:
            raise KeyError(f"No children for {self.key}")
        model = self.children[key]

        for part in parts[1:]:
            model = model[part]  # type: ignore[index]
        return model

    @classmethod
    def parse_dir(cls, path: Path, key_prefix: Optional[str] = None):
        """
        Parse a directory of YAML files into a dictionary of Dataset objects.

        Args:
            path: The path to the directory of YAML files.
            path: Path

        Returns:
            A dictionary of Dataset objects.
        """
        key = ".".join([key_prefix, path.name]) if key_prefix is not None else path.name
        children = cls.parse_children(path=path, key_prefix=key)
        filepath = cls.find_definition_file(path=path)
        return cls.parse_yaml(path=filepath, key=key, children=children)

    @classmethod
    def parse_children(
        cls, path: Path, key_prefix: Optional[str] = None
    ) -> dict[str, Type[BlacklineModel]]:
        """
        Parse a directory of YAML files into a dictionary of Dataset objects.

        Args:
            path: The path to the directory of YAML files.
            path: Path

        Returns:
            A dictionary of Dataset objects.
        """
        children: dict[str, Type[BlacklineModel]] = {}
        if cls.children_cls is None:
            return children
        for child_path in path.iterdir():
            if child_path.is_dir():
                child = cls.children_cls.parse_dir(
                    path=child_path, key_prefix=key_prefix
                )
                children[child.key] = child
        return children

    @classmethod
    def find_definition_file(cls, path: Path) -> Path:
        file = list(path.glob(f"{cls.stem}.yml")) + list(path.glob(f"{cls.stem}.yaml"))
        file_len = len(list(file))
        if file_len == 0:
            raise FileNotFoundError(
                f"No {cls.stem} file found in directory: {path.absolute()}"
            )
        if file_len > 1:
            raise ValueError(
                f"Multiple {cls.stem} files found in directory: {path.absolute()}, only include one of resource.yaml or resource.yml"
            )
        return file[0]

    @classmethod
    def parse_yaml(
        cls,
        path: Path,
        key: str,
        children: Optional[dict[str, Type[BlacklineModel]]] = {},
    ):
        """
        Parse a yaml file into a the children_cls object.

        Args:
            path: Path location of the yaml file.
            key: Key to identify the dataset.

        Returns:
            Dataset object.
        """
        with open(path, "r") as f:
            info = yaml.safe_load(f)[cls.stem][0]
            info["key"] = key
            if cls.stem == "dataset":
                return cls.parse_obj(info)
            info[cls.children_stem] = children
            return cls.parse_obj(info)

Config

Config for the BlacklineModel

Source code in BAR /opt/hostedtoolcache/Python/3.10.12/x64/lib/python3.10/site-packages/blackline/models/catalogue.py

class Config:
    "Config for the BlacklineModel"
    extra = "forbid"
    orm_mode = True

parse_children(path, key_prefix=None) classmethod

Parse a directory of YAML files into a dictionary of Dataset objects.

Parameters:

Name	Type	Description	Default
path	Path	The path to the directory of YAML files.	required
path	Path	Path	required

Returns:

Type	Description
dict[str, Type[BlacklineModel]]	A dictionary of Dataset objects.

Source code in /opt/hostedtoolcache/Python/3.10.12/x64/lib/python3.10/site-packages/blackline/models/catalogue.py

@classmethod
def parse_children(
    cls, path: Path, key_prefix: Optional[str] = None
) -> dict[str, Type[BlacklineModel]]:
    """
    Parse a directory of YAML files into a dictionary of Dataset objects.

    Args:
        path: The path to the directory of YAML files.
        path: Path

    Returns:
        A dictionary of Dataset objects.
    """
    children: dict[str, Type[BlacklineModel]] = {}
    if cls.children_cls is None:
        return children
    for child_path in path.iterdir():
        if child_path.is_dir():
            child = cls.children_cls.parse_dir(
                path=child_path, key_prefix=key_prefix
            )
            children[child.key] = child
    return children

parse_dir(path, key_prefix=None) classmethod

Parse a directory of YAML files into a dictionary of Dataset objects.

Parameters:

Name	Type	Description	Default
path	Path	The path to the directory of YAML files.	required
path	Path	Path	required

Returns:

Type	Description
	A dictionary of Dataset objects.

Source code in /opt/hostedtoolcache/Python/3.10.12/x64/lib/python3.10/site-packages/blackline/models/catalogue.py

@classmethod
def parse_dir(cls, path: Path, key_prefix: Optional[str] = None):
    """
    Parse a directory of YAML files into a dictionary of Dataset objects.

    Args:
        path: The path to the directory of YAML files.
        path: Path

    Returns:
        A dictionary of Dataset objects.
    """
    key = ".".join([key_prefix, path.name]) if key_prefix is not None else path.name
    children = cls.parse_children(path=path, key_prefix=key)
    filepath = cls.find_definition_file(path=path)
    return cls.parse_yaml(path=filepath, key=key, children=children)

parse_yaml(path, key, children={}) classmethod

Parse a yaml file into a the children_cls object.

Parameters:

Name	Type	Description	Default
path	Path	Path location of the yaml file.	required
key	str	Key to identify the dataset.	required

Returns:

Type	Description
	Dataset object.

Source code in /opt/hostedtoolcache/Python/3.10.12/x64/lib/python3.10/site-packages/blackline/models/catalogue.py

@classmethod
def parse_yaml(
    cls,
    path: Path,
    key: str,
    children: Optional[dict[str, Type[BlacklineModel]]] = {},
):
    """
    Parse a yaml file into a the children_cls object.

    Args:
        path: Path location of the yaml file.
        key: Key to identify the dataset.

    Returns:
        Dataset object.
    """
    with open(path, "r") as f:
        info = yaml.safe_load(f)[cls.stem][0]
        info["key"] = key
        if cls.stem == "dataset":
            return cls.parse_obj(info)
        info[cls.children_stem] = children
        return cls.parse_obj(info)

blackline.models.catalogue.ContactDetails

Bases: BaseModel

The contact details information model.

Used to capture contact information for controllers, used as part of exporting a data map / ROPA.

This model is nested under an Organization and potentially under a system/dataset.

Parameters:

Name	Type	Description	Default
name	Optional[str]	An individual name used as part of publishing contact information.	None
address	Optional[str]	An individual address used as part of publishing contact information.	None
email	Optional[str]	An individual email used as part of publishing contact information.	None
phone	Optional[str]	An individual phone number used as part of publishing contact information.	None

Source code in BAR /opt/hostedtoolcache/Python/3.10.12/x64/lib/python3.10/site-packages/blackline/models/catalogue.py

class ContactDetails(BaseModel):
    """
    The contact details information model.

    Used to capture contact information for controllers, used
    as part of exporting a data map / ROPA.

    This model is nested under an Organization and
    potentially under a system/dataset.
    """

    name: Optional[str] = Field(
        description="An individual name used as part of publishing contact information.",
    )
    address: Optional[str] = Field(
        description="An individual address used as part of publishing contact information.",
    )
    email: Optional[str] = Field(
        description="An individual email used as part of publishing contact information.",
    )
    phone: Optional[str] = Field(
        description="An individual phone number used as part of publishing contact information.",
    )