Documentation Center

API changes

The web services API changes.

General

The web services API are made available for integration using the Windows Communication Foundation (WCF), resulting in SOAP 1.2 services like /ISHWS/WCF/API25/Application.svc capable of supporting claims-based authentication. The deprecated endpoints like /ISHWS/Application25.asmx relying on proprietary authentication are still present in this release.

Typically users write their first code based on a label (e.g. statusIn translation). If you want to change the label later on, you have to adapt a lot of code. Now all API25 methods accept element names (e.g. stable id for status VSTATUSINTRANSLATION) as input for parameters making code independent from label renames. This is valid for all ListOfValue based entries like for example: language, resolution, outputformat, user, usergroup, userrole, etc. [TS-6473]

The FISHSTATUSTYPE calculation is no longer done asynchronously, avoiding a lot of background task Translation Managements to spin up. The FISHSTATUSTYPE field holds shortcut values to identify if your object is either draft (10), released (20), out-of-date (30), etc.

Comma Space (, ) is now allowed in string fields. With the changed back-end, the system can now easily make the difference between a multi-value field where comma-space is the separator, and a regular string field. [TS-5104]

In the version algorithm, the build number system changed. We will now continuously increase the build number. For example version 10.0.312.5 has build number 312 and can be read as March 12 from the year 2013. Version 10.0.1629.5 has build number 1629 and can be read as 29 April 2014 (every multiple of 1200 indicates a year). [TS-6951]

We introduced full stack write functions for classes DocumentObj25 and PublicationOutput25 in 11.0.0. These optimized versions got a considerable performance improvement because of a new architecture and the rewrite of the IOnDocStore system, resulting in the IWrite plugins.

This now allowed us to introduce a considerable read performance improvement on all API 25 classes like for exampleDocumentObj25 and PublicationOutput25 - available since 11.0.1. The boost is visible in metadata field retrieval areas such as:
  • Publication Manager, when opening a publication;
  • Authoring Bridge, when loading the content of a folder;
  • Baseline operations like autocomplete and freeze;
  • API25 based customization.

Most optimizations were in the data source layer. Result set handling of queries that return 500+ rows received a major boost. Some loops and lists were optimized with dictionary lookups for bigger amounts of data. Also the logging engine setup changed: it now relies more on static instances. [TS-8889]

MetadataBinding25

API consumers don’t know if a field is metadata bounded to an issue tracker, or a wiki, or a taxonomy system, or some ontology system. The following API functions have been added to let you build the controls in a Properties screen. These endpoints allow generic handling of data coming from metadata bounded fields:

  • MetadataBinding25.ResolveIds resolves the tag IDs for each field into labels/descriptions.
  • MetadataBinding25.RetrieveTags retrieves a list of tags for the specified field and applies filter logic like hierarchical structures.
  • MetadataBinding25.RetrieveTagStructure retrieves a hierarchy of tags – so including relationships – for the specified field and applies filter logic.
  • MetadataBinding25.Validate [internal] validates the tag IDs of the specified fields against the filter field values.

DocumentObj20, DocumentObj25 and PubliciationOutput25

All read functions, like for example DocumentObj25.RetrieveMetadata, let you retrieve the labels of metadata bounded fields.
ishvaluetypepsXMLRequestedMetadatapsOutXMLObjList
(default)<ishfields><ishfield name="FCITIES" level="lng"/></ishfields><ishobjects><ishobject ...=""><ishfields><ishfield name="FCITIES"level="lng">Moscow, Copenhagen, Brussels</ishfield></ishfields></ishobject></ishobjects>
value<ishfields><ishfield name="FCITIES" level="lng" ishvaluetype="value" /></ishfields><ishobjects><ishobject ...=""><ishfields><ishfield name="FCITIES" level="lng" ishvaluetype="value">Moscow, Copenhagen, Brussels</ishfield></ishfields></ishobject></ishobjects>
id<ishfields><ishfield name="FCITIES" level="lng" ishvaluetype="id" /></ishfields><ishobjects><ishobject ...=""><ishfields><ishfield name="FCITIES" level="lng" ishvaluetype="id">524901, 2618425, 2800866</ishfield></ishfields></ishobject></ishobjects>
element<ishfields><ishfield name="FCITIES" level="lng" ishvaluetype="element" /></ishfields><ishobjects><ishobject ...=""><ishfields><ishfield name="FCITIES" level="lng" ishvaluetype="element">524901, 2618425, 2800866</ishfield></ishfields></ishobject></ishobjects>

All find functions, like for example DocumentObj25.Find, require the identifier to be passed. The actual value or label is not saved in the repository and is always looked up just-in-time in the metadata bounded source repository.

All write functions, like for example DocumentObj25.SetMetadata, require the identifier to be passed. The actual value or label is not saved in the repository. Furthermore the label is not guaranteed to be unique enough to allow lookup in the metadata bounded source repository.

PublicationOutput25.Find and DocumentObj25.Find with a filter on metadata using @ishoperator like now can filter on values over 255 characters in length. The earlier rootword-length filter limitation has been removed. Performance has been improved for these functions as they take the Status Filter (FISHSTATUSTYPE) restriction into account from the start. [SRQ-3393|TS-9866]

We fine-tuned several behaviors, most notably:
  • When submitting a blob as non-administrator, you were blocked if the object was released. Now you are blocked only if the object is part of a released publication output with the current language.
  • When updating the status, you must select a valid status transition. Moreover, if the object is part of a frozen baseline, you could not move from released back to a draft status. Now you can do both actions as long as the object is not part of a released publication output, making it easier to work statuses on translated objects.

DocumentObj20.StartTranslationMgmt is obsolete and can be replaced by TranslationManagement25.CreateTranslationFromVersion [internal].

DocumentObj20.TerminologyUpdate is obsolete.

EDT25

All documents and publications in the database are linked with an Electronic Document Type (EDT) which specifies the file extension and the mime type of the document. We introduce an API which allows remote management, aligns with OutputFormat, User, UserGroup, ...

  • EDT25.Create
  • EDT25.GetMetadata (single)
  • EDT25.RetrieveMetadata (plural)
  • EDT25.Update
  • EDT25.Delete
  • EDT25.Find

EDT25.GetList is deprecated and should be replaced by EDT25.Find which matches our naming convention.