Web Services Examples
Author: John Stokely
1. IntroductionThis guide will walk you through using the provided wsdl.php file to use php to interact with web services, or creating
your own. Basic knowledge of php is necessary to use this guide to interact with the provided dll, and advanced
knowledge of php as well as wsdl and xml is needed to create a custom web services dll. Knowledge of wsdl is also
useful for using the dll, but not required.
2. Adding references
To use the php file, it must first be added included in you current php file. include_once will insure that you don't
accidentally include it multiple times, and will prevent you from getting errors about redeclaring classes
3. Using the provided file
Once you have added wsdl.php included in your current project, you are ready to begin using it. The main purposes
for using wsdl are to read, create, edit, delete, and publish assets. An asset is anything in cascade that you can
modify, from users and groups to pages and templates.
a. Creating our main object:
To begin, we will need to create our object that will be interacting with cascade. In this case, the object
is called AssetOperationHandlerService, so use {code}$service = new AssetOperationHandlerService;{code}
Once we have our object, we need to set the URL that it will be interacting with. To do this type
{code}services->url = "myUrl"{code}, where myUrl is the full URL to your CMS instance, with
ws/services/AssetOperationService?wsdl appended to the end. For example, if this
will be run from the same machine that your CMS instance is installed on, it will most likely be
http://localhost:8080/ws/services/AssetOperationService?wsdl. If you do not provide the full url, including
the http://, this will not work. If no Url is specified, it will default to
http://localhost:8080/ws/services/AssetOperationService?wsdl
b. Authentication
To do any operation in cascade, wsdl must provide valid credentials. To do this, use the authentication
object. After you have instantiated it, set its username and password to the account information that you wish
to use.
c. Reading and Deleting
i. Choosing our asset to interact with
If you are reading or deleting an asset, you will use identifier to set which asset you are reading
from. To do this, instantiate a new identifier. Next, set its path OR id field, but not both. If
both are provided, it defaults to ignoring the id and using the path. To ignore the path instead,
set {code}$squelchValue = "path";{code}. The path should point to the full path within CMS that the
object resides in, ie. "intranet/site-map". The id should hold the asset's identifier within cascade,
which is unique for each asset. To find an asset's id within cascade, navigate to that asset as you
normally would. Then look in your browser's address bar. The URL is a get request, which shows you
the asset that you are opening's type and ID. For example, the id is the portion between "id=" and
"#highlight", and the type is the portion between "type=" and "&". Next, you will supply your
identifier's type. This will be a:
assetfactory, assetfactorycontainer, block, destination, file, folder, group, metadataset,
metadatasetcontainer, page, pageconfigurationset, pageconfigurationsetcontainer, publishset,
publishsetcontainer, reference, structureddatadefinition, structureddatadefinitioncontainer, stylesheet,
symlink, target, template, transport, user, workflowdefinition, or workflowdefinitioncontainer.
ii. Sending the read request.
To try to read from cascade, we will use our main object that we instantiated earlier. The function
name is read and it takes out authentication and identifier as parameters. For example,
{code}services.read(auth, id);{code}. will send a read request with the authentication "auth"
and the identifier "id".
iii. Interpreting the results.
The result from the read is stored into a string inside of your assetOperationHandlerService called
"fullXML", which can be accessed with {code}$service->fullXML;{code} for debugging purposes. This
xml is immediately broken into 3 fields within the service--message, success, and asset.
Success is either "true" or "false" depending on the outcome of the read request. If the
asset could not be found, a false will be returned. If the asset was found and everything registered
correctly, a true will be returned. To see what exactly went wrong with your read request, check the
message field. If success is "false", this will hold any available information to help you determine
the cause of the failure. The third field, asset, is only returned if the read operation is successful.
The easiest (and only suggested) way to view the results of a read is with
{code}$service->serialize(){code}. This will recursively break the contents of each object up into
arrays. So that the asset contents of a read request can be immediately used in a edit request, all
choice fields, such as id/paths, only display the path. If you wish to display the id instead, set
{code}$squelchValue = "path";{code}. If you wish to display all contents of your objects, set
{code}$squelchValue = "";{code}.
iv. Sending the delete request.
To try to read from cascade, we will use our main object that we instantiated earlier. The function
name is delete and it takes out authentication and identifier as parameters. For example,
{code}services.delete(auth, id);{code}. will send a delete request with the authentication "auth"
and the identifier "id".
v. Interpreting the results.
The result from the delete is stored into a string inside of your assetOperationHandlerService called
"fullXML", which can be accessed with {code}$service->fullXML;{code} for debugging purposes. This
xml is immediately broken into 3 fields within the service--message, success, and asset.
Success is either "true" or "false" depending on the outcome of the read request. If the
asset could not be found, a false will be returned. If the asset was found and everything registered
correctly, a true will be returned. To see what exactly went wrong with your read request, check the
message field. If success is "false", this will hold any available information to help you determine
the cause of the failure. At this time, the asset field is not used for delete requests.
e. Creating and Editing
i. Similarities and differences.
Creating and editing an object within CMS is almost an identical operation. When you are editing an
asset, you have to supply the additional field "path," which will contain the full path to the asset
being modified, or "id" which will contain the CMS's unique id for the asset. However, when you
are creating an object, both of these fields must be left empty. Also, creating an asset implies
that it does not already exist, while editing it implies that it does exist. This means that if
you create an asset with a name that already exists within CMS, CMS will automatically append a
number to the name, and create it anyway. Therefore, if you only want to create an asset if it doesn't
exist, the safest thing to do is try to read it first. If the asset doesn't exist, the readResult's
success field will be "false", and the message will specify that the specified asset could not be found.
At this point, you know that you can safely create the page without creating a duplicate within CMS.
ii. Creating your asset.
To Create or Edit an asset, you must first create what you want the asset to be within C#. For example,
if you are creating a page, you must first instantiate a wsdl.page object. Next, you must set all of
its fields that you want to be set when the page is created within the CMS. For more information on
asset fields, please refer to the section "Asset Fields." Once the asset that you are creating or
editing is complete, create an Asset object, and set its field with the name of your object to be the
asset that you just created. For example, if you made a xmlBlock, set
{code}$asset->xmlBlock = $myXMLBlock;{code}. The asset that we create this way will be the asset that
we pass to the wsdl to create or edit a page. All fields that are objects are named after the class that
the field should contain.
iii. Sending the create or edit request.
To try to create or edit a page in cascade, we will use our main object that we instantiated earlier.
The function name for creating a page is "create", and the function for editing a page is "edit."
They both take in the asset and the authentication that we created. For example,
{code}services.create(auth, asset);{code}. will send a read request with the authentication "auth"
and the wsdl.asset "asset".
iv. Interpreting the results.
The create and edit requests both return a wsdl.operationResult object, which has the fields success,
and message. Success will indicate if the asset was created or edited successfully with either the
text "true" or "false". Message will have any additional information, if the operation failed.
f. Assets and their 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 factory
workflowMode: which workflows assets created with this asset factory are governed by.
Options include:
wsdl.assetfactoryworkflowmode.factorycontrolled: controlled by the asset factory
wsdl.assetfactoryworkflowmode.foldercontrolled: controlled by the folder that the
asset is created in
wsdl.assetfactoryworkflowmode.none: no workflow will be used for these assets
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 for this block. Valid fields are author, displayName, endDate,
keywords, metaDescription, reviewDate, startDate, summary, teaser, and title. Their functions
are exactly the same as they are inside of CMS. All dates should be specified as C# 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 for this block. Valid fields are author, displayName, endDate,
keywords, metaDescription, reviewDate, startDate, summary, teaser, and title. Their functions
are exactly the same as they are inside of CMS. All dates should be specified as C# 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 for this block. Valid fields are author, displayName, endDate,
keywords, metaDescription, reviewDate, startDate, summary, teaser, and title. Their functions
are exactly the same as they are inside of CMS. All dates should be specified as C# 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 for this block. Valid fields are author, displayName, endDate,
keywords, metaDescription, reviewDate, startDate, summary, teaser, and title. Their functions
are exactly the same as they are inside of CMS. All dates should be specified as C# 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:
wsdl.indexblocksortorder.alphabetical, wsdl.indexblocksortorder.createddate,
wsdl.indexblocksortorder.folderorder, and wsdl.indexblocksortorder.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 for this block. Valid fields are author, displayName, endDate,
keywords, metaDescription, reviewDate, startDate, summary, teaser, and title. Their functions
are exactly the same as they are inside of CMS. All dates should be specified as C# 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 stru
- web-services-examples-php.txt
This is the main script that provides example code for all the Cascade Server web services. - wsdl-php.txt
This is the PHP API wrapper file for the Cascade Server web services.
Last modified on Mon, 30 Oct 2006 12:47:28 -0500
Top / Up / Table of Contents