Documentation Center

Changes to the class PublicationOutput 2.5

Describes the changes in the class PublicationOutput25 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 LogicalId 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 is no longer appended.

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 use PublicationOutput25 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'.

There is no Publication25.asmx

All methods to access all levels of the publication objects can be found in PublicationOutput25.

In Web Services 2.0 it was not possible to get the metadata of the lng level using the Publication20 methods and it was not possible to get only the metadata of publication or publication version object using the PublicationOutput20 methods.

PublicationOutput25 is similar to DocumentObj25. Depending on the given parameters and the requested metadata the correct level is returned.

Changes to the methods getting the publish report

Only methods using IshLngRef

In Web Services 2.0, there was a GetReport method which allowed you to get the report when you knew LogicalId, Version, Language combination and Output format. In Web Services 2.5 there are only "ByIshLngRef" methods remaining.

Get the report in small chunks

In Web Services 2.0, the GetReportByIshLngRef method immediately returned the full publish report as a string. If the publish report was very big, sending the large xml over web services could give issues (e.g. timeout, maximum response size,...).

In order to avoid those issues the method "GetReportByIshLngRef" is replaced by a combination of 2 methods which allow retrieving the publish report in small chunks:
  • First use PublicationOutput25.GetPublishReportInfoByIshLngRef to retrieve the reference of the current publish report (IshPublishReportRef) and some information like the size of the report
  • Then use that information to retrieve the publish report in small chunks using PublicationOutput25.GetNextPublishReportChunkByIshLngRef

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 combination and Output format
  • has a psXMLRequiredCurrentMetadata parameter allowing extra checks on the metadata to ensure that the metadata was not changed by someone else in the meanwhile
The following table gives a detailed overview of all changes in the update methods:
PublicationOutput 2.5Remarks
Publication20.Create
  • ref string psAuthContext
  • string psFolderId
  • ref string psDocId
  • ref string psVersion
  • string psXMLMetaData
Create
  • ref string psAuthContext
  • long plFolderRef
  • ref string psLogicalId
  • ref string psVersion
  • string psOutputFormat
  • string psLanguageCombination
  • string psXMLMetadata
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
Publication20.CopyN/AThe Copy method is deprecated, but can be replaced by a Baseline.Copy call followed by a PublicationOutput.Create call.
Publication20.DeleteDelete(*)
Publication20.SetMetaDataSetMetadataNo changes

PublicationOutput20.Cancel

PublicationOutput20.CancelByIshLngRef

N/A
The Cancel methods are deprecated, but can be replaced by a SetMetadata call with:
<ishfield name='FISHPUBSTATUS' level='lng' ishvaluetype='element'>
VPUBSTATUSPUBLISHINGCANCELLED
</ishfield>
PublicationOutput20.Create
  • string psAuthContext
  • string psDocId
  • ref string psVersion
  • string psOutputFormat
  • string psLngCombination
  • string psXMLMetaData
Create
  • ref string psAuthContext
  • long plFolderRef
  • ref string psLogicalId
  • ref string psVersion
  • string psOutputFormat
  • string psLanguageCombination
  • string psXMLMetadata

There are some changes in the parameters which are all related to the fact that the method can be used to create the logical and/or version level

  • 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 LogicalId is an in/out parameter which will return a new element name when creating a new logical object without specifying the LogicalId
  • The Version is an in/out parameter which will return the version number when supplying the keywords "New" or "Latest"
PublicationOutput20.DeleteDelete(*)
PublicationOutput20.DeleteByIshLngRefDeleteByIshLngRef(*)

PublicationOutput20.Publish

PublicationOutput20.PublishByIshLngRef

N/A
The Publish methods are deprecated, but can be replaced by a SetMetadata call with:
<ishfield name='FISHPUBSTATUS' level='lng' ishvaluetype='element'>
VPUBSTATUSPUBLISHPENDING
</ishfield>
Since the SetMetadata call is not returning any metadata, you must do a GetMetaData call after the SetMetadata call to retrieve the EventId:
<ishfield name='FISHEVENTID' level='lng'/>

PublicationOutput25.Release

PublicationOutput25.ReleaseByIshLngRef

N/A
The Release methods are deprecated, but can be replaced by a Baseline.Freeze (if the baseline was not frozen yet) followed by a SetMetadata call with:
<ishfield name='FISHPUBSTATUS' level='lng' ishvaluetype='element'>
VPUBSTATUSRELEASED
</ishfield>
SetMetaDataSetMetadataThe parameters psXMLMetadata and psXMLRequiredCurrentMetadata are switch in order.
SetMetaDataByIshLngRefSetMetadataByIshLngRefThe parameters psXMLMetadata and psXMLRequiredCurrentMetadata are switch in order.
N/ASetMetadataByIshLngRefs

This new method allows you to update multiple fields for multiple 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!
DocumentObj20.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.

DocumentObj20.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.

DocumentObj20.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.