Integration Using External Attribute Types

In general, value list values are statically defined in the iKnowBase metadata repository. However, it is sometimes useful to have entirely dynamic value lists. For this, iKnowBase supports attribute types of type EXTERNAL. You can configure and maintain these attribute types in the Metadata Management tool available in the Development Studio.

External attribute types enable you to tag iKnowBase information objects with metadata which are defined outside of iKnowBase, e.g. in another system. These attributes can be used as ordinary iKnowBase attributes in Viewers, Forms and Search Sources. They require an external source, which contains functions to support lookups and value lists.

For an external attribute type you must define which external source API to use. You must implement this API to contain given functions for retrieval of information from the external data source.

You can add the external attribute type for a Form component, to enable the end user to tag iKnowBase information objects with this attribute. On the Value tab of the Edit pane for the Form component, you can specify which value list to use for the attribute as well as the default value. The API function get_list_functions is used to populate the dropdown box for value lists, and the function get_values is used to populate the list of possible default values.

You can add the external attribute type to a Viewer or a Search source, to enable the end user to view and search for information objects tagged with this metadata.

External Source API

Before you can create an external attribute type you must implement the external source API for the external data source. The API is implemented as a plsql-package with the following signature:

package my_external_source IS

   function get_value (p_value_id in varchar2) return varchar2;

   function get_values return external_api_table;

   function get_list_functions  return external_api_table
   
   function get_changes (
     p_from_date date, 
     p_to_date in date
   ) return external_api_table;
   
   procedure delete_external_attribute;

end;

table(ikbPropertyTable).
|_. Method          |_. Description|
|get_value          |Retrieves the name for a given item.|
|get_values         |Retrieves a set of values (id and name). You can create several similar functions if you need subsets of the values.|
|get_list_functions |Returns all get_values functions. The list is used when the end user selects between subsets.|
|get_changes        |Returns all changed values (id and name) within the given period. This function is used by the nightly job that re-indexes the iknowbase documents, to update the labels of an external attribute, which may have changed since the last indexing.|
|delete_external_attribute  |Used for deletion of metadata which no longer exist in the external data source. You must run this function from a trigger or a batch job defined at the external data source.  |

Example: Topic Map API

CREATE OR REPLACE PACKAGE topic_map_api

/**
 * Example package used by a external attribute. The functions
 * get_value, get_changes and get_list_functions have to be included 
 * the package; otherwise external attributes will not work properly.
 */

AS
   /**
    * Get the description/name for a given external attribute.
    */
   FUNCTION get_value (p_value_id IN VARCHAR2)
      RETURN VARCHAR2;

   /**
    * Gets a set of values (id and name). You can create several
    * similar functions if you need subsets of the values.
    */
   FUNCTION get_values
      RETURN external_api_table;

   /**
    * Returns all 'get_values' functions. The list is used when 
    * the user selects between subsets.
    */
   FUNCTION get_list_functions
      RETURN external_api_table;

   /**
    * Returns all 'changed' values to the nightly job that reindexes
    * the XML_DATA-field. The purpose is to update the labels in XML_DATA
    * where the label has changed in the external system.
    */

   FUNCTION get_changes (p_from_date IN DATE DEFAULT NULL, p_to_date IN DATE)
      RETURN external_api_table;

   /**
    * Internal function used when external attribute is deleted in 
    * the source system. Returns OK. <message> or ERROR:<error msg> 
    */
   Function Delete_External_Attribute (p_external_value in varchar2) return varchar2;

END topic_map_api;
/

CREATE OR REPLACE PACKAGE BODY topic_map_api
AS

   /**
    * Custom implementation of get_value. 
    * Returns the label/description of an external attribute value.
    */
   FUNCTION get_value (p_value_id IN VARCHAR2)
      RETURN VARCHAR2
   IS
      l_return_value   VARCHAR2 (200);
   BEGIN
      SELECT basename
        INTO l_return_value
        FROM ikbtm.ikb_tm_topic
       WHERE ID = TO_NUMBER (p_value_id);

      RETURN l_return_value;
   EXCEPTION
      WHEN NO_DATA_FOUND
      THEN
         RETURN NULL;
   END;

   /**
    * Custom implementation of get_values. Returns all or a 
    * subset of values from the external source.
    */
   FUNCTION get_values
      RETURN external_api_table
   IS
      CURSOR c1
      IS
         SELECT   external_api_rec (ID, basename)
             FROM ikbtm.ikb_tm_topic
         ORDER BY basename;

      l_values   external_api_table := external_api_table ();
   BEGIN
      OPEN c1;

      FETCH c1
      BULK COLLECT INTO l_values;

      CLOSE c1;

      RETURN l_values;
   END;

   /**
    * Custom impelemtation of get_changes. Returns all or a
    * subset of values that have changed since the last time
    * the indexing job ran.
    */
   FUNCTION get_changes (
      p_from_date IN DATE DEFAULT NULL, 
      p_to_date IN DATE
   )
      RETURN external_api_table
   IS
      CURSOR c1
      IS
         SELECT   external_api_rec (ID, basename)
             FROM ikbtm.ikb_tm_topic
         ORDER BY basename;

      l_values   external_api_table := external_api_table ();
   BEGIN
      OPEN c1;

      FETCH c1
      BULK COLLECT INTO l_values;

      CLOSE c1;

      RETURN l_values;
   END;

   /**
    * Custom implementation of Delete_External_Attribute
    */
   FUNCTION Delete_External_Attribute (
     p_external_value in varchar2
   ) 
     RETURN varchar2
   IS 	
   BEGIN
     RETURN ikb_pck_document.DeleteExternalAttribute(
        p_site_id => 10,
        p_api_name => 'ikb.topic_map_api',
        p_external_value => p_external_value
      );
	END;

   /**
    * Custom impelemtation of get_list_function. Returns all instances
    * of get_values. Each subset must be represented with its own 
    * get_values-function.
    */
   FUNCTION get_list_functions
      RETURN external_api_table
   IS
      l_list_functions   external_api_table := external_api_table ();
   BEGIN
      l_list_functions.EXTEND;
      l_list_functions (1) :=
             external_api_rec ('get_values', 'Hent alle verdier');

      /* If more than one, just add like this
      l_list_functions.EXTEND;
      l_list_functions (2) :=
         external_api_rec ('get_values2',
                           'Hent alle verdier for topictype XX'
                          );
      */

      RETURN l_list_functions;
   END;
END topic_map_api;
/