• KB Home |
• Need Help?

Learning Levels

• Digest
• Concept
• Technical

Announcements

Cascade Server's Web Services interface exposes to SOAP clients an interface for adding and editing assets. This allows repetitive or difficult tasks to be accomplished easily with any SOAP-compatible programming language. As a demonstration of these features, this entry will further explain the task of importing many database entries (from an old CMS) into Cascade Server with PHP and SOAP calls. Web Services makes this process much quicker than a manual import.

Preparation for Web Services Database Migration

To access Cascade Web Services with PHP, users will obviously need a working PHP installation as well as an installation of Cascade Server. To use the MySQL, SOAP, and Tidy interfaces in PHP ensure that the following lines are in the php.ini file:

On Unix-like systems ensure that the following lines are in your php.conf file:

The Database

The data that the import application will import is stored in database from a homegrown CMS application. In this case, the database is structured with two tables, one containing web pages and another containing quotes. Each entry in the web_pages table consists of a block of HTML content, a path, and some miscellaneous metadata. The script will import the old pages into an existing template in the system, while preserving the metadata and path. This will require a folder structure to hold the pages. The script will take care of this step as well. The quotes table contains unformatted quotes with an entry for the type of quote, the source of the quote and the quote body itself. The script will pull this data from the database and create a page using a data definition for quotes.

TABLE 1: the structure of the web_pages table

Id	title	path	keywords	content	metaDesc
1	Company Overview	/company/index.html	Our Company, Service providers, global business, e-economy solutions	<p>Within five years we have seen <i>global...	A quick overview of our company
2	Mission Statement	/company/statement.html	Our Company, Service providers, global business, mission	<p>When our company started...	The statement of our mission
3	ProductOne Overview	/products/product1.html	Our Company, Service providers, global business, ProductOne	<p>Advancements in research through...	Overview of the features of ProductOne

TABLE 2: the structure of the quotes table

 

id	type	source	body
1	Training	Francois de La Rochefoucauld	Good advice is something a man gives when...
2	Global	Jim Cantalupo	And ours is a business that requires discipline and focus.

 

Implementation of Web Services Database Migration Script

The script will be segregated into two parts. The first part will handle importing the web pages, while the second will handle importing quotes. To import the web pages from the MySQL database, the script will first fetch the data with PHP's MySQL API. Next it will tidy it up 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. The procedure for importing quotes will be similar.

Importing the Web Pages

Initially, the import_web_pages() function will attempt a connection with the MySQL server. Luckily, PHP makes MySQL interaction very simple with an intuitive API. The script also configures Tidy to output the type of XHTML we need.

function import_web_pages() { /* Connect to the database server containing the legacy content */ $link = mysql_connect('mysql-host', 'mysql-user', 'mysql-password') or die('Could not connect: ' . mysql_error()); /* Select the database with our old content */ mysql_select_db('cms_database'); /* 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;

Next, the script will initialize some arrays to hold pages and paths. The paths will be an associative array that acts like a hash table to keep track of each unique path. Finally, we will send the query to the MySQL server and store the result set in $result.

/* 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(); $pages = array(); /* Do an SQL query on the data base to select the pages we * want to process. The pages are stored in a table called * "web_pages" */ $result = mysql_query("SELECT * FROM web_pages");

The script will now iterate over every result returned from the table. 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 */ while($line = mysql_fetch_assoc($result)) { /* 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($line["content"], $tidy_config, 'utf8'); $tidy->cleanRepair(); $line["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>";

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($line["path"]); /* Next we find the position of the last (notice the use of strrpos) * directory seperator (the old CMS used a "/"). */ $filename_loc = strrpos($line["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($line["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. */ $line["__system_name"] = $system_name; /* Now we want to transform the path into the part before the * page name */

Finally, we store the path and the page in our previously-initialized arrays and end the while loop.

/* Store this page's associative array so that we can add it * to the CMS through Web Services later */ array_push($pages, $line); /* 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[$line["path"] = true;

The rest of import_web_pages() simply closes the MySQL connection, 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.

/* Here we free the data structure for the MySQL result */ mysql_free_result($result); /* Close the MySQL link*/ mysql_close($link); /* 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 on is an associative * array containing the page data) and add it to Cascade */ foreach ($page 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> <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() { /* Connect to the database server containing the legacy content */ $link = mysql_connect('mysql-host', 'mysql-user', 'mysql-password') or die('Could not connect: ' . mysql_error()); /* Select the database with our old content */ mysql_select_db('cms_database'); /* 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); /* Do a MySQL query to pull all the rows from the quotes * table. */ $result = mysql_query("SELECT * FROM quotes"); /* Iterate through each quote */ while($quote = mysql_fetch_assoc($result)) { /* 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/Quote", '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"); } } mysql_free_result($result); }

Summary

The Web Service interface to Cascade Server eases automation of asset creation. PHP's built-in SOAP and MySQL 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.

Downloads

• php_mysql_soap-php.txt

© 2001 - 2008 Hannon Hill Corporation

Site Index | HH Internet | Beta Feedback

Contact Us: Online Form | +1.678.904.6900