Basic Use of the JavaScript Library

For basic functionality of the JavaScript library for the real-time state API, only the following two functions are necessary.

Note: A complete list of table names and their data structures can be found in System State Model of the Real-Time API.

bomgarState(options)

Make one call to the bomgarState() function to provide the API with connection and authentication information and with the tables you wish to receive updates for.

Arguments

  • options ( Object )
    • username ( String ) - Required.
    • password ( String ) - Required.
    • host ( String ) - Required.
    • port ( Integer ) - Optional. Defaults to 443.
    • company ( String ) - Required.
    • tables ( String | String[] ) - Optional. Can be an array of table names or the string all. Defaults to all.

Returns

  • ( Observable<Object> ): An observable sequence of all model changes as objects, parsed from the original JSON.

Note: You must call .subscribe() on this returned observable object to actually initiate the connection to the server. Calling bomgarState() merely defines the necessary connection and authentication parameters.

Example

  • // Provide the API with the connection and authentication parameters
  • var allChangesObservable = bomgarState({
    • host: 'companyname.support.example.com',
    • port: 443, // Optional
    • company: 'companyname',
    • username: 'username',
    • password: 'password',
    • tables: ['customer_client', 'representative'] // Or 'all'
  • });
  •  
  • // This triggers the actual connection and authentication:
  • var subscription = allChangesObservable.subscribe();

.subscribe([onChange], [onError], [onCompleted])

Calling the subscribe() method on the observable returned by bomgarState() initiates the connection and authentication with your appliance over a WebSocket. If successful, the API then sends your table list to the server. subscribe() also allows you to optionally register callback functions for model changes, errors, and connection closures.

Arguments

  • onChange ( Function ): Function that the API invokes for every model change received from the server. The function should accept one argument: an object describing the model changes. The structure of this object is described in the Model Updates section of Protocol of the Real-Time State API.
  • onError ( Function ): Function that the API invokes 0 or 1 times if a fatal error occurs during connection, authentication, or table registration.
  • onCompleted ( Function ): Function that the API invokes once when the connection closes normally.

Returns

  • ( Object ): Returns an object representing the subscription. If you need to programmatically close the connection, call .dispose() on this object.

Example

  • // This causes the connection and authentication to occur.
  • var subscription = allChangesObservable.subscribe(
    • // This onChange function is invoked every time any model change - insertion, update, deletion, or truncation - occurs in any table you have registered for
    • function onChange(changeObject) {
      • switch (changeObject.type) {
        • case 'model_update':
          • // Test for 'insert', 'update', or 'delete' properties on changeObject, then find the table name and change local data accordingly
          • break;
        • case 'truncate_model':
          • // Delete all local data in all tables
          • break;
      • }
    • },
    • function onError(error) {
      • console.error('An error occurred: %s', error);
    • },
    • function onCompleted() {
      • console.log('Connection closed. No more messages will be received.');
    • }
  • );
  •  
  • // Later, if you need to close the connection manually:
  • // subscription.dispose();