5 Steps to Seamless Embedded BI Integration
Sep 19, 2018
As a BI consultant, part of what I do is guide new clients as they integrate Exago BI into their applications in preparation for deployment. Since they’ve already been through a trial integration using one of our sandbox applications at that point, clients know what steps are involved. Still, nine times out of ten, they seem to expect the actual integration into their actual products to be more extensive somehow.
Which it is, but not for the reasons they think!
BI integration can be broken down into five phases, some of which happen concurrently. These steps are:
- Identifying Requirements
- Listing Required Data Objects
- API Integration
- Custom Styling
- Multi-tenancy and Security
The developers heading up their company's BI integration project invariably get excited about #3. They anticipate hours of scripting and maybe even an opportunity for some ingenious “automagicry,” but here’s the big reveal: API integration is literally the easiest part of the integration process. You can get a minimum viable implementation done in under 20 lines of code.
You see, mechanics are just the tip of the integration iceberg. What keeps them afloat and functioning is a considerable amount of strategy and forethought. Linking to your requisite data objects, for example, is a quick and relatively straightforward process, and this is by design. Preparing those data objects for reporting, however, can take some doing. If there’s anything you take away from this article, it should be that integration is 90% planning, 10% execution.
If there’s anything you take away from this article, it should be that integration is 90% planning, 10% execution.
But let’s dig into these phases a little more so our understanding of the integration process looks less like a labyrinth and more like a blueprint.
Phase 1: Identify Requirements
Most companies already have this list in writing by the time they get to the integration phase, as technical and business requirements bear heavily on the product evaluation. Still, this list is subject to change over time, so make sure it’s up to date as you begin your integration.
A good rule of thumb to follow when listing your requirements is to start general and get more granular as you go. Make sure your framework and database needs are met before looking at things like tenanting structure and report storage or even finer details such as CSS classes and icons. Here’s an example of what an abbreviated requirements list might look like:
Once you’ve identified the capabilities that are important to you, you can begin reviewing Exago’s documentation and/or working with its services team to determine which will require action on your part to implement and which are already active by default. Your reconciled list might look a bit more like this:
Translating requirements into action items will help inform the rest of your integration and deployment process. Passing authentication parameters to Exago for authorization, for example, can be done via the API, and now your team can incorporate that code when they reach that step of the process.
Phase 2: List and Add Data Objects
Adding data objects to Exago is easy. All you have to do is point to the database using a connection string and then select the objects you want users to access. Preparing data objects for reporting both at the database level and at the configuration level—that requires some forethought and strategy.
It’s generally more performant, for example, to report off data tables that have been denormalized than to pull purely transactional data. Denormalization reduces the number of tables or views that your users have to navigate, which not only speeds up database queries by reducing the number of joins it takes to retrieve the necessary records but also improves the user experience and encourages product adoption. If connecting to a multi-tenant database, it’s also important to have tenant columns and/or schema owner information added to the requisite data objects so that Exago roles can be configured (see Phase 5).
Exago can report off programmable data objects such as views and stored procedures. While an effective means of getting some advance data processing done, these data object types can also slow performance if not implemented correctly. Familiarizing yourself with relevant best practices will go a long way toward optimizing your data from the outset.
Phase 3: API Integration
Minimal integration with Exago’s API, whether .NET or REST, is easily done in minutes and requires very little code. The example below was taken from the Exago demo application and shows how one would launch the full Exago UI using the .NET API.
//C# example of displaying the full Exago UI with .NET API
//Create a new api object.
//Specify the path to Exago and which Config file to load.
Api api = new Api(”C:/Program Files/Exago/”, ”WebReports.xml”);
//Make any user/session specific changes.
api.Parameters.GetParameter(“userId”).Value = “Nick”;
api.Parameters.GetParameter(“companyId”).Value = “Exago”;
api.General.LanguageFile = “en-us,en-us-tooltips,en-us-extensibility”;
//Activate a Role
Role role = api.Roles.GetRole("services");
//Make final api call to get one-time use parameter string
string sessionIdStr = api.GetUrlParamString(“ExagoHome”, true);
//Create full URL and set it as iFrame's source
string iFrameUrl = @"http://localhost/Exago/";
this.EmbeddedIFrame.Attributes['src'] = iFrameUrl + sessionIdStr;
But this, again, is the bare minimum, and figuring out how to expand on this depends a great deal on how you want your end users to experience the application. Exago BI’s modularity makes it easy to isolate the elements you want to display. Maybe you want a dropdown menu option to lead to a specific report designer or a button to export a particular report to PDF. Or perhaps you want to greet users with an interactive dashboard when they navigate to a given page. The API could be used to accomplish any of these objectives.
You’d be surprised how many companies completely skip this step. And they don’t skip it because it’s hard, they skip it because they don’t see the value from a user experience perspective. “With embedded analytics, business users no longer have to exit a business application to view results, analyze performance, and view recommended actions,” explains analytics consultant Wayne Eckerson. “They can do this inside the application itself.”
Simply plopping the full Exago UI into your application only gets you 50% of the embedding benefits.Yes, now users don’t have to leave your application to do their data analysis, but they still have to leave their patient form or blueprint or whatever they were looking at when they decided to divert to your reporting suite. What if they could access the data they needed through a dropdown next to the patient form? What if that chart was right alongside the blueprint?
This phase is by far the most strategy heavy. My advice? Plan as though you were building your reporting component rather than buying it. Go through all the same design processes you normally would for your own product, then map those decisions to Exago BI.
Here’s another example of good API integration at work. Looking back on our requirements list, let’s imagine we’re a medical application and want a custom menu to display just organ and tissue donor reports. When a user selects one of these reports from the menu, we want to display the report output in HTML format, but we also want to require that the user narrow the results by date and donor type, as the report would otherwise return an unwieldy number of records and put undue strain on the system.
Given these requirements, part of our API integration would involve filtering the report tree to display just the donor reports in the custom menu as well as inspecting each donor report prior to execution and dynamically adding a filter requirement where necessary. The resulting UI puts donor reports in an area of the application where users would expect them and helps ensure that those reports load the requisite information in a timely fashion.
Phase 4: Custom Styling
As a white label application, Exago BI makes it easy to change accent colors, modify the solution’s CSS, swap out icons, and “languagize” virtually all areas of the UI. We devoted an entire blog post to the subject if you want a deeper dive and links to relevant documentation. Suffice it to say, though, that with a little planning, you can utterly transform the user interface into something that looks both native to your application and accessible to your users.
Phase 5: Multi-Tenancy and Security
Setting up security involves a number of small precautionary measures and is otherwise largely driven by your tenanting structure, which starts with users’ login credentials.
As an embedded application, Exago BI leaves authentication to the host solution, which supplies Exago BI with the user identifiers it needs for authorization. This means that users need only log into the host application in order to access their respective Exago BI environments. Single sign-on facilitates a seamless experience as users transition from the host application to those embedded within it.
Once a user has provided credentials (for example, the user id and password), the host application authenticates the user and passes the user’s identification parameters to Exago BI via the API. From there, authorization is applied as per administrators’ configuration settings. User identification parameters can be used to authorize and configure the vast majority of application features, either natively or through programmatic extensions.
The same credentials that are passed in to determine what features are accessible will be used to dictate what data the user will see as well. Whether you're using schema- or column-based tenancy, or even a separate database for each of your clients, Exago BI's various multi-tenanting capabilities will help to ensure that individuals access only the data they are cleared to access.
And that’s it! Five steps. I hope this has been a helpful window onto what integrating Exago BI entails and how one might best go about it. For more information on this and related topics, I highly encourage you explore the following resources.
- Documentation - Searchable and extensive library of technical guides.
- Admin Support Labs - Guided webinars on administrative tasks and how they manifest to the end user.
- Exago Services - BI consultants ready to assist with technical training, API reviews, sample code snippets, report building, and more. Contact firstname.lastname@example.org.
- Training Videos - Series of videos by yours truly on virtually all areas of the Exago UI, a great way to get insight into what your users will have access to.
- End User Support Labs - Guided webinars on Exago BI features. Valuable resource to help you design your end user training.