Lookup, concordance add/update entry
Warning
The following functionality is deprecated and will be removed in a future version.
The lookup related services provide the following operations:
- Lookup in a TM: performs a lookup in a single TM searching for similar segments and returns the matches with the stored translation.
- Concordance: performs a free-text search in the TM and returns the matches.
- Add/update entry in the TM: add a new entry (segment pair) to the TM or update an existing entry.
These functions use Xml documents for describing the lookup data, the returned match results and the segment content. These Xml documents are transported as strings through the API functions. The Xml documents are described by an XSD scheme detailed below. Every Xml document input is validated according to this scheme, and every result returned by the API in Xml form is guaranteed to conform to this scheme.
These functions require an existing and valid user session to the API in the name of a user who exists in the memoQ server. The permissions associated with the TM must allow the user access.
A special license "MemoQServerWS-TM" is required in the memoQ server to access these functions. If the license is not present or not valid, the service returns a specific error.
Data schema
The XSD scheme below describes the expected input format of the Xml documents and the format of the returned results. The segment content scheme is partially derived from the TMX 1.4b specification, but this schema allows a subset of what TMX allows in the TU elements.
Please note that a single scheme describes the following types of documents, but at all times only a single document is contained in the Xml strings (the XSD scheme verifies this too):
- Lookup request (root element: mq:lookup, input of function LookupSegment);
- Lookup results (root element: mq:fuzzy-results, output of function LookupSegment);
- Concordance results (root element: mq:concordance-results, output of function Concordance);
- Add/update entry (root element: mq:item-to-store, input of function AddOrUpdateEntry).
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns="http://kilgray.com/memoqservices/2007"
xmlns:mq="http://kilgray.com/memoqservices/2007"
targetNamespace="http://kilgray.com/memoqservices/2007"
elementFormDefault="qualified">
<!-- Lookup request -->
<xs:complexType name="CT_LookupRequestItem">
<xs:sequence>
<xs:element name="context" minOccurs="0" maxOccurs="1" type="xs:string" />
<xs:element name="context-pre" type="CT_Seg" minOccurs="0" maxOccurs="1" />
<xs:element name="context-post" type="CT_Seg" minOccurs="0" maxOccurs="1" />
<xs:element name="seg" type="CT_Seg" minOccurs="1" maxOccurs="1"
form="unqualified" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="CT_LookupRequestRoot">
<xs:sequence>
<xs:element name="lookup-item" type="CT_LookupRequestItem"
minOccurs="1" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
<xs:element name="lookup" type="CT_LookupRequestRoot" />
<!-- Lookup results -->
<xs:complexType name="CT_LookupResultItem">
<xs:sequence>
<xs:element name="tu" type="CT_Tu" minOccurs="0" maxOccurs="unbounded"
form="unqualified" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="CT_LookupResultRoot">
<xs:sequence>
<xs:element name="fuzzy-result-item" type="CT_LookupResultItem"
minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
<xs:element name="fuzzy-results" type="CT_LookupResultRoot" />
<!-- Concordance results -->
<xs:complexType name="CT_ConcordanceItemRange">
<xs:attribute name="position" type="xs:int" form="unqualified" use="required" />
<xs:attribute name="length" type="xs:int" form="unqualified" use="required" />
</xs:complexType>
<xs:complexType name="CT_ConcordanceItem">
<xs:sequence>
<xs:element name="concordance-range" type="CT_ConcordanceItemRange"
minOccurs="1" maxOccurs="unbounded" />
<xs:element name="tu" type="CT_Tu" minOccurs="1" maxOccurs="1"
form="unqualified" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="CT_ConcordanceResultRoot">
<xs:sequence>
<xs:element name="concordance-item" type="CT_ConcordanceItem"
minOccurs="0" maxOccurs="unbounded" />
</xs:sequence>
<xs:attribute name="totalHitCount" type="xs:int" form="unqualified"
use="required" />
<xs:attribute name="searchExpressionProblem" type="xs:string"
form="unqualified" use="optional" />
</xs:complexType>
<xs:element name="concordance-results" type="CT_ConcordanceResultRoot" />
<!-- Item to store in TM -->
<xs:complexType name="CT_ItemToStoreRoot">
<xs:sequence>
<xs:element name="context" minOccurs="0" maxOccurs="1" type="xs:string" />
<xs:element name="context-pre" type="CT_Seg" minOccurs="0" maxOccurs="1" />
<xs:element name="context-post" type="CT_Seg" minOccurs="0" maxOccurs="1" />
<xs:element name="seg-source" type="CT_Seg" minOccurs="1" maxOccurs="1" />
<xs:element name="seg-target" type="CT_Seg" minOccurs="1" maxOccurs="1" />
<xs:element name="prop" type="CT_TuProp" minOccurs="0" maxOccurs="unbounded"
form="unqualified" />
</xs:sequence>
</xs:complexType>
<xs:element name="item-to-store" type="CT_ItemToStoreRoot" />
<!-- TU and TUV -->
<xs:complexType name="CT_Tuv">
<xs:sequence>
<xs:element name="seg" type="CT_Seg" form="unqualified" />
</xs:sequence>
</xs:complexType>
<xs:complexType name="CT_TuProp" mixed="true">
<xs:attribute name="type" use="required" form="unqualified" />
</xs:complexType>
<xs:complexType name="CT_Tu">
<xs:sequence>
<xs:element name="prop" type="CT_TuProp" minOccurs="0" maxOccurs="unbounded"
form="unqualified" />
<xs:element name="tuv" type="CT_Tuv" minOccurs="2" maxOccurs="2"
form="unqualified" />
</xs:sequence>
<xs:attribute name="tuid" form="unqualified" />
<xs:attribute name="creationdate" form="unqualified" />
<xs:attribute name="creationid" form="unqualified" />
<xs:attribute name="changedate" form="unqualified" />
<xs:attribute name="changeid" form="unqualified" />
<xs:anyAttribute></xs:anyAttribute>
</xs:complexType>
<!-- Segment content -->
<xs:complexType mixed="true" name="CT_Seg">
<xs:choice minOccurs="0" maxOccurs="unbounded">
<xs:group ref="G_Seg_Bpt"></xs:group>
<xs:group ref="G_Seg_Ept"></xs:group>
<xs:group ref="G_Seg_It"></xs:group>
<xs:group ref="G_Seg_Ph"></xs:group>
</xs:choice>
</xs:complexType>
<xs:group name="G_Seg_Bpt">
<xs:sequence>
<xs:element name="bpt" form="unqualified">
<xs:complexType mixed="true">
<xs:attribute name="i" use="required" type="xs:int" form="unqualified" />
<xs:attribute name="type" use="required" form="unqualified">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="bold"></xs:enumeration>
<xs:enumeration value="italic"></xs:enumeration>
<xs:enumeration value="ulined"></xs:enumeration>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:group>
<xs:group name="G_Seg_Ept">
<xs:sequence>
<xs:element name="ept" form="unqualified">
<xs:complexType mixed="true">
<xs:attribute name="i" use="required" type="xs:int" form="unqualified" />
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:group>
<xs:group name="G_Seg_It">
<xs:sequence>
<xs:element name="it" form="unqualified">
<xs:complexType mixed="true">
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:group>
<xs:group name="G_Seg_Ph">
<xs:sequence>
<xs:element name="ph" form="unqualified">
<xs:complexType mixed="true">
<xs:attribute name="type" form="unqualified" />
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:group>
</xs:schema>
Reported errors
Important note: When using Lookup, concordance add/update entry make sure to enable advanced error handling mode (see 2.5.1 Error handling configuration). The functions above report various types of errors. Besides the generally used UnexpectedFault and GenericFault several specific faults are used. There is one special: TMFault. It has an ErrorCode member so that the caller can differentiate between different types of TM related errors. Using older WS technologies it is difficult to access the ErrorCode: you can check the fault code instead, which has the same value as the TMFault.ErrorCode. Possible fault types, fault code values with their fault message are the following:
| Fault type | Fault code (same as ErrorCode in case of TMFault) | Fault message |
|---|---|---|
| NoLicenseFault | NoLicense | No valid license is available. (remark: using this API requires a special license) |
| UnauthorizedAccessFault | UnauthorizedAccess | Access denied. (remark: the specified user (memoQ user) has no rights to perform the request operation.) |
| InvalidSessionIdFault | InvalidSessionId | The session ID is invalid (not logged in or expired). |
| RequestXmlFormatFault | RequestXmlFormatError | The provided XML is not valid against schema. |
| TMFault | TM+DoesNotExists | The TM does not exist or is not published on the server. |
| TMFault | TM+NoReverseLookupIsSupported | Reverse lookup is not supported by the TM. |
| TMFault | TM+Busy | The TM is currently busy (exclusively used by an operation). |
| TMFault | TM+Readonly | The TM is read only. |
| TMFault | TM+Corrupt | The TM is corrupt, it has to be repaired. |
| GenericFault | Generic | The message of the original exception is used as fault message. |
| UnexpectedFault | Unexpected | The message of the original exception is used as fault message. |
Example code and Xml
The "memoQ services test client" bundled with this documentation contains example code on how to use these services. The code also contains simple examples of the Xml documents expected as input. These documents are assembled as a string in the example, however there are various other ways of creating Xml documents and exporting them as a single string. In .NET for example one could use the XmlWriter class to create the document.