Instant Server | ||
---|---|---|
Previous | ||
SOLR Schema model |
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.
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:
Endpoint | Authentication | Authentication type | Return value | Comment |
---|---|---|---|---|
/ikb$service/v1/publish | Optional* | _ikbUserToken | NONE | *Topics with UserList support requires authentication using Secure Token Engine Authentication. |
/private/ikb$service/v1/publish | Required | Container | NONE | This is a application server protected URL. Clients will be prompted for authentication according to authentication setup. |
/ikb$service/v1/requestUserList | Required | _ikbUserToken | JSON:List of UserReference | Request a filtered userlist for the specified topic. |
/private/ikb$service/v1/requestUserList | Required | Container | JSON:List of UserReference | Request a filtered userlist for the specified topic. |
/ikb$service/v1/requestUserListUpdate | Required | _ikbUserToken | JSON:List of UserReference | Request a full userlist for the specified topic. Same as the javascript client subscription option requestUserList=true. |
/private/ikb$service/v1/requestUserListUpdate | Required | Container | JSON:List of UserReference | Request a full userlist for the specified topic. Same as the javascript client subscription option requestUserList=true. |
NOTE: For the old method “sendMessage” is deprecated and replaced by “publish”.
Parameter | Description | Type | Required |
---|---|---|---|
topic | Topic to publish message on. This is the full topicName (<topic base name>?<topic options>). | String | YES |
message | Text coded data to publish on channel. | String | YES |
_ikbUserToken | Scure token identifying the client user. | String | NO* |
Parameter | Description | Type | Required |
---|---|---|---|
topic | Topic to publish message on. This is the full topicName (<topic base name>?<topic options>). | String | YES |
message | Text coded data to publish on channel. | String | YES |
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.
Parameter | Description | Type | Required |
---|---|---|---|
topic | Topic requested for user list. This is the full topicName (<topic base name>?<topic options>). | String | YES |
userNames | Array of usernames. | String[] | NO |
_ikbUserToken | Scure token identifying the client user. | String | YES |
Return value: List of UserReference as JSON.
Parameter | Description | Type | Required |
---|---|---|---|
topic | Topic requested for user list. This is the full topicName (<topic base name>?<topic options>). | String | YES |
userNames | Array of usernames. | String[] | YES |
Return value: List of UserReference as JSON.
Parameter | Description | Type | Required |
---|---|---|---|
topic | Topic requested for user list. This is the full topicName (<topic base name>?<topic options>). | String | YES |
_ikbUserToken | Scure token identifying the client user. | String | YES |
Return value: List of UserReference as JSON.
Parameter | Description | Type | Required |
---|---|---|---|
topic | Topic requested for user list. This is the full topicName (<topic base name>?<topic options>). | String | YES |
Return value: List of UserReference as JSON.
See also:
PL/SQL ContentServices API
and the package
IKB_INSTANT
.
The PLSQL API supports publishing to topics using procedure IKB_INSTANT.PUBLISH with the following parameters.
Parameter | Description | Type | Required | Message formats |
---|---|---|---|---|
p_topic | Topic to publish message on. This is the full topicName (<topic base name>?<topic options>). | VARCHAR2 | YES | TEXT,IKB |
p_data | Text coded data to publish on channel. | CLOB | YES | TEXT,IKB |
p_from_username | The userName that published the message. | VARCHAR2 | NO* | IKB |
p_to_username | The target userName when publishing a private message. | VARCHAR2 | NO | IKB |
p_message_type | A message type used by the application. | VARCHAR2 | NO | IKB |
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.
The PLSQL API supports the server request “requestUserList” for UserList topics.
Parameter | Description | Type | Required | Default value |
---|---|---|---|---|
p_topic | Topic requested for user list. This is the full topicName (<topic base name>?<topic options>). | VARCHAR2 | YES | null |
p_from_username | The userName that requests the list. | VARCHAR2 | YES | null |
p_user_names | Specify to only receive a filtered list of users. | IKB_PORTAL_API.VC_ARR | NO | empty array |
p_timeout | Specify to only receive a filtered list of users. | IKB_PORTAL_API.VC_ARR | NO | 10 (seconds) |
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.
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.
Parameter | Description | Type | Required | Default value |
---|---|---|---|---|
p_topic | Topic requested for user list. This is the full topicName (<topic base name>?<topic options>). | VARCHAR2 | YES | null |
p_from_username | The userName that requests the list. | VARCHAR2 | YES | null |
p_timeout | Specify to only receive a filtered list of users. | IKB_PORTAL_API.VC_ARR | NO | 10 (seconds) |
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.
Previous | Top | |
SOLR Schema model |