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:

  • ActivityDefinition class:

    Assignee
    Unlike before, you can validly pass the value null as a value for Assignee in cases where Assignee can only be one value: when null is passed as the Assignee of the first Activity Definition, it is implicitly assumed to be Everyone, and when null is pass as the Assignee of any Automatic Activity Definition, it is implicitly assumed to be the Workflow Agent User.
  • ActivityInstance class:

    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 ItemDoesNotExist exception is thrown. You need to pass in a valid URI with the right publication ID.
    Finish
    The next Activity provided in the DecisionActivityFinish object must be a valid next activity for the current Decision Activity. Before, an exception would be thrown with error code ErrInvalidUri. Now, an InvalidActionException is thrown with TcmErrorCode.InvalidNextActivity.
  • ApprovalStatus class:

    Save
    Before, any user could create or update, and then save, an ApprovalStatus; now, only users with Workflow Management rights and administrators can.
  • Category class:

    Save
    Before, if AllowedParentCategories contained more than one item, it was ignored. Now an exception is thrown.
  • Component class:

    Save
    A Schema change for a localized Component is no longer allowed.
  • Folder class:

    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.
  • Group class:

    Create
    A PermissionDeniedException is 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.
  • IdentifiableObject class:

    PropertyExists
    Changed accessibility from public to internal.
    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 TcmErrorCode InvalidXML would be thrown. Now, the API throws an InvalidPropertyValueException which uses TcmErrorCode InvalidPropertyChange.
    • If a Content Manager URI in a link contains a version, an InvalidUriException is raised with error code TcmErrorCode.InvalidVersion. Before, the error code was TcmErrorCode.InvalidURI (which is just less specific).
    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 the tcm:Data Xml node while trying to save the item. This also applies for XmlElements that should be valid but are misspelled. Now, no error is thrown, instead the invalid XmlElement is ignored and the item will be saved if there are no validation errors. When an XmlElement that 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
  • Keyword class:

    Save
    • Before, when trying to change ParentKeywords of a localized Keyword, business rules were validated locally, and hence the specific ErrorCode 8004032F (ItemIsLocalized) was sent back. Now, this is done in a more generic way, so now for any invalid property change for a localized RepositoryLocalObject, the ErrorCode is 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 ParentKeyword or RelatedKeyword; if not, a PermissionDeniedException/ PermissionDenied (80040242) is thrown.
    • In the new API, you cannot introduce a cycle by adding a Parent Keyword. This leads to an InvalidPropertyValueException/ CircularLinkDetected.
  • MultimediaType class:

    ToXml
    Before, the tcm:Info element was located after the tcm:Data element, 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 MultimediaType always allowed View, Edit, and Delete for everyone. This does not reflect the actual allowed actions. Only administrators should be allowed to change and delete MultimediaType. In the new API, the allowed actions for View are always set to Allow, while Edit and Delete are only set to Allow for administrator-level users.
  • OrganizationalItem class:

    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.
  • ProcessDefinition class:

    Save
    There is no longer an explicit property for the first Activity; it is now assumed to be the first in the list.
  • ProcessInstance class:

    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 ItemDoesNotExist exception is thrown. You need to pass in a valid URI with the right publication ID.
  • Publication class:

    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 PublicationUrl and MultimediaUrl to empty values. Now an InvalidPropertyValueException is thrown.
    • Before, the values of PublicationUrl and MultimediaUrl were 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, an InvalidPropertyValueException is thrown.
    Delete
    • Deleting a non-existent Publication now raises an exception.
    • If a Publication has a published Taxonomy, you cannot delete that Publication: an ItemIsInUseException is thrown.
    • If a Publication has a published Structure Group, you cannot delete that Publication: an ItemIsInUseException is thrown.
    • Before, any user could delete an ApprovalStatus; now, only users with Workflow Management rights and administrators can.
  • PublicationTarget class:

    ToXml
    Previously, the tcm:Info element was located after the tcm:Data element, 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.
  • Repository class:

    WebDavUrl
    You now get a WebDAV URL on a new item, which was null before.
    Key
    The Key property 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.
  • RepositoryLocalObject class:

    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 an InvalidCastException.
    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, a PermissionDeniedException will 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).
  • Schema class:

    GetTridionWebSchemaXml
    The size element for a Schema field will not be sent to output (for all fields except XHTML and MultiTextField) if no list was specified. tcm:Size for NumberField and DataField have become non-mandatory XML elements in the cm_xml.xsd schema.
  • TargetGroup class:

    Save
    Before, a business rule checked for an incorrect value (string or empty) in KeywordCondition Value and throws an exception (NumericalOperandRequired - 8004033A). Now, the API throws a .NET serialization exception (80040000) when trying to serialize XML into a Data object.
  • TargetType class:

    AccessControlList
    Before, the API used a new permission type called TargetTypePermissions that had one PermissionType: UseTargetType. This has been changed: the right Rights.PublishManagement is 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 AccessControlList will be empty.
    ToXml
    Previously, the tcm:Info element was located after the tcm:Data element, 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.
  • Template class:

    ParameterSchema
    Before, this property could not be set to null. Now it can be, effectively removing the Parameter Schema.
  • TemplateType class: before, this class implemented the IXmlSerializable interface. Now, it no longer does.

  • TemplateTypes class: before, this class implemented the IXmlSerializable interface. Now, it no longer does.

  • TrackingKeyCondition class:

    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).
  • User class:

    constructor
    The Title property contains the value New User (localized) instead of String.Empty.
  • VersionedItem class:

    Load
    • Previously, the AllowedAction for VersionedItems had the Rollback flag not set in Allow and Deny. This is not correct, the options should be there but denied. This was fixed.
    • Before, a TcmErrorCode.AccessDenied would be thrown when an user tries to load an item and does not have the required permissions and/or rights. Now, a PermissionDeniedException is thrown which uses TcmErrorCode.PermissionDenied.
    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 PermissionDeniedException is 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, an InvalidUriException is 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> whereas GetListDeletedReferences() 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 the SubType optional attribute, which was missing.
    Rollback
    • Before, a rollback to a non-existent version resulted in an exception with ItemVersionDoesNotExist error code (8004032A). Now, the error code is ItemDoesNotExist (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 an ItemDoesNotExist exception.
  • WorkItem class:

    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 ItemDoesNotExist exception 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.