Web Services Examples

• Explanation

NEWS & TIPS

• Site Access Keys
• Top: Alt+t
  Previous: Alt+,
  Next: Alt+.
  Up: Alt+;
  (Note: use Ctrl on the Mac)

Explanation

Introduction

This guide will show you how to create, edit, read, publish, and delete assets using Cascade's WSDL.  In PHP, setting up the calls requires no complex coding of any kind; the data structure containing the asset is a simple nested associative array which you pass to a SOAP object. We will show you how to create this object, how to build your parameters, execute your request, and interpret the result. Solid knowledge of PHP is required, and knowledge of Cascade Server assets will most certainly be helpful.  You are not expected to know our WSDL.

1. Creating Our Services Object:

To begin, we will need to create our object that will be interacting with cascade.  This is known as a simple object access protocol object, or SOAP. PHP has a simple to use built-in constructor to create this object:
$service = new SoapClient( "http://localhost:8080/ws/services/AssetOperationService?wsdl", array('trace' => 1));
You will notice two parameters in the constructor.  The first parameter is the URL of the WSDL, which is always found at the address of your Cascade instance, followed by /ws/services/AssetOperationService?wsdl.  For this case, our CMS is located at http://localhiost:8080.  The second parameter indicates to the object that we want it to carry debugging information with it so we can debug errors and check results. 

2. Authentication

To do any operation in cascade, wsdl must provide valid credentials.  To do this, use need to create an array with two fields: username and password, like so:
$auth = array('username' => "admin", 'password' => "admin");
In this case, our username is 'admin', and our password is 'admin'.  Your authentication is now set.

3. Reading and Deleting

A. Creating the Parameters

If you are reading or deleting an asset, you will use identifier to set which asset you are reading from.  To do this, you will need to create an array that contains a 'type' field, and either an 'id' or a 'path' field, but not both.  An example identifier follows:
$id = array( 'type' => 'user','id' => "bob.johnson" );
An 'id' is typically only used with assets that have no containers, such as users and groups.  Most assets, including blocks, stylesheets, pages, configuration sets, and data definitions, use the 'path' field.  An example using that is shown here:
$id = array( 'type' => 'page', 'path' => '/internet/mywebsite/page1' );
The 'type' field corresponds to any type of asset supported by Cascade. You can choose one from the following list:

• assetfactory

• assetfactorycontainer

• block

• destination

• file

• folder

• group

• metadataset

• metadatasetcontainer

• page

• pageconfigurationset

• pageconfigurationsetcontainer

• publishset

• publishsetcontainer

• reference

• structureddatadefinition

• structureddatadefinitioncontainer

• stylesheet

• symlink

• target

• template

• transport

• user

• workflowdefinition

• workflowdefinitioncontainer

B. Sending the Read/Delete Request.

To try to read from cascade, we will use our main object that we instantiated earlier.  We will need to supply it with the $id and $auth parameters we made earlier.

First we need to create the array that houses both of these variables.  To do that, we create a $params variable that is an array with two fields: 'identifier' and 'authentication'. We need to set each of these fields to the values housed in our $id and $auth variables, like so:
$params = array( 'authentication' => $auth, 'identifier' => $id );
With this we can then execute our request to read or delete an asset by doing either of these two commands:
$reply = $service->read($params);
or
$reply = $service->delete($params);

C. Interpreting the Results.

The $reply variable used above stores the return value of the operation.  Aside from containing information on the asset you requested (assuming you performed a 'read'), it also contains useful debugging information, such as whether or not the command was successfully executed and the error message if it failed.  You can access any of these fields through the $reply variable like so:
$reply->readReturn->success; $reply->readReturn->message; $reply->readReturn->asset;
Success will return either 'true' or 'false'.  The message field will contain the error message if the operation failed.  Finally, the asset field contains the information for the asset that you requested.  The asset field is not available in a delete request.

4. Creating and Editing

A. Creating your asset.

To Create or Edit an asset, you must first create the asset you want using nested PHP arrays.  Much like we have done previously with the $auth, $id, and $param variables, the same approach is taken here.  Depending on what type of asset you want to create, a different set of fields is available.  For more information on asset fields, please refer to the section "Asset Fields."  Once the array has been built, you will combine these parameters with the $auth variable to execute the request.
Here is an example of a page asset being built:
$asset = array( 'page' =&gt; array ( 'parentFolderPath' =&gt; $rootLoc, 'metadataSetPath' =&gt; 'Default', 'expirationFolderPath' =&gt; $rootLoc, 'path' =&gt; '/internet/mywebsite/page1', 'shouldBePublished' =&gt; true, 'shouldBeIndexed' =&gt; true, 'configurationSetPath' =&gt; 'General/Simple XML', 'name' =&gt; 'page', 'xhtml' =&gt; '<a>stuff</a>', 'metadata' =&gt; array( 'author' =&gt; $rootLoc, 'title' =&gt; 'My Page')));
You will notice that the outer array has only 1 element in it.  This is because we need to specify what type of asset we are creating/editing before we supply the parameters.  The parameters themselves are supplied in the inner array, indicating that they are associated with the type of asset we chose.

B. Sending the Create/Edit Request.

To try to create or edit a page in cascade, we will use our $service object and combine our $auth and $asset to create the $params object we need, just like before.  We can execute our command using either the create or edit functions.  They can be executed as follows:
$params = array( 'authentication' =&gt; $auth,'asset' =&gt; $asset ); $reply = $service-&gt;create($params); $reply = $service-&gt;edit($params);
There is a slight difference in the parameters for the two commands though.  While editing requires the 'path' field, a create request should not have it.  If you're creating the asset, make sure to leave this field out, or at least set it to an empty string.

C. Interpreting the Results.

The create and edit requests both return a result object, which has the fields success and message.  Just like before, success is either 'true' or 'false', indicating success or failure.  The message parameter is there for you to debug any errors in your request, just like before.

5. Asset Fields

The following fields are available for your use when creating or editing an asset.  In addition, these are the fields available for you to read when you read an asset.

i. assetFactory

• applicableGroups: the groups that can use this asset id/path: the id or path of this asset.  Not used for create name: the name of this asset

• parentContainerId/parentContainerPath: where the asset should be stored

• allowSubFolderPlacement: whether or not to allow subfolder placement for this asset factory

• assetType: the type of asset that this assetfactory makes

• baseAssetId/baseAssetPath: the ID or Path of the base asset for this asset factory

• folderPlacementPosition: the folder placement position for this asset factory, for index blocks and such

• overwrite: whether or not to allow the asset factory to overwrite existing assets

• placementFolderId/placementFolderPath: the ID or path of the default folder for these assets

• workflowDefinitionId/workflowDefinitionPath: the ID or path of the workflow to be used for assets created by this asset

• workflowMode: workflow that governs assets created with this asset factory.
  
  Options include:

ii. assetFactoryContainer:

• applicableGroups: the groups that can use this asset

• children: a children object

• id/path: the id or path of this asset.  Not used for create

• name: the name of this asset

• parentContainerId/parentContainerPath: where the asset should be stored

iii. children:

• child: an array of child objects.

iv. child:

• id: the id for this object

• path: the path to this object

• type: the type of this object

v. destination:

• applicableGroups: the groups that can use this asset

• id/path: the id or path of this asset.  Not used for create

• name: the name of this asset

• directory: the directory to publish assets to

• enabled: if this destination is enabled or not

• publishASCII: if documents should be published in ascii or not

• publishInterval: the amount of time to wait between publishes.  Should be an int wrapped in a string

• publishIntervalUnits: the type of units that the time interval is specified in options are days and hours

• timeToPublish: the time to republish everything, in military time.  Format example: "13:00:00.0000" = 1:00 PM

• transportId/transportPath: the the id or path of the transport to use for publishing

• usesScheduledPublishing: whether or not to use the timeToPublish information to re-publish

vi. feedBlock:

• id/path: the id or path of this asset.  Not used for create

• name: the name of this asset

• parentFolderId/parentFolderPath: where the asset should be stored

• expirationFolderId/expirationFolderPath: the expiration folder id or path to send the block to

• when it expires

• feedUrl: the url to retrieve the feed from

• metadata: the metadata
  
  Options include:

All dates should be specified as DateTime objects

• metadataSetId/metadataSetPath: the metadata set ID or Path to use

vii. file:

• id/path: the id or path of this asset.  Not used for create

• name: the name of this asset

• parentFolderId/parentFolderPath: where the asset should be stored

• data: a byte array containing the data of the file, if it is a data file

• expirationFolderId/expirationFolderPath: the expiration folder id or path to send the block to when it expires

• metadata: the metadata
  
  Options include:

All dates should be specified as DateTime objects

• metadataSetId/metadataSetPath: the metadata set ID or Path to use

• shouldBeIndexed: if the file should be indexed or not

• shouldBePublished: if the file should be published or not
  text: the text contents of the file, if it is a text document.

viii. fileSystemTransport:

• id/path: the id or path of this asset.  Not used for create

• name: the name of this asset

• directory: the directory to publish assets to

• outputZip: if this should output file in a zip file

• overwrite: if this should overwrite existing files

ix. folder:

• children: a children object

• id/path: the id or path of this asset.  Not used for create

• name: the name of this asset

• parentFolderId/parentFolderPath: where the asset should be stored

• expirationFolderId/expirationFolderPath: the expiration folder id or path to send the block to when it expires

• metadata: the metadata
  
  Options include:

All dates should be specified as DateTime objects

• metadataSetId/metadataSetPath: the metadata set ID or Path to use

• shouldBeIndexed: if the file should be indexed or not

• shouldBePublished: if the file should be published or not

x. ftpTransport:

• id/path: the id or path of this asset.  Not used for create

• name: the name of this asset

• directory: the directory to publish assets to

• doPASV: use PASV

• doSFTP: use SFTP

• hostName: the host name

• username: the user name

• password: the password

• port: the port to use

xi. group:

• cssClasses: a list of which css classes the group members are allowed to use

• groupAssetFactoryContainerId/groupAssetFactoryContainerPath: the id or path to the asset factory container that the group members are allowed to use

• groupBaseFolderId/groupBaseFolderPath: the id or path to the base folder for this group

• groupName: the name of this group

• groupStartingPageId/groupStartingPagePath: the id or path of the starting page for this group

• role: the role that the members of this group have

• users: the users to be included in this group

• wysiwygAllowFontAssignment: if the members of this group can change the font of wysiwyg elements

• wysiwygAllowFontFormatting: if the members of this group can change the format of the wysiwyg fonts

• wysiwygAllowImageInsertion: if the members of this group can insert images into wysiwyg fields

• wysiwygAllowTableInsertion: if the members of this group can insert tables into wysiwyg fields

• wysiwygAllowTextFormatting: if the members of this group can format the text in wysiwyg fields

• wysiwygAllowViewSource: if the members of this group can view and edit the source of wysiwyg fields

xii. indexBlock:

• id/path: the id or path of this asset.  Not used for create
• name: the name of this asset
• parentFolderId/parentFolderPath: where the asset should be stored
• expirationFolderId/expirationFolderPath: the expiration folder id or path to send the block to when it expires
• appendCallingPageData: if the block should append the data for the calling page
• depthOfIndex: how deep the block should index files
• includeChildrenInHierarchy: if the block should include children of the indexed folders
• includeCurrentPageXML: if the current page XML should be included
• includePageContent: if the XML should be included for all pages
• indexAccessRights: if access rights should be indexed
• indexBlocks: if blocks should be indexed
• indexedFolderId/indexedFolderPath: the id or path of the folder to index
• indexFiles: if files should be indexed or not
• indexLinks: if links should be indexed or not
• indexPages: if pages should be indexed or not
• indexRegularContent: if regular content should be indexed or not
• indexSystemMetadata: if system metadata should be indexed or not
• indexUserInfo: if user info should be indexed or not
• indexUserMetadata: if user metadata should be indexed or not
• indexWorkflowInfo: if workflow information should be indexed or not
• maxRenderedAssets: the maximum amount of assets to render
• metadata: the metadata
  
  Options include:

All dates should be specified as DateTime objects

• metadataSetId/metadataSetPath: the metadata set ID or Path to use
• renderCurrentPageAndHierarchy: whether or not to render the current page and its hierarchy
•  sortMethod: the method to sort the index block by.
  Valid options are:

• alphabetical
• createddate
• folderorder
• lastmodifieddate

xiii. metadataSet:

• id/path: the id or path of this asset.  Not used for create

• name: the name of this asset

• parentContainerId/parentContainerPath: where the asset should be stored

• authorFieldRequired: if the author field is required or not

• authorFieldVisibility: the visibility of the author field.  Options: hidden, inline, visible

• descriptionFieldRequired: if the description field is required or not

• descriptionFieldVisibility: the visibility of the description field.  Options: hidden, inline, visible

• displayNameFieldRequired: if the display name field is required or not

• displayNameFieldVisibility: the visibility of the display name field.  Options: hidden, inline, visible

• dynamicFields: an array of dynamicMetadataFieldDefinition objects.  Fields for these objects are:
• • configurationXML: The dynamic metadata configuration for radio and checkboxes
  • fieldType: wsdl.dynamicmetadatafieldtype.dropdown, radio, or text
  • name: the name of the dynamic metadata
  • required: if it's required or not
  • visibility: if it's visible or not

• endDateFieldRequired: if the end date field is required or not
• endDateFieldVisibility: the visibility of the end date field.  Options: hidden, inline, visible
• keywordsFieldRequired: if the keywords field is required or not\
• keywordsFieldVisibility: the visibility of the keywords field.  Options: hidden, inline, visible
• reviewDateFieldRequired: if the review date field is required or not
• reviewDateFieldVisibility: the visibility of the review date field.  Options: hidden, inline, visible
• startDateFieldRequired: if the start date field is required or not
• startDateFieldVisibility: the visibility of the start date field.  Options: hidden, inline, visible
• summaryFieldRequired: if the summary field is required or not
• summaryFieldVisibility: the visibility of the summary field.  Options: hidden, inline, visible
• teaserFieldRequired: if the teaser field is required or not
• teaserFieldVisibility: the visibility of the teaser field.  Options: hidden, inline, visible
• titleFieldRequired: if the title field is required or not
• titleFieldVisibility: the visibility of the title field.  Options: hidden, inline, visible

xiv. metadataSetContainer:

• id/path: the id or path of this asset.  Not used for create

• name: the name of this asset

• parentContainerId/parentContainerPath: where the asset should be stored

xv. page:

• id/path: the id or path of this asset.  Not used for create

• name: the name of this asset

• parentContainerId/parentContainerPath: where the asset should be stored

• configurationSetId/configurationSetPath: the id or path of the configurationSet to use

• expirationFolderId/expirationFolderPath: the id or path of the expirationFolder to use

• metadata: the metadata
  
  Options include:

All dates should be specified as DateTime objects

• metadataSetId/metadataSetPath: the metadata set ID or Path to use

• shouldBeIndexed: if this page should be indexed or not

• shouldBePublished: if this page should be published or not

• structuredData: the structuredData of this page.  This is a wsdl.structureddata() object, and has the following fields:

• definitionId/definitionPath: the id or path of the data definition for the structured data

• structuredDataNodes: an array of structuredDataNode objects.

• structuredDataNode: These will have the following fields:

• • assetType: the type of asset, if the current node is an asset--either block, file, page, or symlink

  • blockId/blockPath: the id or path of the block, if the current structuredDataNode is a block

  • fileId/filePath: the id or path of the file, if the current structuredDataNode is a file

  • identifier: the identifier of the current structuredDataNode.  This is the identifier used in the structured data definition inside of CMS

  • pageId/pagePath: the id or path of the page, if the current structuredDataNode is a page

  • structuredDataNodes: a structuredDataNodes object

  • symlinkId/symlinkPath: the id or path of the symlink, if the current structuredDataNode is a symlink 
  • text: the text of the structuredDataNode

---

Topic Feedback Form

Content Rating:	1 - Best 2 3 - Average 4 5 - Poor
Email:
Feedback:

---

Wiki | Edit