ApplicationService

ApplicationService(tm1_rest)

Bases: ObjectService

Service to Read and Write TM1 Applications

Parameters:

Name	Type	Description	Default
tm1_rest	RestService		required

Source code in TM1py/Services/ApplicationService.py

def __init__(self, tm1_rest: RestService):
    """

    :param tm1_rest:
    """
    super().__init__(tm1_rest)
    self._rest = tm1_rest

create(application, private=False, **kwargs)

Create Planning Analytics application

Parameters:

Name	Type	Description	Default
application	Union[Application, DocumentApplication]	instance of Application	required
private	bool	boolean	False

Returns:

Type	Description
Response

Source code in TM1py/Services/ApplicationService.py

def create(self, application: Union[Application, DocumentApplication], private: bool = False, **kwargs) -> Response:
    """Create Planning Analytics application

    :param application: instance of Application
    :param private: boolean
    :return:
    """

    contents = "PrivateContents" if private else "Contents"

    mid = ""
    if application.path.strip() != "":
        mid = "".join([format_url("/Contents('{}')", element) for element in application.path.split("/")])
    url = "/Contents('Applications')" + mid + "/" + contents
    response = self._rest.POST(url, application.body, **kwargs)

    if application.application_type == ApplicationTypes.DOCUMENT:
        url = format_url(
            "/Contents('Applications')" + mid + "/" + contents + "('{name}{suffix}')/Document/Content",
            name=application.name,
            suffix=".blob" if not verify_version(required_version="12", version=self.version) else "",
        )
        response = self._rest.PUT(url, application.content, headers=self.binary_http_header, **kwargs)

    return response

create_document_from_file(path_to_file, application_path, application_name, private=False, **kwargs)

Create DocumentApplication in TM1 from local file

Parameters:

Name	Type	Description	Default
path_to_file	str		required
application_path	str		required
application_name	str		required
private	bool		False

Returns:

Type	Description
Response

Source code in TM1py/Services/ApplicationService.py

def create_document_from_file(
    self, path_to_file: str, application_path: str, application_name: str, private: bool = False, **kwargs
) -> Response:
    """Create DocumentApplication in TM1 from local file

    :param path_to_file:
    :param application_path:
    :param application_name:
    :param private:
    :return:
    """
    with open(path_to_file, "rb") as file:
        application = DocumentApplication(path=application_path, name=application_name, content=file.read())
        return self.create(application=application, private=private, **kwargs)

delete(path, application_type, application_name, private=False, **kwargs)

Delete Planning Analytics application reference

Parameters:

Name	Type	Description	Default
path	str	path through folder structure to delete the applications entry. For instance: "Finance/Reports"	required
application_type	Union[str, ApplicationTypes]	type of the to be deleted application entry	required
application_name	str	name of the to be deleted application entry	required
private	bool	Access level of the to be deleted object	False

Returns:

Type	Description
Response

Source code in TM1py/Services/ApplicationService.py

def delete(
    self,
    path: str,
    application_type: Union[str, ApplicationTypes],
    application_name: str,
    private: bool = False,
    **kwargs,
) -> Response:
    """Delete Planning Analytics application reference

    :param path: path through folder structure to delete the applications entry. For instance: "Finance/Reports"
    :param application_type: type of the to be deleted application entry
    :param application_name: name of the to be deleted application entry
    :param private: Access level of the to be deleted object
    :return:
    """

    # raise ValueError if not a valid ApplicationType
    application_type = ApplicationTypes(application_type)

    if not application_type == ApplicationTypes.FOLDER and not verify_version(
        required_version="12", version=self.version
    ):
        application_name += application_type.suffix

    contents = "PrivateContents" if private else "Contents"
    mid = ""
    if path.strip() != "":
        mid = "".join([format_url("/Contents('{}')", element) for element in path.split("/")])

    url = format_url(
        "/Contents('Applications')" + mid + "/" + contents + "('{application_name}')",
        application_name=application_name,
    )
    return self._rest.DELETE(url, **kwargs)

exists(path, application_type, name, private=False, **kwargs)

Check if application exists

Parameters:

Name	Type	Description	Default
path	str		required
application_type	Union[str, ApplicationTypes]		required
name	str		required
private	bool		False

Returns:

Type	Description
bool

Source code in TM1py/Services/ApplicationService.py

def exists(
    self, path: str, application_type: Union[str, ApplicationTypes], name: str, private: bool = False, **kwargs
) -> bool:
    """Check if application exists

    :param path:
    :param application_type:
    :param name:
    :param private:
    :return:
    """
    # raise ValueError if not a valid ApplicationType
    application_type = ApplicationTypes(application_type)

    if not application_type == ApplicationTypes.FOLDER and not verify_version(
        required_version="12", version=self.version
    ):
        name += application_type.suffix

    contents = "PrivateContents" if private else "Contents"
    mid = ""
    if path.strip() != "":
        mid = "".join(["/Contents('{}')".format(element) for element in path.split("/")])

    url = format_url(
        "/Contents('Applications')" + mid + "/" + contents + "('{application_name}')", application_name=name
    )
    return self._exists(url, **kwargs)

get(path, application_type, name, private=False, **kwargs)

Retrieve Planning Analytics Application

Parameters:

Name	Type	Description	Default
path	str	path with forward slashes	required
application_type	Union[str, ApplicationTypes]	str or ApplicationType from Enum	required
name	str		required
private	bool		False

Returns:

Type	Description
Application

Source code in TM1py/Services/ApplicationService.py

def get(
    self, path: str, application_type: Union[str, ApplicationTypes], name: str, private: bool = False, **kwargs
) -> Application:
    """Retrieve Planning Analytics Application

    :param path: path with forward slashes
    :param application_type: str or ApplicationType from Enum
    :param name:
    :param private:
    :return:
    """
    # raise ValueError if not a valid ApplicationType
    application_type = ApplicationTypes(application_type)

    # documents require special treatment
    if application_type == ApplicationTypes.DOCUMENT:
        return self.get_document(path=path, name=name, private=private, **kwargs)

    if not application_type == ApplicationTypes.FOLDER and not verify_version(
        required_version="12", version=self.version
    ):
        name += application_type.suffix

    contents = "PrivateContents" if private else "Contents"
    mid = ""
    if path.strip() != "":
        mid = "".join([format_url("/Contents('{}')", element) for element in path.split("/")])

    base_url = format_url(
        "/Contents('Applications')" + mid + "/" + contents + "('{application_name}')", application_name=name
    )

    if application_type == ApplicationTypes.CUBE:
        response = self._rest.GET(url=base_url + "?$expand=Cube($select=Name)", **kwargs)
        return CubeApplication(path=path, name=name, cube_name=response.json()["Cube"]["Name"])

    elif application_type == ApplicationTypes.CHORE:
        response = self._rest.GET(url=base_url + "?$expand=Chore($select=Name)", **kwargs)
        return ChoreApplication(path=path, name=name, chore_name=response.json()["Chore"]["Name"])

    elif application_type == ApplicationTypes.DIMENSION:
        response = self._rest.GET(url=base_url + "?$expand=Dimension($select=Name)", **kwargs)
        return DimensionApplication(path=path, name=name, dimension_name=response.json()["Dimension"]["Name"])

    elif application_type == ApplicationTypes.FOLDER:
        # implicit TM1pyException if application doesn't exist
        self._rest.GET(url=base_url, **kwargs)
        return FolderApplication(path=path, name=name)

    elif application_type == ApplicationTypes.LINK:
        # implicit TM1pyException if application doesn't exist
        self._rest.GET(url=base_url, **kwargs)
        response = self._rest.GET(base_url + "?$expand=*", **kwargs)
        return LinkApplication(path=path, name=name, url=response.json()["URL"])

    elif application_type == ApplicationTypes.PROCESS:
        response = self._rest.GET(url=base_url + "?$expand=Process($select=Name)", **kwargs)
        return ProcessApplication(path=path, name=name, process_name=response.json()["Process"]["Name"])

    elif application_type == ApplicationTypes.SUBSET:
        url = "".join(
            [
                base_url,
                "?$expand=Subset($select=Name;$expand=Hierarchy($select=Name;$expand=Dimension($select=Name)))",
            ]
        )
        response = self._rest.GET(url=url, **kwargs)
        return SubsetApplication(
            path=path,
            name=name,
            dimension_name=response.json()["Subset"]["Hierarchy"]["Dimension"]["Name"],
            hierarchy_name=response.json()["Subset"]["Hierarchy"]["Name"],
            subset_name=response.json()["Subset"]["Name"],
        )

    elif application_type == ApplicationTypes.VIEW:
        response = self._rest.GET(url=base_url + "?$expand=View($select=Name;$expand=Cube($select=Name))", **kwargs)
        return ViewApplication(
            path=path,
            name=name,
            cube_name=response.json()["View"]["Cube"]["Name"],
            view_name=response.json()["View"]["Name"],
        )

get_all_private_root_names(**kwargs)

Source code in TM1py/Services/ApplicationService.py

def get_all_private_root_names(self, **kwargs):

    url = "/Contents('Applications')/PrivateContents"
    response = self._rest.GET(url, **kwargs)
    applications = list(application["Name"] for application in response.json()["value"])
    return applications

get_all_public_root_names(**kwargs)

Retrieve all public root application names.

Parameters:

Name	Type	Description	Default
kwargs		Additional arguments for the REST request.	{}

Returns:

Type	Description
	List of public root application names.

Source code in TM1py/Services/ApplicationService.py

def get_all_public_root_names(self, **kwargs):
    """
    Retrieve all public root application names.

    :param kwargs: Additional arguments for the REST request.
    :return: List of public root application names.
    """
    url = "/Contents('Applications')/Contents"
    response = self._rest.GET(url, **kwargs)
    applications = list(application["Name"] for application in response.json()["value"])
    return applications

get_document(path, name, private=False, **kwargs)

Get Excel Application from TM1 Server in binary format. Can be dumped to file.

Parameters:

Name	Type	Description	Default
path	str	path through folder structure to application. For instance: "Finance/P&L.xlsx"	required
name	str	name of the application	required
private	bool	boolean	False

Returns:

Type	Description
DocumentApplication	Return DocumentApplication

Source code in TM1py/Services/ApplicationService.py

def get_document(self, path: str, name: str, private: bool = False, **kwargs) -> DocumentApplication:
    """Get Excel Application from TM1 Server in binary format. Can be dumped to file.

    :param path: path through folder structure to application. For instance: "Finance/P&L.xlsx"
    :param name: name of the application
    :param private: boolean
    :return: Return DocumentApplication
    """
    if not name.endswith(ApplicationTypes.DOCUMENT.suffix) and not verify_version(
        required_version="12", version=self.version
    ):
        name += ApplicationTypes.DOCUMENT.suffix

    contents = "PrivateContents" if private else "Contents"
    mid = "".join([format_url("/Contents('{}')", element) for element in path.split("/")])
    url = format_url("/Contents('Applications')" + mid + "/" + contents + "('{name}')/Document/Content", name=name)

    content = self._rest.GET(url, **kwargs).content

    url = format_url("/Contents('Applications')" + mid + "/" + contents + "('{name}')/Document", name=name)
    document_fields = self._rest.GET(url, **kwargs).json()

    return DocumentApplication(
        path=path,
        name=name,
        content=content,
        file_id=document_fields.get("ID"),
        file_name=document_fields.get("Name"),
        last_updated=document_fields.get("LastUpdated"),
    )

get_names(path, private=False, **kwargs)

Retrieve Planning Analytics Application names in given path

Parameters:

Name	Type	Description	Default
path	str	path with forward slashes	required
private	bool	boolean	False

Returns:

Type	Description
	list of application names

Source code in TM1py/Services/ApplicationService.py

def get_names(self, path: str, private: bool = False, **kwargs):
    """Retrieve Planning Analytics Application names in given path

    :param path: path with forward slashes
    :param private: boolean
    :return: list of application names
    """
    contents = "PrivateContents" if private else "Contents"
    mid = ""
    if path.strip() != "":
        mid = "".join([format_url("/Contents('{}')", element) for element in path.split("/")])
    base_url = "/api/v1/Contents('Applications')" + mid + "/" + contents

    response = self._rest.GET(url=base_url, **kwargs)
    applications = list(application["Name"] for application in response.json()["value"])

    return applications

rename(path, application_type, application_name, new_application_name, private=False, **kwargs)

Source code in TM1py/Services/ApplicationService.py

def rename(
    self,
    path: str,
    application_type: Union[str, ApplicationTypes],
    application_name: str,
    new_application_name: str,
    private: bool = False,
    **kwargs,
):
    # raise ValueError if not a valid ApplicationType
    application_type = ApplicationTypes(application_type)

    if not application_type == ApplicationTypes.FOLDER and not verify_version(
        required_version="12", version=self.version
    ):
        application_name += application_type.suffix

    contents = "PrivateContents" if private else "Contents"
    mid = ""
    if path.strip() != "":
        mid = "".join([format_url("/Contents('{}')", element) for element in path.split("/")])

    url = format_url(
        "/Contents('Applications')" + mid + "/" + contents + "('{application_name}')/tm1.Move",
        application_name=application_name,
    )
    data = {"Name": new_application_name}

    return self._rest.POST(url, data=json.dumps(data), **kwargs)

update(application, private=False, **kwargs)

Update Planning Analytics application

Parameters:

Name	Type	Description	Default
application	Union[Application, DocumentApplication]	instance of Application	required
private	bool	boolean	False

Returns:

Type	Description
Response

Source code in TM1py/Services/ApplicationService.py

def update(self, application: Union[Application, DocumentApplication], private: bool = False, **kwargs) -> Response:
    """Update Planning Analytics application

    :param application: instance of Application
    :param private: boolean
    :return:
    """

    contents = "PrivateContents" if private else "Contents"

    mid = ""
    if application.path.strip() != "":
        mid = "".join([format_url("/Contents('{}')", element) for element in application.path.split("/")])

    if application.application_type == ApplicationTypes.DOCUMENT:
        url = format_url(
            "/Contents('Applications')" + mid + "/" + contents + "('{name}{extension}')/Document/Content",
            name=application.name,
            extension="" if verify_version("12", self.version) else ".blob"
        )
        response = self._rest.PATCH(url=url, data=application.content, headers=self.binary_http_header, **kwargs)
    else:
        url = "/Contents('Applications')" + mid + "/" + contents
        response = self._rest.POST(url, application.body, **kwargs)

    return response

update_document_from_file(path_to_file, application_path, application_name, private=False, **kwargs)

Update DocumentApplication in TM1 from local file

Parameters:

Name	Type	Description	Default
path_to_file	str		required
application_path	str		required
application_name	str		required
private	bool		False

Returns:

Type	Description
Response

Source code in TM1py/Services/ApplicationService.py

def update_document_from_file(
    self, path_to_file: str, application_path: str, application_name: str, private: bool = False, **kwargs
) -> Response:
    """Update DocumentApplication in TM1 from local file

    :param path_to_file:
    :param application_path:
    :param application_name:
    :param private:
    :return:
    """
    with open(path_to_file, "rb") as file:
        application = DocumentApplication(path=application_path, name=application_name, content=file.read())
        return self.update(application=application, private=private, **kwargs)

update_or_create(application, private=False, **kwargs)

Update or create Planning Analytics application

Parameters:

Name	Type	Description	Default
application	Union[Application, DocumentApplication]	instance of Application	required
private	bool	boolean	False

Returns:

Type	Description
Response	Response

Source code in TM1py/Services/ApplicationService.py

def update_or_create(
    self, application: Union[Application, DocumentApplication], private: bool = False, **kwargs
) -> Response:
    """Update or create Planning Analytics application

    :param application: instance of Application
    :param private: boolean
    :return: Response
    """
    if self.exists(
        path=application.path,
        application_type=application.application_type,
        name=application.name,
        private=private,
        **kwargs,
    ):
        response = self.update(application=application, private=private, **kwargs)
    else:
        response = self.create(application=application, private=private, **kwargs)
    return response

update_or_create_document_from_file(path, name, path_to_file, private=False, **kwargs)

Update or create application from file

Parameters:

Name	Type	Description	Default
path	str	application path on server, i.e. 'Finance/Reports'	required
name	str	name of the application on server, i.e. 'Flash.xlsx'	required
path_to_file	str	full local file path of file, i.e. 'C:\Users\User\Flash.xslx'	required
private	bool	access level of the object	False

Returns:

Type	Description
Response	Response

Source code in TM1py/Services/ApplicationService.py

def update_or_create_document_from_file(
    self, path: str, name: str, path_to_file: str, private: bool = False, **kwargs
) -> Response:
    """Update or create application from file

    :param path: application path on server, i.e. 'Finance/Reports'
    :param name: name of the application on server, i.e. 'Flash.xlsx'
    :param path_to_file: full local file path of file, i.e. 'C:\\Users\\User\\Flash.xslx'
    :param private: access level of the object
    :return: Response
    """

    if self.exists(path=path, application_type=ApplicationTypes.DOCUMENT, name=name, private=private):
        response = self.update_document_from_file(
            path_to_file=path_to_file, application_path=path, application_name=name, private=private
        )
    else:
        response = self.create_document_from_file(
            path_to_file=path_to_file, application_path=path, application_name=name, private=private
        )

    return response