Documentation Center

Changes to the class DocumentObj 2.5

Describes the changes in the class DocumentObj25 that were made in release 2.5 of the API.

Changes to behavior

ISHObjectList no longer contains 'ISHNotFound' elements

In Web Services 2.0 an ishobject element with ishtype "ISHNotFound" is added when a given or referenced DocId cannot be found in the database.

Since an extra postprocessing step is required to check that all objects are present and to add extra ishobjects if necessary, the extra ishobject element no longer is appended.

Filtering on resolution is only applied for images

In Web Services 2.5 the filtering on resolution is only applied on images.

In Web Services 2.0 the filtering on resolution was applied for all objects because of the implicit filter on ishtype "ISHIllustration".

In Web Services 2.5 if you only want images, you must combine the filtering on the resolution with an explicit filter on ishtype "ISHIllustrations".

Behavior of the latestafterfilter keyword in the VersionNumber

The keyword latestafterfilter means that the latest version number is calculated after all filtering is applied. However, in most cases the used filtering is on one of the following fields: language, resolution, or status. For performance reasons, beginning with Web Services 2.5 the latest version after applying the filtering on language, resolution and status is calculated. Any other filtering is executed after calculating the version and does not change the version number.

Behavior of Metadata Filter operators

In Web Services 2.0 it was possible to use each filter operator on all fields independent on the data type of the field. Although it is technically possible to use the operator like on a date, the result is not always predictable. Beginning with Web Services 2.5, all filter operators on all field types is no longer supported.

DocumentObj25 cannot be used for publications

You should now use Publication20 for publications. In Web Services 2.0 it was still possible to use DocumentObj20 for publication and publication version objects.

DocumentObj25 only returns and accepts objects of type 'ISHMasterDoc', 'ISHModule', 'ISHIllustration', 'ISHLibrary' or 'ISHTemplate'.

Behavior of the "language" parameter

The language parameter is used to retrieve the language object.

In Web Services 2.0 you could provide multiple languages comma-space separated in the language parameter. Starting from Web Services 2.5 parameters can only contain multiple values if they are passed as an array or a list. So, the language parameter which is a regular string cannot contain multiple values.

For multiple languages on an image (= LanguageApplicability) this means you need to pass ONE language for retrieving the language object. Any of the languages specified on the language object, can be used to retrieve the language object. When you want to update the language object, all languages must be supplied via the DOC-LANGUAGE field in the xml metadata.

Changes to workflow methods

GetInitialStates

In Web Services 2.0, the method GetInitialStates could be used to request the initial statuses for a specific ishtype. An array with the labels of the initial statuses was returned.

Starting with Web Services 2.5 the method is removed from the DocumentObj25 class. In order to get the initial statuses you can use Settings25.GetPossibleTargetStatuses. This method uses filtering on ishtype , user role and optional from status to return a LOV ValueList XML Structure with the statuses.

GetPossibleTransitionStates

In Web Services 2.0, the method GetPossibleTransitionStates could be used to request the possible status transitions for a specific language object which was specified by logical identifier, version number and language. An array with the labels of the possible statuses was returned.

Starting with Web Services 2.5 this method is replaced by the method DocumentObj25.GetPossibleTargetStatuses that still allows you to specify the language object by logical identifier, version number and language. However, this method returns a LOV ValueList XML Structure with the statuses instead of an array with only the labels of the statuses.

In Web Services 2.5 there is an extra method DocumentObj25.GetPossibleTargetStatusesByIshLngRef that has the same functionality as the previous function but which can be used to get the possible status transition if you already have a language reference.

Changes to retrieve object methods

There are some changes concerning the methods to retrieve objects and their content.

The following table gives an overview of those methods and the changes:
DocumentObj 2.0DocumentObj 2.5Description
RetrieveObjects
  • ref string psAuthContext
  • string psDocIds
  • enum peStatusFilter
  • string psXMLMetadataFilter
  • string psXMLProductDef
  • string psXMLRequestedMetadata
  • ref string psOutXMLObjList
RetrieveObjects
  • ref string psAuthContext
  • string array pasLogicalIds
  • enum peStatusFilter
  • string psXMLMetadataFilter
  • string psXMLProductDef
  • string psXMLRequestedMetadata
  • out string psOutXMLObjList
This method retrieves the objects using the filtering on logical identifier, status and the extra filtering specified in the xml metadata filter. For those objects the requested metadata and the content is returned.
RetrievebyIshLngRef
  • ref string psAuthContext
  • string psLngRefs
  • string psXMLProductDef
  • string psXMLRequestedMetadata
  • boolean pbIncludeData
  • ref string psOutXMLObjList
RetrieveObjectsByIshLngRefs
  • ref string psAuthContext
  • Long array palLngRefs
  • string psXMLProductDef
  • string psXMLRequestedMetadata
  • out string psOutXMLObjList
This method returns the requested metadata and content for the specified language objects.
N/A
RetrieveObjectsByRevisionIds
  • ref string psAuthContext
  • String array pasRevisionIds
  • string psXMLProductDef
  • string psXMLRequestedMetadata
  • out string psOutXMLObjList

This method returns the requested metadata and content for the specified revision objects.

The requested metadata is not specific for the revision. For instance, the links on the language object are the links from the latest revision.

Changes to update methods

Each update method...
  • has an "ByIshLngRef" alternative to allow faster retrieval of the language object via the language reference instead of finding the language object based on LogicalId, Version, Language and Resolution (*)
  • has a psXMLRequiredCurrentMetadata parameter allowing extra checks on the metadata to ensure that the metadata was not changed by someone else in the meanwhile
Internally there are 2 big changes...
  • the status transition is treated as a simple field update
  • the IOnDocStore and ICustomerPlugins plugins are replaced by a new more uniform plugin mechanism
The following table gives a detailed overview of all changes in the update methods:
DocumentObj 2.0DocumentObj 2.5Remarks
Create
  • ref string psAuthContext
  • string psFolderId
  • enum peISHType
  • ref string psDocId
  • ref string psVersion
  • string psLng
  • string psResolution
  • string psXMLMetaData
  • string psEdt
  • byte[] pbData
Create
  • ref string psAuthContext
  • long plFolderRef
  • string psIshType
  • ref string psLogicalId
  • ref string psVersion
  • string psLanguage
  • string psResolution
  • string psXMLMetadata
  • string psEdt
  • byte[] pbData

There are 2 changes in the parameters

  • The folder reference must be supplied as a number, but can be 0 or negative when you are adding a new version or language to an existing logical object
  • The ISHType is no longer an enumeration but a string which can contain the same string representations of the enumeration values: ISHMasterDoc, ISHModule, ISHIllustration, ISHLibrary and ISHTemplate
UpdateUpdateNo changes
N/AUpdateByIshLngRef(*)
SetMetaDataSetMetadataNo changes
N/ASetMetadataByIshLngRef(*)
N/ASetMetadataByIshLngRefs

This new method allows you to update multiple fields for multiple objects and replaces the Workflow20.PerformAction method which could only be used to update the status for multiple language objects

Some remarks:
  • The multiple objects are handled one-by-one within a new transaction.
  • If one of the updates fails, the exception is reported but the method continues with the next object.
  • Background tasks are also triggered for each object separately. So, they are not grouped!
CheckIn
  • ref string psAuthContext
  • string psDocID
  • string psVersion
  • string psLng
  • string psResolution
  • string psXMLMetadata
  • string psEdt
  • byte[] pbData
CheckIn
  • ref string psAuthContext
  • string psLogicalId
  • string psVersion
  • string psLanguage
  • string psResolution
  • string psXMLMetadata
  • string psXMLRequiredCurrentMetadata
  • string psEdt
  • byte[] pbData
New parameter psXMLRequiredCurrentMetadata
N/ACheckInByIshLngRef(*)
CheckOut
  • ref string psAuthContext
  • string psDocID
  • ref string psVersion
  • string psLng
  • string psResolution
  • string psXMLRequestedMetadata
  • ref string psOutXMLObjList
CheckOut
  • ref string psAuthContext
  • string psLogicalId
  • ref string psVersion
  • string psLanguage
  • string psResolution
  • string psXMLRequiredCurrentMetadata
  • string psXMLRequestedMetadata
  • out string psOutXMLObjList

There are 2 changes in the parameters

  • New parameter psXMLRequiredCurrentMetadata
  • The parameter psOutXMLObjList is an out parameter and not an in/out parameter
N/ACheckOutByIshLngRef(*)
UndoCheckOut
  • ref string psAuthContext
  • string psDocID
  • string psVersion
  • string psLng
  • string psResolution
UndoCheckOut
  • ref string psAuthContext
  • string psDocID
  • string psVersion
  • string psLng
  • string psResolution
  • string psXMLRequiredCurrentMetadata
New parameter psXMLRequiredCurrentMetadata
N/AUndoCheckOutByIshLngRef(*)
CreateOrUpdateN/AThe CreateOrUpdate method is not ported, but can be replaced by the new TryGetMetadata method followed by a Create or Update depending on the result.
TerminologyUpdateN/AThis was not a standard function and will not be replaced
DeleteDeleteRules that determine when the object can be deleted were updated. For the complete set of new rules, please refer to the topic DocumentObject25.Delete
AddShortcutN/A

The AddShortcut is moved to the Folder 2.5 class and replaced by Folder25.AddShortcuts which will add multiple objects to the same reference folder.

Each logical object is added to the reference folder in a new transaction. If one of the actions fails, the exception is reported but the method will continue with the next object. If the object was already referenced in the folder, the object is skipped silently without throwing an exception.

RemoveShortcutN/A

The RemoveShortcut is moved to the Folder 2.5 class and replaced by Folder25.RemoveShortcut which will remove multiple objects from the same reference folder.

Each logical object is removed from the reference folder in a new transaction. If one of the actions fails, the exception is reported but the method will continue with the next object. If the object was not referenced in the folder, the object is skipped silently without throwing an exception.

MoveN/A

The Move is moved to the Folder 2.5 class and replaced by Folder25.MoveObjects which will move multiple objects to the same folder.

Each logical object is moved in a new transaction. If one of the actions fails, the exception is reported but the method will continue with the next object.

Other changes

StartTranslationMgmt

In Web Services 2.0, the method StartTranslationMgmt could be used to start the translation management process.

Starting with Web Services 2.5 the method is removed from the DocumentObj25 class. There is no public method provided as a replacement. Internally, the new (internal) method TranslationManagement25.CreateTranslationFromVersion is used.