Sample: Action URL XML Transformer

This sample demonstrates how to read and write XML to update the workbook files. XML transformers should use the XmlContentTransformerBase base class that handles parsing the file XML and saving the modified XML back to the file to be published.

XML transformers require additional resource overhead to execute, so care should be taken when developing them.

• Due to encryption, XML transformers require the file to be loaded into memory to modify. For large files, such as those with large extracts, this can require significant memory.
• Python XML transformers each require extra processing as the parsed XML is converted from a .NET representation to a Python representation. For files with large XML content this can require significant time and memory. Combining multiple Python XML transformers can minimize this impact.

In general, resource overhead can be mimized by implementing the NeedsXmlTransforming/needs_xml_transforming method, which allows the transformer to use the metadata of the content item to determine whether the XML file needs to be loaded.

XML transformers are provided with "raw" XML and no file format validation is performed by the SDK. Care should be taken when modifying workbook or other files that the changes do not result in content that is valid XML but invalid by the file format. File format errors can lead to migration errors during publishing, and can also cause errors that are only apparent after the migration is complete and reported success.

• Python
• C#

Transformer Class

To update action URLs in Python, you can use the following transformer class:

from xml.etree import ElementTree
from tableau_migration import (
    IPublishableWorkbook,
    XmlContentTransformerBase
)

class ActionUrlXmlTransformer(XmlContentTransformerBase[IPublishableWorkbook]):
    
    def needs_xml_transforming(self, ctx: IPublishableWorkbook) -> bool:
        # Returning false prevents the transform method from running.
        # Implementing this method potentially allows workbooks to migrate
        # without loading the file into memory, improving migration speed.
        return True

    def transform(self, ctx: IPublishableWorkbook, xml: ElementTree.Element) -> None:
        # Changes to the XML are saved back to the workbook file before publishing.
        for action_link in xml.findall("actions/*/link"):
            action_link.set("expression", action_link.get("expression").replace("127.0.0.1", "testserver"))

Registration

plan_builder.transformers.add(ActionUrlXmlTransformer)

See hook registration for more details.