Instant Server

The iKnowBase Instant Server is the web endpoint for real time asynchronous messaging.

In addition to the JavaScript API, see Javascript library > iKnowBase.Instant in the iKnowBase API Reference, which supports both publish and consume, the following APIs are available for publishing messages.

HTTP API

The HTTP API supports publishing to topics and is an easy way of publishing messages for HTTP clients when there is no need for subscribing to and receiving messages.

The HTTP API v1 has the following endpoints:

NOTE: For the old method “sendMessage” is deprecated and replaced by “publish”.

/ikb$service/v1/sendMessage:

/private/ikb$service/v1/sendMessage:

Sending messageFormat=IKB

An example “message” parameter using sendMessage with messageFormat=IKB:

{"toUserName":"","messageType":"SAMPLE_MESSAGE","data":"Hi, how are you?"}

fromUser will be added to the IKBResponseMessage based on authentication.

/ikb$service/v1/requestUserList:

Return value: List of UserReference as JSON.

/private/ikb$service/v1/requestUserList:

Return value: List of UserReference as JSON.

/ikb$service/v1/requestUserListUpdate:

Return value: List of UserReference as JSON.

/private/ikb$service/v1/requestUserListUpdate:

Return value: List of UserReference as JSON.

PLSQL API

See also: PL/SQL ContentServices API and the package “IKB_INSTANT”.

Publish message

The PLSQL API supports publishing to topics using procedure IKB_INSTANT.PUBLISH with the following parameters.

Example procedure for integration with iKnowBase Event using TEXT message:

CREATE OR REPLACE
PROCEDURE publish_to_instant_topic1_text
(
  PARAMS      IN    OT_EVENTPARAMS   
  , OLDREC    IN    OT_DOCUMENT    
)
IS 
  P_TOPIC         VARCHAR2(200);
  P_DATA          CLOB;
  P_FROM_USERNAME VARCHAR2(200);
  P_TO_USERNAME   VARCHAR2(200);
  P_MESSAGE_TYPE  VARCHAR2(200);
BEGIN
  P_TOPIC         := '/Topic1?messageFormat=TEXT';
  P_DATA          := 'Event triggered due to id: '||params.object_id;
  P_FROM_USERNAME := NULL;
  P_TO_USERNAME   := NULL;
  P_MESSAGE_TYPE  := NULL;
  IKB_INSTANT.PUBLISH(
      P_TOPIC
      , p_DATA
      , P_FROM_USERNAME
      , P_TO_USERNAME
      , P_MESSAGE_TYPE
  );
  COMMIT;
END;

Example procedure for integration with iKnowBase Event using IKB message:

CREATE OR REPLACE
PROCEDURE publish_to_instant_topic1_ikb
(
  PARAMS      IN    OT_EVENTPARAMS   
  , OLDREC    IN    OT_DOCUMENT    
)
IS 
  P_TOPIC         VARCHAR2(200);
  P_DATA          CLOB;
  P_FROM_USERNAME VARCHAR2(200);
  P_TO_USERNAME   VARCHAR2(200);
  P_MESSAGE_TYPE  VARCHAR2(200);
BEGIN
  P_TOPIC         := '/Topic1?messageFormat=IKB';
  P_DATA          := 'Event triggered due to id: '||params.object_id;
  P_FROM_USERNAME := 'IKBUSER1';
  P_TO_USERNAME   := NULL;
  P_MESSAGE_TYPE  := 'SAMPLE_MESSAGE';
  IKB_INSTANT.PUBLISH(
      P_TOPIC
      , p_DATA
      , P_FROM_USERNAME
      , P_TO_USERNAME
      , P_MESSAGE_TYPE
  );
  COMMIT;
END;

NOTE: You may need to issue “set define off” due to ampersands (&) in P_TOPIC.

Server request: requestUserList

The PLSQL API supports the server request “requestUserList” for UserList topics.

The call will return CT_USEREFERENCE, which is a list of OT_USERREFERENCE of users currently registered as online on the topic.

Example statement for calling the requestUserList:

DECLARE
  P_TOPIC VARCHAR2(200);
  P_USER_NAMES IKB_PORTAL_API.VC_ARR;
  P_FROM_USERNAME VARCHAR2(200);
  P_TIMEOUT NUMBER;
  L_USER_REFERENCES CT_USERREFERENCE;
BEGIN
  P_TOPIC := '/Topic1?messageFormat=IKB&userList=true';
  P_USER_NAMES := ikb_portal_api.empty_vc_arr;
  P_FROM_USERNAME := 'ORCLADMIN';
  P_TIMEOUT := 10;
  L_USER_REFERENCES := IKB_INSTANT.REQUEST_USERLIST(
    P_TOPIC => P_TOPIC,
    P_USER_NAMES => P_USER_NAMES,
    P_FROM_USERNAME => P_FROM_USERNAME,
    P_TIMEOUT => P_TIMEOUT
  );  
  DBMS_OUTPUT.PUT_LINE('Number of user references returned: ' || l_user_references.COUNT);
  FOR i IN 1 .. L_USER_REFERENCES.COUNT
  LOOP
     DBMS_OUTPUT.PUT_LINE('id=' || L_USER_REFERENCES(i).id || '; guid=' || L_USER_REFERENCES(i).guid || '; username=' || L_USER_REFERENCES(i).username || '; dn=' || L_USER_REFERENCES(i).dn || '; label=' || L_USER_REFERENCES(i).label);
  END LOOP;
END;

NOTE: You may need to issue “set define off” due to ampersands (&) in P_TOPIC.

Server request: requestUserListUpdate

The PLSQL API supports the server request “requestUserListUpdate” for UserList topics. This call produces the exact same output as the javascript client subscription option requestUserList=true.

The call will return CT_USEREFERENCE, which is a list of OT_USERREFERENCE of users currently registered as online on the topic.

Example statement for calling the requestUserList:

DECLARE
  P_TOPIC VARCHAR2(200);
  P_FROM_USERNAME VARCHAR2(200);
  P_TIMEOUT NUMBER;
  L_USER_REFERENCES CT_USERREFERENCE;
BEGIN
  P_TOPIC := '/Topic1?messageFormat=IKB&userList=true';
  P_FROM_USERNAME := 'ORCLADMIN';
  P_TIMEOUT := 10;
  L_USER_REFERENCES := IKB_INSTANT.REQUEST_USERLIST_UPDATE(
    P_TOPIC => P_TOPIC,
    P_FROM_USERNAME => P_FROM_USERNAME,
    P_TIMEOUT => P_TIMEOUT
  );  
  DBMS_OUTPUT.PUT_LINE('Number of user references returned: ' || l_user_references.COUNT);
  FOR i IN 1 .. L_USER_REFERENCES.COUNT
  LOOP
     DBMS_OUTPUT.PUT_LINE('id=' || L_USER_REFERENCES(i).id || '; guid=' || L_USER_REFERENCES(i).guid || '; username=' || L_USER_REFERENCES(i).username || '; dn=' || L_USER_REFERENCES(i).dn || '; label=' || L_USER_REFERENCES(i).label);
  END LOOP;
END;

NOTE: You may need to issue “set define off” due to ampersands (&) in P_TOPIC.