Integration IDs

From KnowledgeTree Community

To assist software integrators, documents may also be referenced using Integration IDs.

Each document may have a custom integration id associated with it. This is provided as additional information to assist system integrators and is not used by KnowledgeTree.

oem_no database field

In the database, a oem_no field has been added to the documents table. It is stored as a varchar(255).

assigning the integration id to a document

Integrators are most likely to access KnowledgeTree via web services, and this is the only way the integration id can be maintained at this stage.

To assign an integration id to a document, the update_metadata web service function must be called.

This function is also called indirectly when calling the following web service functions:

checkin_base64_document_with_metadata
checkin_document_with_metadata
add_base64_document_with_metadata
add_document_with_metadata

This means the integration id may be assigned to a document by either setting it expicitly using the update function, or when checking in or adding a document.

illustrative example

The update_metadata is defined as follows:

update_document_metadata(session_id : string, document_id : integer, metadata : kt_metadata_fieldsets, sysdata : kt_sysdata) : kt_document_detail

kt_sysdata is an array of kt_sysdata_items composed of two fields, name and value.

Example psuedocode:

session_id = 'hjlfhdsadlkfhsakjfdsa'
document_id = 1
metadata = []
sysdata = [ [ name='oem_no', value='inv001' ] ]
result = update_document_metadata(session_id, document_id, metadata, sysdata) 
if (result.status_code != 0) 
  throw new Exception('could not update the integration id on the document with id: ' + document_id + ' because: ' + result.message + '(' + result.status_code + ')');

ensuring uniqueness of the integration id

As illustrated above, oem_no is the field that must be specified as part of the system metadata to be set on the document.

unique_oem_no is another field that may be used. It is in essence the same as oem_no, except that it will update the database setting any other occurances of oem_no to be null for other documents.

finding documents based on integration ids

To search for documents based on integration id, the function get_documents_by_oem_no has been provided.

get_documents_by_oem_no(session_id : string, oem_no : string, detail : string) : kt_document_collection_response

kt_document_collection_response provides a collection of kt_document_detail records.

session_id = 'hjlfhdsadlkfhsakjfdsa'
oem_no = 'inv001'
result = get_documents_by_oem_no(session_id, oem_no, "") 

if (result.status_code != 0) 
  throw new Exception('problem searching for document based on integration id: ' + result.message + '(' + result.status_code + ')');

if (result.collection.count == 0) 
  throw new Exception('could not find any documents matching the integration id: ' + oem_no);

print result.collection[0].title

Notice the detail parameter is sent as an empty string. This parameter is passed to the get_document_detail function and is used to indicate how much document information must be returned. This string may include the characters L, T, M, V,H corresponding to links, workflow transitions, metadata, version history and transaction history.

searching using the advanced search

V3.5.2 is the development tree where this functionality was initially developed. The advanced search allows a KnowledgeTree user to search by specifying the integration id in queries including other search fields.

backporting to v3.4.x

It should be possible to get the functionality working on a V3.4.x installation.

You will need to do the following:

copy the ktapi folder to the V3.4.x installation
copy to ktwebservice folder to the V3.4.x installation
apply the following SQL to the 3.4.x database: ALTER TABLE documents ADD oem_no varchar(255)

Note that it is possible for some other issues to exist as there are considerable changes from the V3.4.x to the V3.5.x code bases.

The advanced search will not provide search capabilities at this stage as the search engine has been changed considerably from V3.5.2.

Bookmark this page: