Using the join.me API to schedule online meetings in Orchard CMS

Here at Cloud Construct we use join.me for all of our online meetings, audio conferences, and screen sharing session with clients. We like it a lot since it's simple and easy to use. Recently we were asked to figure out a way to host online meetings dynamically for a client and allow online scheduling for these meetings. We did not want to write conference software from scratch so we took a look to see if join.me had an application program interface (API) for hosting meetings, and indeed they do! If you go to the developer site for join.me it has details about a Restful API that you can access by simply signing up for access. This API allows for the scheduling and starting of meetings. It is very important to understand, however, that this API is currently only in BETA and that joinme.com has a forum for feature requests and enhancements if needed.

I created this blog post in an effort to explore the API providing some new functionality to one of our clients, The Paint Bar. I hope it provides some information on the API and also the great extensibility of Orchard CMS. The Paint Bar website is built on Orchard CMS. Customers can sign up for in-studio classes at The Paint Bar’s Boston and Newton, MA locations.. One idea is to allow the ability for customers to sign up for online classes as well, so they can learn to paint from home!

In starting this endeavor I reviewed the join.me API and saw that the best way to integrate the join.me functionality would be to allow for the creation of a new online meeting in the join.me system corresponding to a new online class in Orchard CMS. Once they create this meeting, users would get a personal link in a confirmation email when they signed up that would allow them to access the online class when it was time. We could also send a calendar invite as well in this email so users could add it to their calendars. Security would be provided by the anonymous link that is sent to the users. This would make sure only people with the email could join the online meeting. Lastly, to start the meeting we would show the link to an administrator in the Orchard CMS backend so they could launch and start the meeting as needed.

Step 1 : Create a new Orchard CMS Module

This blog post details specifically how to interact with the join.me API. Please read the Orchard documentation on Getting Started with Modules in order to understand the various components of an Orchard module. I hope to be packaging up the module for sharing to the Orchard Gallery as soon as I can.

Initially I created a new Orchard CMS module and enabled it in the Modules area under the administration dashboard. Secondly, I added a new settings class in order to allow the user to store their join.me API key for the site. These settings are found under the Settings nav item in Orchard.

 

In order to interact with the join.me API you need to use your key to make API requests and to have a proper redirect URL configured for your application. Once you set your key, the site will show you the redirect URL shown to you so you can enter it into the join.me portal. 

The last part of creating your module should be the custom online meeting part you will need to attach to whatever content item you wish. It is important to think about how this works ahead of time so that everything falls into place for you. In the case of The Paint Bar, they have the hierarchy of an online calendar that contains classes. These classes are content items that have various parts attached to them. In our example, we will create a new content type called "Online Paint Class" which has the same content parts our existing Paint Class type has except it also has our new join.me content part as well. This is what adds our new functionality to our class. 

New Online Paint Class Content Type :

Content Parts Associated with this Content Type :

Step 2 : Creating a new meeting

Now that we have our module scaffolded and interacting with Orchard via the dashboard, we can begin to create the service layer to schedule meetings. I recommend the first thing you do is download the Kitchen Sink example from join.me's developer portal. This is a C# example of how to authenticate with the join.me API and begin interacting with it.

I added a new menu item for our Online Classes in the Paint Bar's back end in order to facilitate adding new Online Painting Classes to the calendar. This will let employees of the Paint Bar easily schedule a new class that is specifically designed for online participants. 

As you can see above, there is a new item under Calendar called "Online Classes". This will allow employees to easily browse and create new classes. To recap, we have our Orchard module and our scaffolding built into the Orchard admin to support our new content type of Online Painting class. The next step is to allow for creating a new meeting. My first premonition was to simply create a C# service that would be called from my new content part driver to authorize to join.me and create my meeting. I was met with some disarray when I realized the API only supports the OAUTH 2.0 Implicit Grant Scenario. This means the token requires a browser in order to authenticate to the API and interact. In my scenario, this would be fine for an admin creating a new online class, but not for users looking to attend the meeting. There is no way to automatically add them to the meeting upon reserving a spot.

In order to work around this limitation we will need to send our own custom email to the user so they know what URL to browse to and what numbers to dial into when it is time to join the class. This would work well, but the API also does not currently support returning this information upon scheduling a new meting. This information is only provided when a new "Ad-Hoc" meeting is scheduled. I have put in a request to join.me to please add this ability. Well it seems we're at a roadblock with our module implementation. Let's look at Step 3 to see if we can solve these issues.

Step 3 : Implementing the join.me client side library and a new work flow.

In order to get around these hurdles and add the functionality we want to the site, we will need to think about this in a different way. It is my thought that we can have administrators schedule a meeting inside Orchard and save that meeting to the CMS for that particular class. At that point the online meeting with be scheduled through join.me and an email invitation will be sent to the administrator. Once scheduled, users will then sign-up for the class on the front end calendar and a queue will be setup to add user emails to the meeting in order to include them. This is not ideal because an administrator then has to log into the CMS and process the add requests manually. For now, this will be the way we approach this because it is much simpler than trying to spin up browsers in memory, etc.

After downloading the Kitchen Sink example I looked at the code and it was all pretty straightforward. I basically copied all of the JavaScript that was present in the example and then created a View template in my Orchard module in order to tie those in. Secondly, I added the various editor fields to my page as well in order to set the values using disabled and hidden fields for my module. Upon saving/publishing the Online Paint Class content item, these items would be persisted to the database. This is important so that next time an administrator comes into the class, they will have the option to start the meeting only and not scheduled it anymore. We can also add the ability to update the participant list based on reservations as well right on this screen or in a separate listing controller as well.

JoinMe Module Scripts

Step 4 : Putting it all together

Administrators will be required to authorize themselves to the join.me API on the first time scheduling an Online Paint class. Then the session token will be stored in the browser for future scheduling.

JoinMe Module requesting access for the first time when creating a new Online Paint Class :

Once the access is approved, we will show a different button that allows for scheduling the class online through join.me API. The fields will default to the values that the Online Paint Class has set in other content parts. For a painting class we typically have title, start time, and location as well. We simply use JavaScript to grab those values and set them through those fields.

Once the administrator clicks the button to schedule the online meeting we will then set the hidden fields on the page for our join.me module so that when the user publishes the class it is saved as well. Because I set myself as a participant of the meeting, I will receive an email letting me know what the scheduled painting class information is. It includes the join.me link as well as the dial in numbers.

After creating the meeting, we then will click Publish on our Online Paint Class item and all of our hidden fields we set will get saved to the database.

View of JoinMe.cshtml editor file.

<fieldset>
<legend>@T("join.me")</legend>
</fieldset>
<fieldset>
<label>Online Class Name : </label>
@Html.TextBoxFor(m => m.MeetingName, new { disabled = "disabled" })
@Html.HiddenFor(m => m.MeetingId) scheduled for
@Html.TextBoxFor(m => m.MeetingStart, new {disabled = "disabled" }) to
@Html.TextBoxFor(m => m.MeetingEnd, new { disabled = "disabled" }).
@Html.HiddenFor(m => m.Participants)
@Html.HiddenFor(m => m.StartWithPersonalUrl, new { value = "false" })
</fieldset>

The class is now saved and published to our Online Calendar!

Users can navigate to the online classes calendar and choose this new event. When administrators browse to the Online Class in the administration area of the CMS, they can now choose to simply start the class when they're ready or they could start it from their join.me dashboard as well.

To Be Continued...

I must leave the remaining pieces up to everyone out there. The remaining pieces as I see them are:

  • Add the ability to add a participant manually to a class or have an update participants button in the dashboard so all users who register for this class get added to the join.me participant list and the meeting is saved. This is important so they get an email with the audio and video conference information. 
  • Provide an update button for the meeting so that an administrator may choose to change the start date or end date for the meeting. This would then send an email to all participants who have paid for the class and let them know about the change.
  • I need to publish the code for this module to the Orchard CMS Gallery so people can take advantage of it. At it's core it is a very simple module to store meeting information and manage the participants. Because the join.me API is all done via the client side, all the logic is done via JS and most of that was re-purposed from their Kitchen Sink example.

In summary, I think this will be a great addition to The Paint Bar's offerings and I hope to show them this functionality soon. I also hope the join.me team will continue to improve the API and allow for some more options for integration/authorization. This will allow for a more robust and secure setup, as well as allow for some automated processes. This is where it can be very powerful.