.NET API

Author: John Stokely

1. Introduction

This guide will walk you through using the provided wsdl.dll file to use C# to interact with web services, or creating your own. Basic knowledge of C# is necessary to use this guide to interact with the provided dll, and advanced knowledge of C# 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 dll, it must first be added as a reference in your current C# file. If you are working in Microsoft Visual C# or Microsoft Developer's Studio, click open your current project, then click on the Project dropdown at the top of the screen, and select "Add Reference." If you are working in Visual Web Developer and are currently working on a website, the dropdown will be called "Website." Next, click on the "Browse" tab, and navigate to the directory where you saved wsdl.dll. Select it, click ok, and you will be able to use all of its features.

3. Using the provided dll

Once you have added wsdl.dll as a reference in your current project, you are ready to begin using it. The main purposes for using wsdl are to read, create, edit, and delete 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 dll, the object is called AssetOperationHandlerService. Everything in our dll is in the wsdl namespace, so we will need to create the service using:

wsdl.AssetOperationHandlerService services = new wsdl.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 wsdl.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 wsdl.identifier to set which asset you are reading from. To do this, instantiate a new wsdl.identifier. Next, set its path OR id field, but not both. 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 wsdl.entityTypeString. This is an enumerator, and the valid choices are: assetfactory, assetfactorycontainer, block, destination, file, folder, group, metadataset, metadatasetcontainer, page, pageconfigurationset, pageconfigurationsetcontainer, publishset, publishsetcontainer, reference, structureddatadefinition, structureddatadefinitioncontainer, stylesheet, symlink, target, template, transport, user, workflowdefinition, and workflowdefinitioncontainer. To use enumerators in C#, you will be typing wsdl.entityType.choice, ie.

id.type = wsdl.entityTypeString.page;

if your identifier's name is "id" and the type of asset that you are reading from is a page.

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 authentacation 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 read function returns a readResult object, with 3 fields that matter: success, message, 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. First, you need to select the asset type that you were reading. For example, if you stored your read result in the object "result" and you were reading a page, you will access this data with result.asset.page. Each asset has different fields, depending on what type of asset it is. For more information on what fields individual asset types have, please refer to the section "Asset Fields."

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 authentacation 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 create and edit requests both return a wsdl.operationResult object, which has the fields success, and message. Success will indicate if the asset was deleted succesfully with either the text "true" or "false". Message will have any additional information, if the operation failed.

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 a wsdl.asset object, and set its "Item" to be the asset that you just created. This will be the asset that we pass to the wsdl to create or edit a page.

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 succesfully 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

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 facotry 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

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

parentContainerId/parentContainerPath: where the asset should be stored

iii. destination:

applicableGroups: the groups that can use this asset

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

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 wsdl.timeUnits.days and wsdl.timeUnits.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

iv. feedBlock:

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

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

v. file:

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

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

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.

vi. fileSystemTransport:

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

directory: the directory to publish assets to

outputZip: if this should output file in a zip file

overwrite: if this should overwrite existing files

vii. folder:

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

parentFolderId/parentFolderPath: where the asset should be stored

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

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

viii. ftpTransport:

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

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

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

x. indexBlock:

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

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

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

xi. metadataSet:

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

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 wsdl.dynamicMetadataFieldDefinition()s. Fields for these objects are:

configurationXML: The dynamic metadata configuration for radio and checkboxes

fieldType: wsdl.dynamicmetadatafieldtype.dropdown, radio, or text

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

xii. metadataSetContainer:

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

parentContainerId/parentContainerPath: where the asset should be stored

xiii. page:

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

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

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 structuredDataNodes. These will have the following fields:

assetType: the type of asset, if the current node is an asset--either wsdl.structureddataassettype.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: an array of structuredDataNodes

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

text: the text of the structuredDataNode, if it is a plain text node

type: the type of the structuredDataNode that we are currently on. This is of type wsdl.structureddatatype.asset, group, or text. It is a group is it is an array of structuredDataNodes, an asset if it is any type of asset, and text if it is anything else

xhtml: the xhtml of this page

xiv. pageConfigurationSet:

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

pageConfigurations: array of wsdl.pageConfiguration()s. Fields for these objects are:

defaultConfiguration: whether or not it's the default configuration or not

id: the id for this pageConfiguration

wsdl.dll
The DLL needed by .NET scripts to perform web services actions.
wsdl.cs
This is the code wrapper that encapsulates different web service calls using .NET.

Last modified on Mon, 05 Feb 2007 15:08:48 -0500

Top / Up / Table of Contents

.NET API

NEWS & TIPS

.NET API

1. Introduction

2. Adding references

3. Using the provided dll