Hi Developers and Interface Engineers!

I'd like to share with you how you can help your organization today obtain a better understanding of key message processing metrics (i.e. average message processing times, number of inbound messages, number of outbound messages, etc.)! Given the embedded IRIS database powering integration, you already have all the data you need -- you just need to put the data to use and present them in a user-friendly format!

Let me walk you through a sample implementation of an operational analytics dashboard that has served as a template for many organizations using these dashboards in production today. This particular sample dashboard will include the following metrics:

 

You can find the accompanying sample code here on Open Exchange. Just as a note, I used IRIS for Health 2019.1, but this can be done on Ensemble, Health Connect, and HealthShare.

Now, let's dive in!

1) Create a New Namespace: “REPORTS”

In this section, we will create a new namespace called “REPORTS,” where we will be compiling all the messages from other namespaces of interest to compute the message processing metrics.  

1. From the main screen of the Management Portal, click System Administration à Configuration à System Configuration à Namespaces
2. To create a new namespace, click the Create New Namespace button on the top left corner of the page.
3.  Fill in the following information to configure the namespace:
   1. Name of the namespace: REPORTS
   2. The default database for Globals: Local Database
   3. Select an existing database for Globals: Select Create New Database

This will launch the Database Wizard, which is used to create a new database 

1. 1. 1. Enter the name of your database: REPORTSGLOBALS
      2. Database directory: C:\InterSystems\HealthShare\mgr\REPORTSGLOBALS

A warning will appear saying that the directory does not exist. This is okay.

1. 3. 3. Click Next. Click Finish.
   4. The default database for Routines: Local Database
   5. Select an existing database for Routines: Select Create New Database

This will launch the Database Wizard, which is used to create a new database 

1. 1. 1. Enter the name of your database: REPORTSROUTINES
      2. Database directory: C:\InterSystems\HealthShare\mgr\REPORTSROUTINES

A warning will appear saying that the directory does not exist. This is okay.

3. 5. 3. Click Next. Click Finish.
   6. Click Save. Wait for the namespace to be created – a new page will show up.
4. Scroll to the bottom of the new Enable Ensemble Namespace page and click Close.

To edit the settings of a namespace, click the namespace on the Namespaces page and edit the desired properties. Then click Save in the top left corner of the page.

2) Import Code via Studio

In this section, we will use Studio to code and create necessary class files to fetch messages from all namespaces specified in the ^ReportNamespaces global and store the computed metrics in the Demo.OperationalAnalytics.MetricsTable class.

1. Open Studio. Ensure you are in the REPORTS namespace. To switch namespaces, go to File à Change Namespace and select the REPORTS namespace.
2. Click File à New. Under Categories, select General. Under Templates, select Class Definition and click OK.
   1. In the New Class Wizard, specify the following:
      1. Enter a package name: Demo.OperationalAnalytics
      2. Enter a class name: Compute
      3. Click “Next”
      4. For Class Type, press “Extends” and enter %SYS.Task.Definition for the Name of super class. This is to enable scheduling via Task Manager.
      5. Click “Finish”
3. Within the curly braces of the Demo.OperationalAnalytics.Compute class, copy-paste the following:

• Retrieve the code from Open Exchange
• Wait until we create the actual table to compile the class we just created.

4. Click File à New. Under Categories, select General. Under Templates, select Class Definition and click OK.
   1. In the New Class Wizard, specify the following:
      1. Enter a package name: Demo.OperationalAnalytics
      2. Enter a class name: MetricsTable
      3. Click “Next”
      4. For Class Type, select “Persistent”
      5. Click “Finish”
5. Within the curly braces of the Demo.OperationalAnalytics.MetricsTable class, copy-paste the following (the code will also be available on Open Exchange):

 

6. Compile both class files. On the top toolbar, click Build à Compile to compile the class.
7. In the Output console at the bottom of Studio, store the names of all namespaces into the ^ReportNamespaces global.
   1. For example:
      1. set ^ReportNamespaces(1) = “SANDBOX”
      2. set ^ReportNamespaces(2) = “FHIRSERVER”
      3. Repeat until you have the names of all namespaces stored in ^ReportNamespaces. You can check which namespaces have been stored by entering “zwrite ^ReportNamespaces”

3) Add Appropriate Global/Package Mappings to Namespaces of Interest

In this section, we will add the necessary global and package mappings to all namespaces that will be reporting to the REPORTS namespace.

1. From the main screen of the Management Portal, click System Administration à Configuration à System Configuration à Namespaces
2. For every namespace you would like to include in the final table,
   1. Click on Global Mappings, and then click “New.” Fill in the following information:
      1. Global Database Location: REPORTSGLOBALS
      2. Global Name: (copy paste from <DataLocation> tag in Demo.OperationalAnalytics.MetricsTable file in Studio – see below)
         1. Do not include the “^”
      3. Press “OK” to close the pop-up box, and then press “Save Changes.”
   2. Click on Package Mappings, and then click “New.” Fill in the following information:
      1. Package Database Location: REPORTSROUTINES
      2. Package Name: Demo.OperationalAnalytics
      3. Press “OK” to close the pop-up box, and then press “Save Changes.”

 

 

4) Set up Cube and Pivot Table on Analytics

In this section, we will build a Cube on Analytics Architect to organize the data from Demo.OperationalAnalytics.Compute class.

1. From the main screen of the Management Portal, click Analytics àArchitect. Ensure you are in the REPORTS namespace.
2. Click “New” and fill in the following information:
   1. Definition Type: Cube
   2. Cube Name: Operational Analytics
   3. Cube Source: Class
   4. Source Class: Demo.OperationalAnalytics.MetricsTable
      1. Use the “Browse…” button to select the class
   5. Class Name for the Cube: Leave as is.
   6. Hit “OK” on the bottom right.
3. From Source Class on the left-hand column, drag and drop Namespace onto the Dimensions category under the “Operational Analytics”.
   1. To create a roll-up for the date/time (year, month, day, hour):
      1. Click “Add Element” next to “Model Elements” at the top.
      2. In the pop-up window, enter the following:
         1. Enter New Element Name: DateRollUp
         2. Select Time Dimension
         3. Click “OK”
      3. Click on “DateRollUp” under Dimensions and select “Property” as “RunTime” in the Details pane. Then, click on the “H1” listed under “DateRollUp”, and click “Add Element” at the top again.
         1. Enter New Element Name: Year
         2. Select Level
         3. Click “OK”
         4. Click the new level that was just created and select the appropriate “Extract value with function” on the right-hand side under “Details”. See table below for corresponding functions.

1. 1. 1. 5. Repeat for Month, Day, and Hour

 

4. Drag and drop the remaining metrics except %ID (AvgAckTime, AvgTime, MaxTime, MinTime, NumInbound, and NumOutbound) onto the Measures category.
   1. The following only applies to the time metrics (AvgAckTime, AvgTime, MaxTime, MinTime). Leave NumInbound and NumOutbound as is:

Under Details on the right-hand side, set the “Precision” to 3, as shown below.

5. Press “Compile” and hit “Done” once finished. The Cube should look like the following:

 

 

6. Back in the Management Portal, go to Analytics àAnalyzer. In the Analyzer, press the cube on the top left and select the “Operational Analytics” cube we just created.
   1. The Analyzer may already load the “Operational Analytics” cube. Move onto step 7 if so
7. Drag and drop all the measures (except “Count”) under Columns. As for the dimensions, drag and drop them onto rows in the following manner:

After dragging Namespace into Rows, drag DateRollUp onto the diagonal arrow of Namespace.

8. To format the numbers that will show up in the table, click on the “wheel” symbol next to each measure you added in the column (see image above).
9. When the “Level Options” window pops out, press “Format and Style” to expand the section.
   1. Enter “#” in the Format section for NumInbound and NumOutbound.
   2. Hit “OK” to exit.

10. Press “Save” at the top, and fill in the following information for “Save Pivot”:
    1. Folder: Demo (up to user discretion)
    2. Pivot Name: Operational Analytics Pivot
    3. Press “OK”

5) Create a Dashboard on Analytics – User Portal

In this section, we will set up a dashboard on Analytics User Portal to display the resulting Operational Analytics pivot table.

1. From the main screen of the Management Portal, click Analytics à User Portal. Ensure you are in the REPORTS namespace.
2. Press the large “+” sign at the top, and then press “Add Dashboard” under “Add New Item” on the left-hand column.
   1. Fill in the following information to create a new dashboard.
      1. Folder: Demo (up to user discretion)
      2. Dashboard Name: Operational Analytics Dashboard
      3. Dashboard Title: Operational Analytics Dashboard
      4. Press “OK” at the bottom right.
3. An empty dashboard will have appeared on the page. Click the right-hand arrow on the left-side of the page. In the Dashboard Editor that will slide out, click “Widgets” and then the “+” sign to add a widget.
4. In the Widget Wizard, click on “Pivots and Charts” on the left-hand column, and then select “Table”. See example image below.
   1. Data source: Demo/Operational Analytics Pivot.pivot (use the magnifying glass button to navigate)
   2. Widget Name: Operational Analytics Widget
   3. Press “OK” on the bottom right to exit the wizard.

The resulting widget will display the data stored in the Demo.OperationalAnalytics.MetricsTable. As of right now, there is no data stored and you will see an empty table.

 

By adding a filter on Namespace or Year/Month/Day/Hour, we can focus on particular dates and exclude “null” data.

1. Click the right-hand arrow on the left-side of the page. In the Dashboard Editor that will slide out, click “Widgets” and then select the “Operational Analytics Widget” widget.
2. Click on “Controls” and then press the “+” sign to prompt the Control Wizard
   1. Target: *
   2. Action: Apply Filter
   3. Filter: (put in Namespace, Month, etc.)
   4. Press “OK” to exit the wizard.
3. Press “Save” on the top to preserve the newly added filter.
4. More filters can be added by following the above procedure.

6) Schedule to Run Hourly using Task Manager

In this section, we will use the Task Manager to schedule the Operational Analytics Dashboard to refresh every hour to evaluate the messages from the preceding hour.

1. From the main screen of the Management Portal, ensure you are in the REPORTS namespace. To navigate to Task Manager, click System Operation à Task Manager à New Task
2. Fill out the Task Scheduler Wizard:
   1. Task name: Refresh Operational Analytics Dashboard
   2. Namespace to run task in: REPORTS
   3. Task type: Demo.OperationalAnalytics.Compute
   4. Click “Next>” on the bottom of the screen.
   5. How often do you want the Task Manager to execute this task? Daily
      1. Every “1” day(s)
      2. Specify Start Date (End Date is not necessary)
      3. Select the option to “Run every ___” and modify to “Run every 1 Hours”
      4. First time to run: 00:00:00
      5. Last time to run: 23:00:00
   6. Press “Finish” to exit the wizard.

7) Verifying the Implementation

In this section, we will examine how to verify the above implementation of the operational analytics table displaying key metrics of processing messages across specified namespaces.

To observe the contents of the Demo.OperationalAnalytics.MetricsTable, we can take advantage of the built-in SQL feature.

1. From the main screen of the Management Portal, ensure you are in the REPORTS namespace.
2. Navigate to System Explorer à SQL
3. Click “Execute Query” and insert the following SQL statement:
   1. select * from Demo_OperationalAnalytics.MetricsTable
4. Press “Execute” and the contents will be displayed via SQL.

8) Resulting Analytics Dashboard: Sample

By following the above implementation, we are able to achieve a table listing the metrics for messages from specified namespace(s).

 

 

 

 

*Please note that the data has been generated for display purposes.

 

Double click on "2019" next to SANDBOX to take advantage of the DateRollUp we created! 

Continue clicking down into "Mar-2019" or any of the other months to drill down into days and then hours.

 

... and that's it! Please feel free to adapt the sample code to meet the needs of your organization!

If you have any questions, please reach out to your account's Sales Engineer!