Annotation

Annotation(comment_value, object_name, dimensional_context, comment_type='ANNOTATION', annotation_id=None, text='', creator=None, created=None, last_updated_by=None, last_updated=None)

Bases: TM1Object

Abtraction of TM1 Annotation

:Notes: - Class complete, functional and tested. - doesn't cover Attachments though

Initialize an Annotation object.

Parameters:

Name	Type	Description	Default
comment_value	str	The value of the annotation comment.	required
object_name	str	Name of the TM1 object the annotation is attached to.	required
dimensional_context	Iterable[str]	Iterable of dimension elements providing context.	required
comment_type	str	Type of the comment (default "ANNOTATION").	'ANNOTATION'
annotation_id	str	Unique ID of the annotation.	None
text	str	Text of the annotation.	''
creator	str	Creator of the annotation.	None
created	str	Creation timestamp.	None
last_updated_by	str	Last user who updated the annotation.	None
last_updated	str	Last update timestamp.	None

Source code in TM1py/Objects/Annotation.py

def __init__(
    self,
    comment_value: str,
    object_name: str,
    dimensional_context: Iterable[str],
    comment_type: str = "ANNOTATION",
    annotation_id: str = None,
    text: str = "",
    creator: str = None,
    created: str = None,
    last_updated_by: str = None,
    last_updated: str = None,
):
    """
    Initialize an Annotation object.

    :param comment_value: The value of the annotation comment.
    :param object_name: Name of the TM1 object the annotation is attached to.
    :param dimensional_context: Iterable of dimension elements providing context.
    :param comment_type: Type of the comment (default "ANNOTATION").
    :param annotation_id: Unique ID of the annotation.
    :param text: Text of the annotation.
    :param creator: Creator of the annotation.
    :param created: Creation timestamp.
    :param last_updated_by: Last user who updated the annotation.
    :param last_updated: Last update timestamp.
    """
    self._id = annotation_id
    self._text = text
    self._creator = creator
    self._created = created
    self._last_updated_by = last_updated_by
    self._last_updated = last_updated
    self._dimensional_context = list(dimensional_context)
    self._comment_type = comment_type
    self._comment_value = comment_value
    self._object_name = object_name

body property

Get the annotation body as a JSON string.

Returns:

Type	Description
str	JSON string representation of the annotation.

body_as_dict property

Get the annotation body as a dictionary.

Returns:

Type	Description
Dict	Dictionary representation of the annotation.

comment_value property writable

Get the comment value.

Returns:

Type	Description
str	The comment value string.

created property

Get the creation timestamp.

Returns:

Type	Description
str	Creation timestamp as string.

dimensional_context property

Get the dimensional context.

Returns:

Type	Description
List[str]	List of dimension elements providing context.

id property

Get the annotation ID.

Returns:

Type	Description
str	Annotation ID string.

last_updated property

Get the last updated timestamp.

Returns:

Type	Description
str	Last update timestamp as string.

last_updated_by property

Get the last user who updated the annotation.

Returns:

Type	Description
str	Username of last updater.

object_name property

Get the object name.

Returns:

Type	Description
str	Name of the TM1 object.

text property

Get the annotation text.

Returns:

Type	Description
str	The annotation text.

construct_body_for_post(cube_dimensions)

Construct the body for POST requests to create an annotation.

Parameters:

Name	Type	Description	Default
cube_dimensions		List of cube dimension names.	required

Returns:

Type	Description
Dict	Dictionary for POST request body.

Source code in TM1py/Objects/Annotation.py

def construct_body_for_post(self, cube_dimensions) -> Dict:
    """
    Construct the body for POST requests to create an annotation.

    :param cube_dimensions: List of cube dimension names.
    :return: Dictionary for POST request body.
    """
    body = collections.OrderedDict()
    body["Text"] = self.text
    body["ApplicationContext"] = [
        {"Facet@odata.bind": "ApplicationContextFacets('}Cubes')", "Value": self.object_name}
    ]
    body["DimensionalContext@odata.bind"] = []

    for dimension, element in zip(cube_dimensions, self.dimensional_context):
        coordinates = format_url("Dimensions('{}')/Hierarchies('{}')/Members('{}')", dimension, dimension, element)
        body["DimensionalContext@odata.bind"].append(coordinates)

    body["objectName"] = self.object_name
    body["commentValue"] = self.comment_value
    body["commentType"] = "ANNOTATION"
    body["commentLocation"] = ",".join(self.dimensional_context)

    return body

from_json(annotation_as_json) classmethod

Alternative constructor

Parameters:

Name	Type	Description	Default
annotation_as_json	str	String, JSON	required

Returns:

Type	Description
Annotation	instance of Annotation

Source code in TM1py/Objects/Annotation.py

@classmethod
def from_json(cls, annotation_as_json: str) -> "Annotation":
    """Alternative constructor

    :param annotation_as_json: String, JSON
    :return: instance of Annotation
    """
    annotation_as_dict = json.loads(annotation_as_json)
    annotation_id = annotation_as_dict["ID"]
    text = annotation_as_dict["Text"]
    creator = annotation_as_dict["Creator"]
    created = annotation_as_dict["Created"]
    last_updated_by = annotation_as_dict["LastUpdatedBy"]
    last_updated = annotation_as_dict["LastUpdated"]
    dimensional_context = [item["Name"] for item in annotation_as_dict["DimensionalContext"]]
    comment_type = annotation_as_dict["commentType"]
    comment_value = annotation_as_dict["commentValue"]
    object_name = annotation_as_dict["objectName"]
    return cls(
        comment_value=comment_value,
        object_name=object_name,
        dimensional_context=dimensional_context,
        comment_type=comment_type,
        annotation_id=annotation_id,
        text=text,
        creator=creator,
        created=created,
        last_updated_by=last_updated_by,
        last_updated=last_updated,
    )

move(dimension_order, dimension, target_element, source_element=None)

Move annotation on given dimension from source_element to target_element.

Parameters:

Name	Type	Description	Default
dimension_order	Iterable[str]	List, order of the dimensions in the cube.	required
dimension	str	Dimension name.	required
target_element	str	Target element name.	required
source_element	str	Source element name (optional).	None

Returns:

Type	Description
	None

Source code in TM1py/Objects/Annotation.py

def move(self, dimension_order: Iterable[str], dimension: str, target_element: str, source_element: str = None):
    """
    Move annotation on given dimension from source_element to target_element.

    :param dimension_order: List, order of the dimensions in the cube.
    :param dimension: Dimension name.
    :param target_element: Target element name.
    :param source_element: Source element name (optional).
    :return: None
    """
    for i, dimension_name in enumerate(dimension_order):
        if dimension_name.lower() == dimension.lower():
            if not source_element or self._dimensional_context[i] == source_element:
                self._dimensional_context[i] = target_element