Web Services Examples

• Overview

NEWS & TIPS

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

Web Services Examples

Author: John Stokely

Introduction

This 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.

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 

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  $service = new AssetOperationHandlerService;  

Once we have our object, we need to set the URL that it will be interacting with.

To do this type: services->url = "myUrl", 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  $squelchValue = "path";.  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, which will be one of the following:

• 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

 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, services.read(auth, id); . 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  $service->fullXML;  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 $service->serialize() .  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 $squelchValue = "path"; . If you wish to display all contents of your objects, set $squelchValue = "", .

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, services.delete(auth, id); . 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  $service->fullXML;  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 $asset->xmlBlock = $myXMLBlock; .  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, services.create(auth, asset);  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:

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
  • 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 structuredDataNode

1. web-services-examples-php.txt
   This is the main script that provides example code for all the Cascade Server web services.
2. wsdl-php.txt
   This is the PHP API wrapper file for the Cascade Server web services.

---

Wiki | Edit