Skip directly to searchSkip directly to the site navigationSkip directly to the page's main content

View System Documentation - Query Module FAQ

Overview

This document provides answers to the frequently asked questions (FAQ) and Troubleshooting tips for the IBIS-PH Query System's module development. The first section lists the FAQs, while the last section gives a general decision tree that can be used to help locate and diagnose the problem.

FAQ

This section discusses some of the frequently asked questions on module development. What do I name my file? This section discusses some of the frequently asked questions on module development. What sub directory/folder should I put my file in? This section discusses some of the frequently asked questions on module development. How do I test my just created module? This section discusses some of the frequently asked questions on module development. How do I check that my module is the correct structure and well formed? This section discusses some of the frequently asked questions on module development. How do I get my module included on the menu or as part of the module set? This section discusses some of the frequently asked questions on module development. How do I remove a non related step for a measure? This section discusses some of the frequently asked questions on module development. How do I remove a non related question/answer set for a measure? This section discusses some of the frequently asked questions on module development. How do I remove a group by dimension choice for a measure? This section discusses some of the frequently asked questions on module development. I'm done with my module now what am I supposed to do with it? This section discusses some of the frequently asked questions on module development.
FAQs:
Q: What should <STEP> names be?
A: Each step is named so it may be referred to elsewhere in the Module.xml file. The step name does not need to be externally consistent (e.g., with the SAS dataset). Choose a name that is descriptive. For example, a step that allows users to select which years they want to query might be named "Year." Other names might include, "Age," "Cause," "Geo," and "Gender."

Q: What is the Query.cfg path (in the IBISQ_ PARAMETERS)?
A: This is the path to the Query.cfg file on the HLUnix server. The paths have been listed in the Modules and Measures.xls file.

Q: Do DIMENSIONS need to be the same as STEPS?
A: No, you can include more dimensions than steps, and you may leave a step off the dimensions. We generally try to be consistent, and use Year, Age, Sex/Gender, and Geography as both steps and dimensions. Additional variables may be added to the dimensions, as long as they have been defined in the steps/answers somewhere. We also want to avoid situations in which a user can limit their query using a variable, such as by using the 5 Age Groups version of the age variable, and then run their query by a DIFFERENT VERSION of the same variable, such as the Four Age Groups version of the age variable.

Q: Who decides which steps we should be using?
A: We have made a decision, based on user-friendliness, that the steps should look similar across different modules. Most modules will have Year, Age, Sex/Gender, and Geography, so we've decided to include those. Certain modules will have additional selection, for instance, most Mortality modules have a "Cause of Death" step, surveys have an "Other Respondent Characteristics" step, and some birth modules have "Mother's Characteristics" step, in addition to the standard steps.

Q: Why are there different versions of the same step in my module.xml file?
A: For certain MEASURES, we can suppress certain <ANSWER>s, or even whole <STEP>s. Some modules, such as the Mortality module, will have two versions of the same STEP; one is suppressed for certain measures, while the other is suppressed for the other measures.

Q: When should I use radio buttons, versus check boxes, versus a scrolling list?
A: Use radio buttons when we don't want the user to select more than one item on the list. For instance, we don't want a user to select more than one VERSION of the age grouping, so we use radio buttons to limit them to one selection only (4 age groups OR 11 age groups, but not both). Use check boxes if it is okay for them to select more than one. This is frequently the case in end node filter variable selections. In such cases, the user may select multiple counties, age groups, or years. However, if the end node selections number more than 12, we'll want to use a scroll box.

What should question text be right under the step?

When to use <SELECTED />?
Each step should have a default selection when it is initially opened.

When to state defaults?

Q: if your module isn't working, how do you know if it is your problem, or the back end?
A: First, there's a tool on most xml editors that finds errors you might have made. For example: parse, F7, check for errors, etc. Secondly, you can look at Tomcat and on the line where it shows the (most recent) date and time, there's sometimes an error showing. Example: end tag does not correspond to <DESCRIPTION>. You can also set the first parameter to: name=debug, value=true. This will enable you to see parameter information on the confirmation page, and provides you with a link (IBISQ URL) that shows a possible mistake on the results page. If by then you've torn your hair out and still have no idea what the problem is, assume it's a back-end problem, so never you mind.

Q: What should be in the navigation path?
A: The navigation path should show the steps a users has selected to get to the current screen. For example: IBIS-PH > Custom Query > ED Small Area > Treat and Release > Hospital ED Encounters > Count - ED Treat and Release Encounters

Q: When do you capitalize variable names?
A: For variable names capitalize the first letter of each word unless it is an acronym. Examples: AgeGpSurvey18, GeoLHD, Year89_pres, MomEduc. For indicating variables they are usually lowercase. Examples: cause_f, agegrp_f, geo_f, year_f, icdDiag, icdEcodes, icdProc.

Q: What should the measure name be?
A: Measure names must match exactly, spelling and capitalization, with the xmlout files on the backend. We have adopted a standard of using all caps and using the measure type as the name, for example, PERCENTAGE, COUNT, AVERAGE, etc.

Q: How do you get a variable that users don't select into js?
A: Use the Hidden input flag in the configuration for that measure.

Referencing items from JavaScript
Anything that is to be referenced by any JavaScript MUST have a valid HTML name with a unique value for that name within that group of same named items. This means that the ANSWERS (or ANSWER) needs to have a NAME element and the ANSWER elements need to have a VALUE element for anything that is to be referenced/used by the JavaScript. It is good practice to document the input/selection names and values at the top of the JavaScript code. This name/value pairs map can really help you see (and it documents things better) what the selections are so that you know what the code is supposed to work with. When testing the code you can use "view source" to verify the name and values of the input selections are what you think they're supposed to be. It is also recommended that you use either Netscape or Firefox to debug JavaScript. It gives more information and it is more helpful that IE.

JavaScript in Mortality
Right now we added a line of code to restore the original func value if a user uses modify query to change the query. This prevents the func value from being incremented twice. The current solution necessitates that func values be 1-9. If additional funcs need to be added then the mod value (currently 10) will need to be changed in the javascript as well as the values that are added (currently 10 and 20). Also the func file names on hlunix will need to be changed to correspond with the new added values.

Steps to Validate a query
1. Run the query to the results page.
2. Press the [Show XML] button.
3. Save the xml (File/Save As). Save the file in the same directory that contains the "module.xsd" file.
4. Open the saved file in any validating XML editor and change the QUERY element to look like this:

<QUERY xmlns:ibis="http://ibis.health.utah.gov/ibisq_xml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="C:\Tomcat\webapps\ibisph-view\xml\query\module.xsd">
5. Choose the editor's Validate Option and see if there are any problems.

Trouble Shooting

This section discusses the process of determining where the problem is. This assumes you have a working PC with Internet Explorer 6.0+ or Netscape Navigator 6.0+ also properly working.

Can you bring up your module page on your PC?
URL: http://localhost/Query?module=my_module_name&measure=the_measure_name Where you need to substitute the "my_module_name" and "the_measure_name" values.
No.
Is Tomcat running?
Yes.
Try http://localhost/.
Page not found.
Tomcat and/or the ibisph-view system has a problem. Call the system administrator or Garth.
Home page displayed.
Does your module name match exactly your module's filename which should be in the tomcat/webaspps/ibisph-view/xml/query/module directory?
Yes
Does your measure name exactly match a measure name contained within your module xml file? This value should be in one of the /QUERY/MODULE/MEASURES/MEASURE/NAME elements.
Yes
Is your document well formed? See the FAQs on how this is tested.
No
Fix the issues and test again
Yes
Is tomcat throwing an exception (bunch of text displayed in the Tomcat output window). Look at the first few lines of the exception error and sometimes this gives line number of offending XML code.
Was Tomcat exception helpful?
Yes
Fix and try again.
No
Take a screen shot of the exception and email/call system administrator.
No.
Start the Tomcat service and try again.


Troubleshooting Tips