SSE: Data Broadcasting

note note this feature is only available for web apps that integrate with console overview the server side events (sse) feature enables app developers to build more responsive web applications with the ability to receive real time response data directly from the console ui this is achieved through a server sent event communication, enabling a seamless and immediate data flow from the console to the web app upon initiating an api request the native push based data delivery not only enables faster, real time frontend experiences but also streamlines infrastructure efficiency we’ve enhanced sse to support these additional features when multiple tabs are opened for an app on one browser, server sent events can facilitate sharing a single connection for pushing data updates to each open tab, keeping their application state consistent rather than separate connections per tab, developers can enable inter tab communication hence, all tabs process updates from a shared connection upon events instead of needing explicit coordination logic, allowing tabs to remain in sync applications can enable cross device data synchronization for their users by having them subscribe to server broadcasted topics the sse communication channel will facilitate pushing updates for subscribed topics across the user's connected devices supported browsers supported browsers the feature is expected to work fine while using chrome, firefox, microsoft edge, and safari prerequisites to implement sse, you need to instantiate the os1httpclient from the console ui the os1httpclient is a wrapper http client provided by the console ui to make it easier to support all http methods necessary for restful api calls it is a pre configured instance of axios https //axios http com/docs/intro that handles authentication, base urls, and other http client best practices // import from console ui context import { os1httpclient } from 'console/http'; // instantiate const httpclient = new os1httpclient( consolecontext authinitializer, process env base url ); the os1httpclient takes two arguments the first is props console authinitializer , which contains the authentication context or initialization parameters necessary for the client to make authenticated requests the second argument is the process env base url is for the api endpoints that the application will communicate with implementation enabling data bra across tabs to enable inter tab data synchronization, set the intertabcommunicationrequired flag to true , while initializing the console ui if not set, it defaults to false and each tab will have its own connection, which may result in unsynchronized data see the example below \<os1provider clientid={process env react app client id} loginredirectpath={'/redirectpath'} logoutredirectpath={'/logoutpath'} appid={process env react app initial app id} controls={controls} intertabcommunicationrequired={true} // here it is set as true \> \<initiate setconsole={handleconsoleinstancechange} /> \</os1provider> coherent views across multiple devices this section details the integration of server side events (sse) using the os1httpclient class provided by the console, allowing for real time communication from server to client in your application there are two ways to implement the server side events (sse) coherent views feature in your application prerequisites developers must set the intertabcommunicationrequired flag to true for their app they need to subscribe to the topic(s) they want to listen to for broadcasted messages the maximum number of topics that can be broadcast at a time is five we allow the following alphanumeric characters hyphen ( ) underscore ( ) colon ( ) for example, to broadcast dispatch updates to all the users who have opened a particular dispatch, the developer can create and subscribe to a topic using the dispatch id (e g , dispatch 1234) this subscription should be made when the page loads for the dispatch messages can then be sent to this broadcast topic as described below subscribing a topic developers can select specific topics to follow by calling the subscribebroadcasttopic function please note that each app has a maximum of 10 topics and 10 subscribers per topic to maximize the results, it is suggested to create specific topics that reflect the events they represent this will enable targeted events within the limits while ensuring accuracy therefore, it's important to use topic names that accurately reflect the context and stay within the subscriber limits to unsubscribe from a topic, call unsubscribebroadcasttopic example await httpclient subscribebroadcasttopic(\[ "dispatch\ e3956ddf e7a2 4a9e 914a ddace6a9d701", "facility 326e7698 c039 416a a697 768e9bbb451c\ dispatches"]) here the httpclient is an instance of os1httpclient , that is instantiated above the only argument that this function accepts is the array of strings option 1 using the {{sse broadcast}} placeholder this is the simplest option if using the console’s axios https //axios http com/docs/intro client step 1 setting the broadcast url parameter when making an api call, developers need to specify the attribute where the broadcast url is expected on the backend to set the value of this attribute, us the placeholder {{sse broadcast(topicnames)}} after setting the attribute, the console will automatically detect and replace this placeholder with the actual broadcast url developers can pass the callback attribute in the request url, headers, or the request body the example below adds {{sse broadcast(topicnames)}} to the header for the createvehicles request try { await axiosclient post( '/vehicles', dto, // the payload for the api call 'createvehicles', // the operation or function being called { withauth false }, // options, set to false if authentication is not required { headers { 'callback' "{{sse broadcast(dispatch\ e3956ddf e7a2 4a9e 914a ddace6a9d701, facility 326e7698 c039 416a a697 768e9bbb451c\ dispatches)}}", // updated automatically by the axios client 'content type' 'application/json', // set the content type of the request } } ); } catch (error) { console error('error', error); } the os1httpclient manages the sse connection and retrieves the callback url from the server it replaces the {{sse broadcast(topicnames)}} placeholder with the broadcast url needed in the api request if you need to pass multiple topics, separate them using a comma, like this {{sse broadcast(topicname1,topicname2)}} note that you can only pass up to 5 topics step 2 listen to sse events once a callback is received from the server, the console will emit a custom event, ssecallbackevent your application needs to listen to this event in your ui code and handle the data when the api response is pushed from the server document addeventlistener(`${consoleinstance events() ssecallbackevent}`, (eventdata) => { // handle the event data }); error handling if any internal errors occur during the connection setup, the console will throw an error, and an api call will be made with null as the callback url only non retriable errors will be thrown to the user example implementation the following sample code demonstrates the full implementation for using the {{sse broadcast}} placeholder // import and instantiate http client import { os1httpclient } from 'console/http'; const httpclient = new os1httpclient(consolecontext authinitializer, base url); // make api request with placeholder const makerequest = async () => { try { const response = await httpclient post('/api', data, { headers { 'callback' '{{sse broadcast(dispatch\ e3956ddf e7a2 4a9e 914a ddace6a9d701)}}' } }); console log(response); } catch (error) { console error(error); } }; // listen for callback event document addeventlistener(consolecontext events ssecallbackevent, (event) => { const data = event data; // callback payload // handle data }); // initiate request makerequest(); the implementation does the following imports and instantiates the os1httpclient makes an api call with the {{sse broadcast()}} placeholder console will swap the placeholder with the actual broadcast url each tab will check whether it has been subscribed to that topic or not if subscribed then it will listen for the ssecallbackevent callback the event data contains the response payload option 2 calling the broadcastevents this option works with any http client and is not limited to console’s axios client step 1 call the broadcastevents before making an api call, call the broadcastevents function to broadcast events this function accepts the topicnames on which events should be broadcasted and the "payload" to be passed please refer to the example code below const broadcast= await cl broadcastevents(\[ "dispatch\ e3956ddf e7a2 4a9e 914a ddace6a9d701"], payload ); step 2 listen for ssecallbackevent once a callback is received from the server, the console will emit a custom event, ssecallbackevent your application can listen to this event in your ui code and handle the data when the api response is pushed from the server document addeventlistener(`${consoleinstance events() ssecallbackevent}`, (eventdata) => { // handle the event data }); example implementation the following example shows how to implement sse into an application by manually calling the geteventbrokerurl // import and instantiate http client import { os1httpclient } from 'console/http'; const httpclient = new os1httpclient(consolecontext authinitializer, base url); // broadcast url state await axiosclient broadcastevents(\[ "dispatch\ e3956ddf e7a2 4a9e 914a ddace6a9d701"], payload ) // listen for callback event document addeventlistener(consolecontext events ssecallbackevent, (event) => { // handle event }); the implementation does the following imports and instantiates http client calls the broadcastevent for broadcasting response listens for ssecallbackevent broadcast event payload { "data" { "businesscommand" "participantsboatsentitycreate", "callbackmeta" {}, "commandname" "participantcreationsuccessevent", "data" { "appid" "participants", "createdat" "1707463018469", "createdby" { "id" "1", "name" "vehicle consoleui" }, "entityname" "boats", "isactive" true, "name" "sjdsadghafja", "owner" "tenants 436a9b2c 5f79 5b51 92ba 2da25050dd36", "properties" { "availability" true, "failurereason" "", "fueltype" "cng", "inprogress" false, "isfail" false, "mode" "sdhavdhha", "operatorid" "hdad", "processingstage" "isactive", "servicecode" "", "system" false }, "state" { "current" "onboarding\ onboarding", "transitions" \[ "active\ active" ] }, "uniquecode" "bjhgfajdf", "updatedat" "1707463018469", "updatedby" { "id" "1", "name" "vehicle consoleui" }, "id" "boats\ c6cf6d0c 7024 5925 90d9 a803b59df46f" }, "requestid" "d133e887 e52b 47dc 80ca 9f4228708cab", "tenantid" "developsln1" }, "eventid" "e5462690 e8b1 49e6 a082 82bad87ee70d", "x coreos request id" "", "brokertimestamp" 1707463018742, "agenttimestamp" 1707463018747, "topics" \[ "delhivery1\ app 0641372d ecd2 5804 93bb df0f802aaeb4\ test17" ], "type" "broadcast", // by this we are distinguishing between broadcast and callback "consoletimestamp" 1707463018796 } callouts if a user has subscribed to certain topics but their sse connection is interrupted due to network issues, the browser will automatically try to re establish the connection once the network is back if the user is re connected within 10 seconds, they will be re subscribed to their chosen topics however, if the reconnection takes longer than 10 seconds, the subscription will be lost each topic can have up to 10 subscribers each user can subscribe to 10 topics per application broadcasted message events are only raised on tabs that subscribed to that topic