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.0anishobjectelement withishtype"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
ishobjectelement no longer is appended. - Filtering on resolution is only applied for images
-
In
Web Services 2.5the filtering on resolution is only applied on images.In
Web Services 2.0the filtering on resolution was applied for all objects because of the implicit filter onishtype"ISHIllustration".In
Web Services 2.5if you only want images, you must combine the filtering on the resolution with an explicit filter onishtype"ISHIllustrations". - Behavior of the latestafterfilter keyword in the VersionNumber
-
The keyword
latestafterfiltermeans 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 withWeb Services 2.5the 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.0it 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 withWeb Services 2.5, all filter operators on all field types is no longer supported. - DocumentObj25 cannot be used for publications
-
You should now use
Publication20for publications. InWeb Services 2.0it was still possible to use DocumentObj20 for publication and publication version objects.DocumentObj25only returns and accepts objects of type 'ISHMasterDoc', 'ISHModule', 'ISHIllustration', 'ISHLibrary' or 'ISHTemplate'. - Behavior of the "language" parameter
-
The
languageparameter is used to retrieve the language object.In
Web Services 2.0you could provide multiple languages comma-space separated in thelanguageparameter. Starting fromWeb Services 2.5parameters can only contain multiple values if they are passed as an array or a list. So, thelanguageparameter 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-LANGUAGEfield in the xml metadata.
Changes to workflow methods
- GetInitialStates
-
In
Web Services 2.0, the methodGetInitialStatescould be used to request the initial statuses for a specificishtype. An array with the labels of the initial statuses was returned.Starting with
Web Services 2.5the method is removed from the DocumentObj25 class. In order to get the initial statuses you can use Settings25.GetPossibleTargetStatuses. This method uses filtering onishtype,user roleand optionalfrom statusto return a LOV ValueList XML Structure with the statuses. - GetPossibleTransitionStates
-
In
Web Services 2.0, the methodGetPossibleTransitionStatescould be used to request the possible status transitions for a specificlanguage objectwhich 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.5this 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.5there 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 alanguage reference.
Changes to retrieve object methods
There are some changes concerning the methods to retrieve objects and their content.
| DocumentObj 2.0 | DocumentObj 2.5 | Description |
|---|---|---|
|
RetrieveObjects
|
RetrieveObjects
| 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
|
RetrieveObjectsByIshLngRefs
| This method returns the requested metadata and content for the specified language objects. |
| N/A |
RetrieveObjectsByRevisionIds
| 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
- 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
psXMLRequiredCurrentMetadataparameter allowing extra checks on the metadata to ensure that the metadata was not changed by someone else in the meanwhile
- the status transition is treated as a simple field update
- the IOnDocStore and ICustomerPlugins plugins are replaced by a new more uniform plugin mechanism
| DocumentObj 2.0 | DocumentObj 2.5 | Remarks |
|---|---|---|
|
Create
|
Create
| There are 2 changes in the parameters
|
| Update | Update | No changes |
| N/A | UpdateByIshLngRef | (*) |
| SetMetaData | SetMetadata | No changes |
| N/A | SetMetadataByIshLngRef | (*) |
| N/A | SetMetadataByIshLngRefs | This new method allows you to update multiple fields for multiple objects and replaces the
Some remarks:
|
|
CheckIn
|
CheckIn
| New parameter psXMLRequiredCurrentMetadata |
| N/A | CheckInByIshLngRef | (*) |
|
CheckOut
|
CheckOut
| There are 2 changes in the parameters
|
| N/A | CheckOutByIshLngRef | (*) |
|
UndoCheckOut
|
UndoCheckOut
| New parameter psXMLRequiredCurrentMetadata |
| N/A | UndoCheckOutByIshLngRef | (*) |
| CreateOrUpdate | N/A | The CreateOrUpdate method is not ported, but can be replaced by the new TryGetMetadata method followed by a Create or Update depending on the result. |
| TerminologyUpdate | N/A | This was not a standard function and will not be replaced |
| Delete | Delete | The rules have been updated to determine how and when an object can be deleted. For the complete set of new rules, please refer to the topic DocumentObject25.Delete |
| AddShortcut | N/A | The 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. |
| RemoveShortcut | N/A | The 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. |
| Move | N/A | The 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. |