• Cascade Server 5.7.3 Release Notes
• Cascade Server 5.7.2 Release Notes
• 2008 User's Conference Presentation Files
• Cascade Server 5.7.1 Release Notes
• Cascade Server 5.7 Release Notes
• Cascade Server 5.5.2 Release Notes
• Cascade Server 5.5.1 Release Notes
• Cascade Server 5.5 Release Notes
• New Asset Factory and Workflow Trigger Plugins

Implementation

Implementation ( download code)

The script will be segregated into two parts. The first part will parse the XML and construct two data structures, one containing all the web pages and another containing all the quotes. The second part will handle actually importing web pages and quotes into the system. Our script will process HTML web page content with PHP's Tidy interface. Tidy will ensure that our data is well-formed XHTML encoded in UTF-8, which is suitable for importing into Cascade. Finally, the PHP SOAP API will take the data as an associative array and make the appropriate Web Services calls to create page assets for each web page and quote.

Parsing the XML

PHP includes a built-in XML parser based on expat, which means that PHP XML Parsing functions can parse, but not validate XML. Ensure that the XML you pass PHP is valid. Our parser will be an event-based parser, so we will register some functions to run when the parser encounters certain XML elements (like character data or an opening tag). We will have to keep track of the state of the XML between events. For our purposes, a simple stack will be sufficient (we simply want to know if the current tag is part of quotes or webpages structure). Here is the code for setting up the parser:

function parse_xml() { global $pages; global $quotes; global $tagstack; /* The file that we will read our XML from */ $file = "data.xml"; /* Initialize the arrays that will hold all of our pages and * quotes. */ $pages = array(); $quotes = array(); /* Initialize the tag stack. This will be a stack of the tag * structure we are currently in */ $tagstack = array(); /* Create an XML Parser object */ $xml_parser = xml_parser_create(); /* Turn off case folding on the XML Parser object, this * will ensure that the parser will be case sensitive */ xml_parser_set_option($xml_parser, XML_OPTION_CASE_FOLDING, 0); /* Set the callback functions for the XML Parser object. The object * will call these functions when various actions happen */ xml_set_element_handler($xml_parser, "start_element", "end_element"); xml_set_character_data_handler($xml_parser, "character_data"); /* Try to open the XML file */ if (!($fp = fopen($file, "r"))) { die("could not open XML input"); } /* Read the data a bit at a a time */ while ($data = fread($fp, 4096)) { /* Try to parse that bit */ if (!xml_parse($xml_parser, $data, feof($fp))) { /* Give and error and quit if the parsing fails */ die(sprintf("XML error: %s at line %d", xml_error_string(xml_get_error_code($xml_parser)), xml_get_current_line_number($xml_parser))); } } /* Free the parser data */ xml_parser_free($xml_parser); }

Notice that we've initialized some arrays to hold all the web pages and quotes. We've also initialized the tag stack, which will record the current tag structure. For instance, when we are looking at an id tag inside of a web_pages tag, the stack will look like this:

Array ( [0] => id [1] => web_pages [2] => cms )

This allows us to have a look at the current context of an event. Let's take a look at the event callbacks that we registered in the previous code.

/* This function will be called by the XML parser when it * finds an opening tag */ function start_element($parser, $name, $attrs) { global $tagstack; global $pages; global $quotes; /* Push the current tag name onto our tag stack */ array_unshift($tagstack, $name); /* If we have just entered the context of the web_pages table * push a new web page data structure onto our $pages array */ if ($name == "web_pages") array_push($pages, array()); /* If we have just entered the context of the quotes table * push a new web page data structure onto our $quotes array */ if ($name == "quotes") array_push($quotes, array()); } /* This function will be called by the XML parser when it * finds a closing tag */ function end_element($parser, $name) { global $tagstack; /* We are exiting a tag, so we want to pop it off of our * tag stack */ array_shift($tagstack); }

When the parser finds an opening tag, we want to put that tag onto the tagstack. If the opening tag is one the ones we are interested in (either quotes or web_pages), we should prepare the appropriate array by adding a new empty entry. When we encounter a closing tag, we should pop one tag off of the tag stack.

/* This function will be called by the XML parser when it * finds character data between the opening and the closing * of a tag */ function character_data($parser, $data) { global $tagstack; global $pages; global $quotes; /* If we aren't deep enough to be in "web_pages" or "quotes" * don't do anything */ if (count($tagstack) < 2) return; /* The tag we are currently looking at will be the first element * on the tag stack. */ $current_tag = $tagstack[0]; /* If we are in the context of the web_pages table and * are inside of a child tag (notice we check the second element * of the stack */ if ($tagstack[1] == "web_pages") { $last = count($pages) - 1; /* If this is the first character data for this tag, then * initialize the entry in this page's array */ if (!isset($pages[$last][$current_tag])) $pages[$last][$current_tag] = ""; /* Append the character data to the current page's tag */ $pages[$last][$current_tag] .= $data; } /* If we are in the context of the web_pages table and * are inside of a tag */ if ($tagstack[1] == "quotes") { $last = count($quotes) - 1; /* If this is the first character data for this tag, then * initialize the entry in this quotes's array */ if (!isset($quotes[$last][$current_tag])) $quotes[$last][$current_tag] = ""; /* Append the character data to the current page's tag */ $quotes[$last][$current_tag] .= $data; } }

When we find character data between tags we want to figure out what context we are in (by looking one level down on the tag stack) and record the data if we need to. We want to place the data in an associative array inside of $pages and $quotes. This way a particular quote body will be $quotes[3]["body"], which will make it easier to access the data later. Notice that we always append data to fields. This is because the XML parser handles all character content, including other XML that is parses from inside of content tags of web_pages.

When the parser finishes its work, we should have two data structures, $pages and $quotes with the information from the XML file. Now let's take a look at the functions that will process and import our data.

Initially, the import_web_pages() function will configure Tidy to output the type of XHTML we need. Next, it will initialize some arrays to hold paths. The paths will be an associative array that acts like a hash table to keep track of each unique path.

function import_web_pages($pages) { /* Initialize a Tidy object, notice that we tell Tidy to * turn indenting off, output valid XHTML, only show the * body and turn all entities into their UTF-8 numeric * equivalents. We want to ensure that Cascade will accept * our XHTML */ $tidy_config = array('indent' => false, 'output-xhtml' => true, 'show-body-only' => true, 'numeric-entities' => true); $tidy = new tidy; /* Initialize some arrays to hold all the pages and paths we've * seen. In this case the path of each web page is stored in the * database. */ $paths = array();

The script will now iterate over every page pulled from the XML file. Notice that it replaces the old HTML in the content field with tidied XHTML. We ensure that the content will be valid and well-formed XHTML after the wrapping it in Cascade's system-xml tag.

/* Here we iterate over each line of the table that this query returns. * Each line will be an associative array which has keys equal to the * field names and value equal to the field values */ foreach ($pages as $key => $page) { /* Now we use the Tidy object to clean up the "content" field * which contains the content for the main block of each page. * We save this cleaned content back into the content field. */ $tidy->parseString($page["content"], $tidy_config, 'utf8'); $tidy->cleanRepair(); $page["content"] = tidy_get_output($tidy); /* Cascade requires that the content we use be well-formed XML, * thus we need to wrap the XML in a single root tag before * delivering it to the CMS */ $line["content"] = '<system-xml xmlns:cascade="http://www.hannonhill.com/CascadeServer/">' . $line["content"] . "</system-xml>"; /* Finally we want to end the HTML tag to complete the markup */ $page["content"] . '</html>';

Here we split the old CMS-style path field into a Cascade path and a system name for our new page. We know that path elements are separated by '/' so we look for the last one in the path. The string after that is the system name (once we remove the extension) and everything before it is the Cascade parent directory.

/* The old CMS had a field named "path" which stored the complete * path of the page, including directory structure and filename. * We want to separate this path out into these two parts, so * that we can add the pages to Cascade */ /* We want to find the string length of the path */ $pathlen = strlen($page["path"]); /* Next we find the position of the last (notice the use of strrpos) * directory seperator (the old CMS used a "/"). */ $filename_loc = strrpos($page["path"], "/"); /* Now we grab the part of the string after this last "/" so we can use * that as the page's system name */ $system_name = substr($page["path"], $filename_loc + 1, $pathlen - $filename_loc - 1); /* Because Cascade does not use page extensions in the CMS, we * want to remove the extension from the system name. In this case, * the old CMS used the ".htm" extension */ $system_name = str_replace(".htm", "", $system_name); /* We store the system name in the associative array, so that we * can use it later. */ $page["__system_name"] = $system_name; /* Now we want to transform the path into the part before the * page name */ $page["path"] = substr($page["path"], 0, $filename_loc);

Finally, we store the path in our previously-initialized array and end the foreach loop.

/* We are going to have to add all the paths we've seen on-the-fly, * so we add them to an associative array (the paths are the keys) */ $paths[$page["path"]] = true; if (!isset($page["metaDesc"])) $page["metaDesc"] = ""; if (!isset($page["keywords"])) $page["keywords"] = ""; if (!isset($page["title"])) $page["title"] = ""; /* Replace the old element in the array with this new one. * This is a safer method than doing foreach with references */ $pages[$key] = $page; }

The rest of import_web_pages() simply sorts the path array, creates a SOAP client and calls functions to add each folder ( add_folder()) and each web page ( add_page()). These functions will be described below.

/* We want to add parent paths before children, so we sort them by * their string length. We use uksort, because we are using the array * like a hash table and we want to sort on the keys */ uksort($paths, "comp_length"); /* Open up a SOAP client to the Cascade server. We give the URI of * the WSDL document describing Cascade Web Services */ $client = new SoapClient("http://my-cascade:8080/ws/services/AssetOperationService?wsdl", array('trace' => 1)); /* Iterate through the keys (each one is a single, unique path) of * $paths and add it to Cascade */ foreach ($paths as $path => $i) add_folder($path, $client); /* Iterate through the elements of $pages (each one is a an associative * array containing the page data) and add it to Cascade */ foreach ($pages as $page) add_page($page, $client); }

Adding a Single Folder

The add_folder() function adds a single folder to Cascade. It takes in the path of the folder to add and removes the last path element as the folder name. Then it constructs an associative array that the SOAP API will turn into a SOAP message. When using SOAP be warned that even though your message might conform to the WSDL that you use, this does not mean that your message was a success. Be sure to check the response that the server returns with __getLastReponse() as shown below.

In PHP the associative array that the SOAP functions accept is structured in a 'tag name' => "tag value" fashion. To pass in multiple tags of a particular tag name, simply associate the 'tag name' key with array of values. This is demonstrated in the add_page() function. Tags may be nested by associating particular tags with other associative arrays.

function add_folder($path, $client) { /* We need to find the last element on the path, which will * be the directory we want to create. We do this similarly to * the way we separated the page name from the path */ /* Find the string length of the path */ $pathlen = strlen($path); /* Find the position of the last path separator */ $folder_loc = strrpos($path, "/"); /* The folder name will be the substring after this separator */ $folder_name = substr($path, $folder_loc + 1, $pathlen - $folder_loc - 1); /* The parent folder for our new folder will be the parent directory */ $path = substr($path, 0, $folder_loc + 1); /* Now we fill an associative array that we will pass to the PHP * SOAP functions. The structure of this array will be determined * by the WSDL specification. PHP will interpret the structure * and create appropriate XML to pass to the Web Services */ $create_params = array ( 'authentication' => array( 'password' => "admin", 'username' => "admin" ), 'asset' => array( 'folder' => array( 'name' => $folder_name, 'metadataSetPath' => "/Default", 'parentFolderPath' => $path))); try { /* Pass the create parameters through the PHP SOAP client. */ $response = $client->create($create_params); /* If something goes wrong, it will be reported with * __getLastResponse, so be sure to take a look at the * message it returns. */ //print($client->__getLastResponse() . "\n"); } catch (Exception $e) { /* The request will throw an exception when parameters do * not conform to the WSDL. This will *not* catch errors * in the parameters themselves */ print("Folder creation request failed to conform to the WSDL.\n"); }

Adding a Single Web Page

The add_page() function is very similar to the add_folder() function, although the request structure is more complex and we must ensure that the metadata we pass to Cascade is valid UTF-8 text.

/* This function adds a page to the Cascade server with web * services. The page information should be stored in an * associative array, $pdata. */ function add_page($pdata, $client) { /* Ensure that all the metadata is encoded in UTF-8 */ $pdata["title"] = utf8_encode($pdata["title"]); $pdata["keywords"] = utf8_encode($pdata["keywords"]); $pdata["metaDesc"] = utf8_encode($pdata["metaDesc"]); /* Construct the parameters in the same way that we * constructucted them for the folder, though creating * a page requires a bit more information */ $create_params = array ( 'authentication' => array( 'password' => "admin", 'username' => "admin" ), 'asset' => array( 'page' => array( 'name' => $pdata["__system_name"], 'parentFolderPath' => $pdata["path"], 'metadataSetPath' => "/Default", 'configurationSetPath' => "/General/Simple Full HTML", 'xhtml' => $pdata["content"], 'metadata' => array( 'title' => $pdata["title"], 'keywords' => $pdata["keywords"], 'metaDescription' =>$pdata["metaDesc"])))); try { $response = $client->create($create_params); /* If something goes wrong, uncomment this line to read * the server's response to your SOAP request */ //print($client->__getLastResponse()); } catch (Exception $e) { print("Page creation request failed to conform to the WSDL.\n"); } }

Importing Quotes

Importing the quotes is very similar to importing the web pages with one major difference: instead of simply passing XHTML content to Cascade, we want to place values in a data definition. Before running this script, we created a data definition in Cascade named Quote which contained fields for the source, type, and body of each quote. Then we created a configuration set which would format this data definition. Here we see the data definition we used for each quote.

<system-data-structure xmlns:cascade="http://www.hannonhill.com/CascadeServer/"> <text identifier="type" label="Quote Type" type="dropdown"> <dropdown-item value="Training"/> <dropdown-item value="Analyst"/> <dropdown-item value="Client"/> <dropdown-item value="Media"/> </text> <text identifier="source" label="Quote Source"/> <text identifier="body" label="Quote" multi-line="true" wysiwyg="false"/> </system-data-structure>

Next, you can see the code for importing the quotes. Notice the structure of the parameter array this time. Structured data definition nodes are packaged in an array inside of the structuredDataNodes tag. Each element is an entry of the structuredDataNode array. To pass more than one node, simply add another level of arrays inside of structuredDataNode.

function import_quotes($quotes) { /* Construct a SOAP client connecting to Cascade instance */ $client = new SoapClient("http://my-cascade:8080/ws/services/AssetOperationService?wsdl", array('trace' =&gt; 1)); /* Create a folder to hold our quotes */ add_folder("//quotes", $client); /* Iterate through each quote */ foreach ($quotes as $quote) { /* Convert the quote body to UTF-8 encoding */ $quote["body"] = utf8_encode($quote["body"]); $quote["type"] = utf8_encode($quote["type"]); $quote["source"] = utf8_encode($quote["source"]); /* construct the parameters to create pages that use * data definitions. Notice the structure of the * structuredDataNodes. Each node is an array of the * elements of each data definition */ $create_params = array ( 'authentication' =&gt; array( 'password' =&gt; "admin", 'username' =&gt; "admin" ), 'asset' =&gt; array( 'page' =&gt; array( 'name' =&gt; $quote["id"], 'parentFolderPath' =&gt; "/quotes", 'metadataSetPath' =&gt; "/Default", 'configurationSetPath' =&gt; "/General/Simple XML", 'structuredData' =&gt; array( 'definitionPath' =&gt; "/Quote", 'structuredDataNodes' =&gt; array( 'structuredDataNode' =&gt; array( array( 'type' =&gt; "text", 'identifier' =&gt; "type", 'text' =&gt; $quote["type"]), array( 'type' =&gt; "text", 'identifier' =&gt; "source", 'text' =&gt; $quote["source"]), array( 'type' =&gt; "text", 'identifier' =&gt; "body", 'text' =&gt; $quote["body"]) ))) ) )); try { /* Pass this request to Web Services */ $response = $client-&gt;create($create_params); /* If something goes wrong check the value of * __getLastResponse() */ print("\n". $client-&gt;__getLastResponse() . "\n"); } catch (Exception $e) { /* The request will throw an exception when parameters do * not conform to the WSDL. This will *not* catch errors * in the parameters themselves */ print("Page creation request failed to conform to the WSDL.\n"); } } }

Summary

The Web Service interface to Cascade Server eases automation of asset creation. PHP's built-in SOAP and XML support makes it useful for migrating to Cascade Server from another product. Content passed to Cascade may have to be converted to XHTML with PHP Tidy and to UTF-8 with the PHP function, utf8_encode(). The PHP SOAP API requires parameters be formed using associative arrays, whose keys describe the tag names. If the call succeeds the server's response can be accessed through the __getLastResponse method of the SoapClient object. Migration becomes far less tedious and time consuming with the use of Web Services.

See Also

• Web Services