Part of building great applications is not only making them beautiful, but also easy to use. Help in the form of tooltips and on page instructions isn’t always enough. We have recently started working with Zendesk and are slowly building up a great knowledge base. Our aim was to serve our articles directly to our users within our application, in a meaningful way. We therefore embarked on an Oracle APEX and Zendesk integration.
We are very happy with the results, and wanted to share so you can do the same! Here’s how.
1. Widget Settings in Zendesk
i. Log in to your Zendesk account and click on the Settings icon. This will allow you to configure your widget as below, in the customization tab
Make sure you have enabled Help Center and Contextual Help
ii. Next, go to the Set Up tab and grab your widget snippet. This piece of code will contain your secret key.
<script id="ze-snippet" src="https://static.zdassets.com/ekr/snippet.js?key=YOURAPIKEY"> </script> <!-- End of xxxxx Zendesk Widget script -->
2. Database objects needed for our Oracle APEX and Zendesk integration
We wanted to be quite specific with our context sensitive help, so we decided to use a simple table. It contains primarily APP_NAME (Alias), PAGE_ID, and SEARCH_STR. This enables us to simply build up a list of very specific keywords or search terms per page.
A package (ZEN_DESK_PKG) then queries this table and prints the appropriate HTML region necessary for the widget.
Our package looks something like this. Please note that we have simplified it here, as we had slightly different requirements. However this should suffice for illustrations purposes!
3. Global Page – APEX – Zendesk region
We wanted help to be available throughout our application, so we included our Zendesk Widget call on Page 0 (Global Page).
The zE.setHelpCenterSuggestions function allows us to pass in a search string dynamically to the widget, and our goal was to make this as relevant as possible.
For example, when a user is on the ‘Manage Users’ page, we knew which articles we wanted to suggest, as below:
Notice that there is a list of suggested articles, before the user has even entered a query. This uses the Context Sensitive help feature we configured above.
We added a PL/SQL Dynamic Content region on Page 0, as below:
BEGIN ZEN_DESK.print_help_html(p_app_id => :app_id, p_page_id => :app_page_id, p_user_id => :p_user_id); END;
And that’s all there is to it! It was extremely simply for us to complete our APEX and Zendesk integration. We love being able to control the suggested articles.
There are so many ways you could do this differently, of course. You could pass in the Page Name if they contain relevant search terms, or alias, or simply page number if your have used good logic in your page numbering (example: page 1-99: Orders, 100 – 199: Products), Page Group…
We really wanted to narrow down the results and control exactly what appeared on every page, so we went quite granular here, but you might not need to go that far.
Please note that if a page has no entry in our table, the widget simply appears with no suggested articles, and the user can enter a search term to search our database themselves:
This was a super simple integration as you can see, and we are definitely finding it has reduced our support emails as users can self-serve from right within the app. What we particularly love is that they don’t even have to leave our app to read the article. When they click on it in the widget, it appears directly there, without the loss of context:
4. Other ways to help your users
Also, don’t underestimate the importance of APEX Item level help and Page Level Help. Will the users bother clicking on those little icons? Not convinced, but it can still decrease your support time if all you have to answer is: click on the question mark icon and you’ll get your answer :-)
Thoughts or comments? We’d love to hear from you! Here’s to building fast and beautiful applications, fellow APEXers!