How to Manage Users and Channels with BizOps Workspace

This how-to article is part of a series of articles that discuss PubNub's data management capabilities, collectively known as BizOps Workspace:

• How to Manage Users and Channels with BizOps Workspace
• How to Monitor and Moderate Conversations with BizOps Workspace

BizOps Workspace is a set of tools that help you manage your application.  This article will look at the 'User Management' and 'Channel Management' features that allow you to manage the App Context metadata about your Users and Channels, as well as the "membership" relationship between them without modifying any code.  This article will explain what App Context is and how it relates to User and Channel Management, as well as provide some interactive examples to help you understand how BizOps Workspace can help you manage your solution.

What is App Context?

App Context (formerly known as Objects) allows you to:

• Provide meaning to the Users and Channels in your application and the relationships between them.
• Store metadata for all of your entities on the server, making it simple to provide a global source of truth for your clients.  Note that a User does not have to represent a human being, and it is common to store device status within the user object instead.
• Receive instant real-time events whenever an object's values change.

While any application can use App Context, it is especially popular with developers creating Chat Solutions.

App Context itself is not new, so if you are already familiar with it, please skip to the next section that discusses what 'User Management' and 'Channel Management' provide.

App Context provides a set of suggested fields for your Users and Channels, as well as suggested fields for the Memberships between them.  Most of these fields are optional, but let's take a look at how you might use App Context in a typical chat application.

User App Context

When a new user is enrolled into your application, perhaps through some external identity provider, you will have some way of uniquely identifying that user to PubNub; this is the User ID that your user's client will use to initialize the PubNub SDK.  The PubNub User ID might not be the same as the ID you use elsewhere in your solution to identify that same user, so we recommend keeping track of that in the 'External ID' field.

User Name, Email, and Profile URL do not require explanation, but the benefit of keeping these within App Context means that if a user changes any of these fields, the changes can be propagated at scale to all listening clients using App Context events, which are supported by all of our SDKs.

Channel App Context

PubNub will create channels automatically whenever a user subscribes or publishes to them, but channels probably represent something meaningful to your application, for example, in a chat app, you might have a Group Chat that uses a channel to communicate or a live event might use a dedicated channel to manage polls.

Specifying App Context for a channel will store and update any desired metadata related to that channel, with those updates being optionally propagated to all interested clients.  You might give a channel a name, e.g., 'Chat between User A and User B,' and perhaps the channel is related to some document storage, which could be tracked in a custom 'URI' field.

Membership App Context

Having defined App Context for both our users and channels, we can now define the relationship between the two by specifying whether users are 'members' of a channel.

When a user joins a channel, they can receive updates about any other member of that same channel; they can be notified when users 'join' or 'leave' as well as whenever that user's App Context updates (e.g., they update their name).

This is a deceptively powerful mechanism that provides a lot of value, especially for chat app developers.  If you did not use App Context, you would need to track every user yourself, which channels they were a member of, and notify everyone else in that same channel when that user joins or leaves.  This challenge does not scale linearly, so the more users you have in your solution, the more difficult it becomes for you to try and manage all this information centrally.

By using App Context, your chat clients are provided with all the information they need to maintain their internal state, and you also have full control over that data with the PubNub Access Manager to prevent unauthorized access.

What is User and Channel Management?

'User Management' and 'Channel Management' provide a way of modifying your application's App Context data on the server through the PubNub admin portal.  For example, you might want to change a user's name or a channel description or delete a user who is no longer required.

Previously, anyone wishing to update an application's App Context had to develop a dedicated frontend that used one of our SDKs to make the required changes.  These new management features allow you to update your App Context data without any new development.

To use the User or Channel Management, you will need:

• App Context enabled on your keyset

• To use App Context in your application to store metadata about your Users and/or Channels, as well as the memberships between those entities.  It does not matter which SDK you use, although we recommend our Chat SDK for Typescript developers creating new chat apps; the feature will work with any of our SDKs.

• A paid pricing plan.  See the BizOps Workspace docs for more details.

User Management

The User Management pane will allow you to:

• Create or delete users

• Filter and search for users

• Create or update the metadata associated with users

• Create or update the channel memberships for those users.

For example, you could delete users who are no longer active in your system or create new users for testing purposes without having to provision that user separately.

Any user you have provided App Context for will appear in the User Management view.  If you are using our Chat SDK, then this SDK handles the app context for you behind the scenes; for example, the Chat SDK 'createUser()' method will call JavaScript's setUUIDMetadata under the covers.  If you are using any SDK other than the Chat SDK, then dedicated APIs are provided to modify your App Context data. I already mentioned the JavaScript API, but there are equivalents for all our APIs, including Java, Swift, Kotlin, Python, Unity, etc.

The documentation page on User Management will walk you through how to use User Management; just remember to create memberships for any new user (Assign to Channels) if needed.

Channel Management

The Channel Management pane, similar to the User Management pane, will allow you to create or delete channels, update the metadata associated with channels as well as update the users who are members of those channels.

For example, you might delete channels that are no longer active or create new channels to test some new functionality in your environment without touching production data.

Any channel you have provided App Context for will appear in the Channel Management view.  If you are using our Chat SDK, then this handles the app context for you behind the scenes; for example, the family of 'Create channel' methods will call JavaScript's setChannelMetadata() and setMemberships under the covers.  If you are using any SDK other than the Chat SDK, then dedicated APIs are provided to modify your App Context data.

The documentation page on Channel Management will walk you through how to use Channel Management; just remember to create memberships for any new channel (Assign Users) if needed.

Interactive Demo User and Chanel Management

I created an interactive demo app as it's a lot easier to understand User and Channel Management by using it or seeing it demonstrated.

The application code can be found on our PubNubDevelopers GitHub account or you can see a hosted version of the app at https://pubnubdevelopers.github.io/App-Context-Exerciser/.  If you are viewing this article on PubNub.com, you should also see the app embedded within an iFrame below

Setting up the Interactive Demo

The demo will create a new user in your keyset to represent itself and join any channels it finds in your keyset, for this reason I would strongly advise generating a new keyset when playing with this demo.

1. Generate a new PubNub keyset from the admin portal.  

2. Enable App Context on this keyset

3. Enable User, Channel, and Membership Metadata Events on this keyset.  These are options under the App Context section of your key configuration page.  If you do not enable these, you won't see updates reflected in the app

4. Leave all other key configuration options on their defaults

5. Make a note of the publish and subscribe keys you generated in the first step

6. Enter the publish and subscribe keys in the appropriate text boxes and press 'Save.'

Using the Interactive Demo

When you enter your publish and subscribe keys into the demo, it will:

• Create a user to represent itself in your keyset

• Query the current Users and Channels available on your keyset.  If it does not find any channels, it will create some test channels and users.

• The user that represents the interactive demo will join all channels it finds so it can receive updates on those channels and the associated users.  If this feels very permissive, remember that in production, you will have Access Manager enabled on your keyset, which prevents unauthorized access.

• Now, switch to the 'User Management' and 'Channel Management' features under BizOps Workspace in the PubNub admin portal.

• You should see some default users and channels created under the User Management and Channel Management screens, respectively. 

• Update the App Context for Users, Channels, and Memberships.  You should see your updates reflected on the demo app.  

• If required, use the 'Refresh Data' button to pull the latest updates from App Context; you would only need to do this if you created a User or Channel that did not share any memberships with the test application's user.

The above screenshot shows updating the App Context for user user_1, specifically the name and email fields, along with adding some custom data.

The above screenshot shows updating the App Conext for channel test_channel3, specifically the name and description fields, along with some custom data.

The above screenshot shows removing all users from testchannel_3, so that the channel now has no members.  Note that the memberships are no longer present in the 'Memberships' view.  

Examples using the PubNub Chat SDK

Although User and Channel Management will work with any SDK and use case, it is particularly useful to developers creating chat apps.  Because we recommend developers create greenfield chat applications using Typescript to target our Chat SDK, this section will illustrate these management capabilties being used with that SDK.

The Sample chat application that comes as part of the Chat SDK shows a simple example of a 1:1 direct conversation between two Users over a single Channel.  As mentioned earlier, the Chat SDK will use App Context to store the relationships between these Users and Channels, so we can use BizOps Workspace to update that data.

If you are following these steps yourself, you will need to refresh the chat application to see any updates you make on the backend; this is because this very simple app was not written to listen to changes in App Context.  This is a limitation of the application, not a limitation of the Chat SDK since you can listen for updates through the family of streamUpdates() APIs.

To manage the Channel data using the sample chat app, you can modify the channel name and see that updated name shown at the top of the app after you refresh the browser.

To manage User data, you must make a minor change to the userData structure; otherwise, any changes you make will be rewritten whenever you reload the app.

Comment out any settings you want to be able to modify with ‘User Management’, for example:

Membership updates are a bit trickier to show using the sample chat app, but the easiest approach I could think of would be to modify the handleSend() function to output the current number of members when each message is sent; that way, you can see updates without having to reload the app.

Modify the handleSend() function as follows:

The above screenshot requires a brief explanation; it is the result of

1. Sending a message without modifying any of the App Context data for Memberships.  This results in a message saying there are 2 channel members.

2. Deleting one of the members from the channel, it does not matter which.

3. Sending another message, this time observing that the message says there is only 1 member of the channel.

4. If we repeated step 2, any subsequent message would say there were 0 members in the channel.

Wait... If I'm not a member of the channel, why am I still receiving messages? This is a common question, and as mentioned in the documentation, you need to call connect() to subscribe to receive messages, which is separate from the membership established by the channel creation API - BizOps Workspace is only concerned with the latter.

Summary

BizOps Workspace can provide you with the ability to manage your User and Channel metadata easily which would previously have required a dedicated application and development effort.

Although this article has focussed on creating a new application, BizOps Workspace is equally useful to developers with existing applications.  Provided your application has been written to use App Context, which has been the recommended development pattern for production PubNub chat apps for some time now, you should be able to take advantage of the features discussed in this article without making any changes to your code.

User Management and Channel Management will work with any PubNub SDK. Still, developers using the Chat SDK will have an easier path to adoption since App Context is baked into the underlying architecture of the Chat SDK.  If you use the Chat SDK, User and Channel Management will "just work."

If you need help or support, feel free to reach out to our dedicated support team or email our developer relations team at devrel@pubnub.com