.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 VisualC# 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 ona 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 purposesfor 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:
{code}wsdl.AssetOperationHandlerService services = new wsdl.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 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.
{code}id.type = wsdl.entityTypeString.page;{code} 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,
{code}services.read(auth, id);{code}. 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,
{code}services.delete(auth, id);{code}. 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,
{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 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
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 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
name: the name of this asset
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
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
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
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
v. 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.
vi. 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
vii. folder:
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
viii. 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
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
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
xi. 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 wsdl.dynamicMetadataFieldDefinition()s. 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
xii. 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
xiii. 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 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
name: the name of this asset
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
name: the name of this pageConfiguration

- Class1.cs
This is the code wrapper that encapsulates different web service calls using .NET. - dot-net-api.zip
This is a zip file with the necessary code behind and DLL to use the web services API. - wsdl.dll
Last modified on Mon, 30 Oct 2006 12:47:37 -0500
Top / Up / Table of Contents