TOM.NET API delta compared to 2009 (SP1)
Compared to SDL Tridion 2009 and SDL Tridion 2009 SP1, the TOM.NET API has changed considerably. Most of these changes are additions to the existing API, turning it from a read-only API into a full-fledged API for all Content Manager interactions. However, the existing TOM.NET API has also undergone a number of changes, which are explained in this topic.
Firstly, the following specific classes and members have changed:
ActivityDefinitionclass:Assignee-
Unlike before, you can validly pass the value
nullas a value for Assignee in cases where Assignee can only be one value: whennullis passed as the Assignee of the first Activity Definition, it is implicitly assumed to be Everyone, and whennullis pass as the Assignee of any Automatic Activity Definition, it is implicitly assumed to be the Workflow Agent User.
ActivityInstanceclass:Load-
Before, passing a valid item ID with Publication ID '0' or any other invalid publication ID could retrieve the item; now this is no longer possible. When trying to retrieve using any other Publication ID, an
ItemDoesNotExistexception is thrown. You need to pass in a valid URI with the right publication ID. Finish-
The next
Activityprovided in theDecisionActivityFinishobject must be a valid next activity for the current Decision Activity. Before, an exception would be thrown with error codeErrInvalidUri. Now, anInvalidActionExceptionis thrown withTcmErrorCode.InvalidNextActivity.
ApprovalStatusclass:Save-
Before, any user could create or update, and then save, an
ApprovalStatus; now, only users with Workflow Management rights and administrators can.
Categoryclass:Save-
Before, if
AllowedParentCategoriescontained more than one item, it was ignored. Now an exception is thrown.
Componentclass:Save- A Schema change for a localized Component is no longer allowed.
Folderclass:Delete-
It is no longer possible to delete a Root Folder. Previously you needed Folder Management and Publication Management rights; now, this will raise an
InvalidActionException.
Groupclass:Create-
A
PermissionDeniedExceptionis raised when you try to create a Group, you are not a system administrator and you do not have permission management rights to at least one Publication.
IdentifiableObjectclass:PropertyExists-
Changed accessibility from
publictointernal. Load- The state of a new item (default XML) now has proper allowed actions.
Save-
- Previously, a Schema check was performed on the XML to ensure that, say, Title was a string of 1-255 characters. An error with
TcmErrorCodeInvalidXMLwould be thrown. Now, the API throws anInvalidPropertyValueExceptionwhich usesTcmErrorCodeInvalidPropertyChange. - If a Content Manager URI in a link contains a version, an
InvalidUriExceptionis raised with error codeTcmErrorCode.InvalidVersion. Before, the error code wasTcmErrorCode.InvalidURI(which is just less specific).
- Previously, a Schema check was performed on the XML to ensure that, say, Title was a string of 1-255 characters. An error with
Update-
Before, an error would be thrown when an element that was invalid according to the item's schema (say,
<tcm:C />) was added to thetcm:Data Xmlnode while trying to save the item. This also applies forXmlElementsthat should be valid but are misspelled. Now, no error is thrown, instead the invalidXmlElementis ignored and the item will be saved if there are no validation errors. When anXmlElementthat should be valid but is misspelled is passed in, and there are no validation errors while saving, the item will be saved without the misspelled property. This behavior is only possible while using the deprecated R5 API
Keywordclass:Save-
- Before, when trying to change
ParentKeywordsof a localized Keyword, business rules were validated locally, and hence the specificErrorCode8004032F (ItemIsLocalized) was sent back. Now, this is done in a more generic way, so now for any invalid property change for a localizedRepositoryLocalObject, theErrorCodeis 80040301 (InvalidPropertyChange). - Before, when trying to add related Keywords, it was not verified if the user had Read access to the category. Now, a user needs Read access to the Category in order to add a keyword to
ParentKeywordorRelatedKeyword; if not, aPermissionDeniedException/PermissionDenied(80040242) is thrown. - In the new API, you cannot introduce a cycle by adding a Parent Keyword. This leads to an
InvalidPropertyValueException/CircularLinkDetected.
- Before, when trying to change
MultimediaTypeclass:ToXml-
Before, the
tcm:Infoelement was located after thetcm:Dataelement, although the Content Manager system schema (cm_xml.xsd) says it must be located before it. This bug was fixed. SetAllowedActions-
Before, the allowed actions for a
MultimediaTypealways allowedView,Edit, andDeletefor everyone. This does not reflect the actual allowed actions. Only administrators should be allowed to change and deleteMultimediaType. In the new API, the allowed actions forVieware always set to Allow, whileEditandDeleteare only set to Allow for administrator-level users.
OrganizationalItemclass:Load-
- The state of a new organizational item (default XML) includes default permissions. In the new API, default permissions for root organizational items include all trustees from the Publication (not just predefined groups, as before) that have rights.
- Previously, all users were given read access to all root items. Now, to be able to read a root item, a user needs at least one management right specified on the Publication, which means that the Publication itself must be accessible.
ProcessDefinitionclass:Save- There is no longer an explicit property for the first Activity; it is now assumed to be the first in the list.
ProcessInstanceclass:Load-
Before, passing a valid item ID with Publication ID '0' or any other invalid publication ID could retrieve the item; now this is no longer possible. When trying to retrieve using any other Publication ID, an
ItemDoesNotExistexception is thrown. You need to pass in a valid URI with the right publication ID.
Publicationclass:Save-
- A Publication with changed Workflow properties now checks during save if these items are from the same context Publication.
- Before, when interacting through the TOM, it was possible to set
PublicationUrlandMultimediaUrlto empty values. Now anInvalidPropertyValueExceptionis thrown. - Before, the values of
PublicationUrlandMultimediaUrlwere not checked during save. Now, they are checked for the presence of query strings, fragments, or non-English characters (none of which can occur in a relative path). If any of these are found, anInvalidPropertyValueExceptionis thrown.
Delete-
- Deleting a non-existent Publication now raises an exception.
- If a Publication has a published Taxonomy, you cannot delete that Publication: an
ItemIsInUseExceptionis thrown. - If a Publication has a published Structure Group, you cannot delete that Publication: an
ItemIsInUseExceptionis thrown. - Before, any user could delete an
ApprovalStatus; now, only users with Workflow Management rights and administrators can.
PublicationTargetclass:ToXml-
Previously, the
tcm:Infoelement was located after thetcm:Dataelement, although the Content Manager system schema (cm_xml.xsd) says it must come before it.This was fixed. TargetLanguage- The value ASP.NET no longer exists as a Target Language, it is instead mapped to TCDL.
Repositoryclass:WebDavUrl- You now get a WebDAV URL on a new item, which was null before.
Key-
The
Keyproperty did not exist before. When upgrading from an old version of the product, this property will be set to the name of the Publication. Load-
The state of a new
Repository(default XML) includes default Rights. This is the set of rights for default Groups which you get when you save a Repository/Publication for the first time.
RepositoryLocalObjectclass:WebDavUrl- You now get a WebDAV URL on a new item, which was null before.
Classify,Reclassify,Unclassify-
Before, when trying to Classify, Reclassify or Unclassify, passing in the URI of an invalid item type (not of a Keyword), the API would throw an exception with
TcmErrorCode.InvalidURI. Now, the item type of the URI is not checked when Classify, Reclassify or Unclassify is called. This will result in throwing anInvalidCastException. AssertValidContainer-
- Now, only users with Administrative privileges can create any item in the System Repository (
tcm:0-0-7). If a user who does not have Administrative privilege tries to create any item in the System Repository, aPermissionDeniedExceptionwill be thrown with error code 80040242. Previously, even a user who did not have Administrative privileges could create any item in the System Repository. - The error code for an invalid item type in a context (parent) URI was changed from 80040325 (
InvalidURI) to 80040348 (InvalidItemTypeInURI).
- Now, only users with Administrative privileges can create any item in the System Repository (
Schemaclass:GetTridionWebSchemaXml-
The size element for a Schema field will not be sent to output (for all fields except
XHTMLandMultiTextField) if no list was specified.tcm:SizeforNumberFieldandDataFieldhave become non-mandatory XML elements in the cm_xml.xsd schema.
TargetGroupclass:Save-
Before, a business rule checked for an incorrect value (string or empty) in
KeywordConditionValueand throws an exception (NumericalOperandRequired- 8004033A). Now, the API throws a .NET serialization exception (80040000) when trying to serialize XML into aDataobject.
TargetTypeclass:AccessControlList-
Before, the API used a new permission type called
TargetTypePermissionsthat had onePermissionType:UseTargetType. This has been changed: the rightRights.PublishManagementis now reused to indicate that you can publish to this Target Type. Load-
Before, everyone could read the permissions on a Target Type. Now, only an administrator can to see the rights on a Target Type. Non-administrator users can still view the Target Type, but the
AccessControlListwill be empty. ToXml-
Previously, the
tcm:Infoelement was located after thetcm:Dataelement, although the Content Manager system schema (cm_xml.xsd) says it must come before it.This was fixed. - constructor
-
Before, when creating a new
TargetType, an administrator-level user was not able to set the security settings immediately on the Target Type. the Target Type had to be saved first and then the Security tab was enabled when re-opening. Now, the Security tab is enabled immediately when creating a new Target Type.
Templateclass:ParameterSchema- Before, this property could not be set to null. Now it can be, effectively removing the Parameter Schema.
TemplateTypeclass: before, this class implemented theIXmlSerializableinterface. Now, it no longer does.TemplateTypesclass: before, this class implemented theIXmlSerializableinterface. Now, it no longer does.TrackingKeyConditionclass:Value-
- Before, if you entered a value 012 (or +12) it is stored as 012 (or +12); now, the value that will be stored is the interpreted value, so 012 or +12 will be 12.
- Before, you could enter a very big number and it was stored exactly the same way; now this very big number will be converted to another format, say, 1E+15 (a format that was already accepted previously).
Userclass:- constructor
-
The
Titleproperty contains the valueNew User(localized) instead ofString.Empty.
VersionedItemclass:Load-
- Previously, the
AllowedActionforVersionedItemshad theRollbackflag not set inAllowandDeny. This is not correct, the options should be there but denied. This was fixed. - Before, a
TcmErrorCode.AccessDeniedwould be thrown when an user tries to load an item and does not have the required permissions and/or rights. Now, aPermissionDeniedExceptionis thrown which usesTcmErrorCode.PermissionDenied.
- Previously, the
UndoCheckout-
Before, it was possible for a properly authorized user to undo a check-out on an item checked out by another user, although this should have been stopped with proper business rule validation. Now, a
PermissionDeniedExceptionis raised if you are not the administrator and you attempt this. CheckOut-
- An Administrator user is now allowed to read a new item that has not been checked in yet.
- Before, you were able to call
CheckOut()on a version of an item. Now, anInvalidUriExceptionis thrown.
GetRollbackComments-
This method is deprecated. The replacement method is
GetListDeletedReferences(). The methods differ in the name of the root XML element:GetRollbackComments()returns<tcm:RollbackComments>whereasGetListDeletedReferences()returns<tcm:ListDeletedReferences>. The XML returned by both the methods does not include the 'Modified' attribute anymore (before, it was always the current date, now removed as pointless). The system schema is fixed to include theSubTypeoptional attribute, which was missing. Rollback-
- Before, a rollback to a non-existent version resulted in an exception with
ItemVersionDoesNotExisterror code (8004032A). Now, the error code isItemDoesNotExist(8004034D). - Before, a rollback to a zero version (that is, an editable version) resulted in an
ErrInvalidVersion exception(error code -2147220698), even when the item didn't have a zero version. In the latter case, the API now throws anItemDoesNotExistexception.
- Before, a rollback to a non-existent version resulted in an exception with
WorkItemclass:Load-
Before, passing a valid item ID with Publication ID '0' or any other invalid publication ID could retrieve the item; now this is no longer possible. When trying to retrieve using any other Publication ID, an
ItemDoesNotExistexception is thrown. You need to pass in a valid URI with the right publication ID.
In addition, the class Tridion.Localization.StringResourceManager had previously erroneously been made public (in Tridion.Common). This mistake has now been rectified: StringResourceManager is now in Tridion.Common.Core and is no longer public.
Finally, existing code that specifies null as the value of a Filter parameter now breaks. This is because Filter used to be loosely typed, and must now be either a non-null value or no parameter at all. To accommodate this change, simply remove the null value, changing the call to a parameter-less call.