IBIS-Q System Documentation - Create Query Module Files

Creating a Query Module

This page describes how to create the Interface XML files. An additional page describes how to create the back-end files. Both the Interface XML files and the back-end files files are needed to produce a complete query module. This page includes:
  • description of Interface XML files
  • step-by-step procedures for creating Interface XML files

Sequence is not important in which end you create first (the Interface XML files or the back-end files); more than one person may be involved in creating the various files. The important thing is to make sure the names of variables match across all associated files.

Environment Containing the Interface and Back-End Files
Figure 3-1. Environment Containing the Interface and Back-End Files

Suggested Practices
  1. Establish a schedule or routine by which the various data stewards release their new datasets to you.
  2. Compile naming conventions and standards list to simplify naming the variables and help maintain consistency.
  3. Use a tested, working module.xml file as a template, and modify that template with the new data as you gather it.

Table 3-1. Interface XML and Back-end File Types
Interface XML Files Back-end Files
HTML Content (HTML Content XML Elements) configuration (.cfg)
Module selection (Module selection XML Elements, Query Module Selection Example) function (.def)
Query builder (Query builder XML Elements, Query Module Example) XML element output value mapping (.map)
Xinclude (optional) group (.grp)
head (.head) and tail (.tail)

Overview of Interface XML Files

The XML files you create are definition and control files that are transformed (via XSLTs) into the HTML pages shown to the user.

Note: The merge process that accomplishes this is controlled by a Java servlet that applies the appropriate XML Style sheet Language Transformations (XSLT) to a certain XML file. The files involved in that process are contained within the Application server, but are not created or maintained by IBIS-Q administrator.

HTML Content Files

The HTML content type XML files provide a consistent way to deliver basic HTML content to a user. The main element of this type of XML file is the CONTENT element. The CONTENT element contains the page's body HTML. Any XHTML may be embedded within this element tag. This allows the page developer to focus solely on the HTML body content of the page. The HTML code for the navigation, banner, header and footer, javascripts, and style sheets are all handled within one transformation file named "home.xslt". The advantage of this design is that the common page HTML code is only stored in one location and usable by many pages.

The Content must be in the form of XHTML. Be aware that XML includes a few oddities, such as having to escape some characters and not being able to use the HTML tag "nbsp".

Note: These types of files are not really "pure" XML data documents in that they have presentation and formatting information in them in the form of embedded XHTML tags/elements. This approach helps produce consistent pages with a simple mechanism to localize body HTML content within the existing system. The HTML formatting flexibility is retained without adding the needless complexity of creating a true XML data implementation where the content is separate from the presentation.

Measure Selection Files

The Measure Selection XML files provide elements that describe a module measure or configuration selection page. The main purpose of a measure selection page is to build selections that drive the user to a specific module.xml with a specific measure or configuration selected (where the user is then able to define and submit a query to the IBISQ system). These XML files, when transformed or formatted with the selection XSLT, produce a HTML measure selection page.

The very end selection item of a measure selection consists of specifying a module.xml and measure/configuration within that module file. The measure selection file contains OVERVIEW data elements but the main elements are SECTION, SELECTIONS, and SELECTION.

Query Builder Files

Query Builder consists of three major elements:
  • QUERY_MODULE
  • REQUEST
  • IBISQ_QUERY_RESULT

Of these three, only the QUERY_MODULE element resides in the Interface XML file. After the user leaves the query builder page a Java servlet adds REQUEST and IBISQ_QUERY_RESULT dynamically to the QUERY_MODULE element for temporary use. The Interface XML file contains measure and configuration definitions (CONFIGURATIONS), CGI application control parameters (PARAMETERS), overviews and section or step definitions (CRITERIA), and dimension data (DIMENSIONS). These Interface XML files, when transformed or formatted with the module.xslt, produce an HTML module page that allows the user to define query filters and specify how the result values should be summarized or grouped for display.

The balance of the XML data displayed on the query confirmation and query result type pages are dynamically added by the servlet. When a module and measure configuration is selected, the servlet loads the module XML file into memory. When the user submits the query, the servlet creates the REQUEST element and appends the user-specified filtering criteria and data grouping selections to this element. After the Query servlet has retrieved the XML data from the CGI application, the IBISQ_QUERY_RESULT element is created, and the actual query record data is appended.

Procedure for Creating Interface XML Files for a Sample Module

The following sample uses the Mortality dataset in creating MortSelection.xml.

Create the Query Selection Page

Note: Line references in the following procedure refer to the example shown in Query Module Selection Example.
Create the query selection page, MortSelection.xml.
  1. Enter the name of the file (line 18).
  2. Enter the overview information (lines 21-26).
  3. Enter the module information (lines 27-51).
    1. Create a section tag (blue bar, line 28) with a title for your measures (line 29), as illustrated in Figure 3-2.
      Sample of a Section Tag
      Figure 3-2. Sample of a Section Tag
    2. Create a <SELECTIONS> tag for your group of measures (line 30) then a <SELECTION> tag for your measure (line 32, 38).
      1. Optional: Enter any help button information needed (lines 33, 39), as shown in Figure 3-3.
        Sample of a Section Tag
        Figure 3-3. Sample of Help Information Added To Module
      2. Enter the title for your measure (line 34, 40). This title will show as a clickable link taking you to the query builder page.
      3. Create the LOCAL_URL tag (line 36, 42). The local URL will start with query/builder followed by the module folder name, mort, and then the module files name, MortCntyICD10, and then the measure name with .html on the end. (from line 42, query/builder/mort/MortCntyICD10/CrudeRate.html)

Create the Query-Builder Page

Create the query-builder page or module file, Mort.xml
Note: Line references in the following procedure refer to Query Module Example.)
  1. Enter the module name, title, description and version date (lines 18-21).
  2. Enter the module parameters (lines 24-37). (See Query Module IBISQ Application PARAMETERs for more information.)
    1. Configuration name with its location must be exact (line 26).
    2. Enter SAS and test (lines 29-36). These are the same for all modules.
  3. Create the QUERY_CONFIGURATION_SELECTION tag (lines 38-41). This is used for the 'You are Here:' line at the top of the page.
  4. Create the <CONFIGURATIONS> tag (lines 42-101).
    1. Configuration name (line 66) must match configuration name used in the selection file.
    2. Enter the title and description (lines 67-68).
    3. Enter the measure information (lines 44-65)
      1. Measure name, numerator, denominator and confidence limits must match xml output file exactly
      2. Enter the title and description
    4. Enter the function file in the configuration IBIS-Q parameters (lines 70-75). For Crude Rate enter CrudeRate for the function (func) value.
    5. Enter data source, notes, and issues (lines 76-101). See Figure 3-4 to see how they display.
      Display of Data Source, Notes, and Issues
      Figure 3-4. Display of Data Source, Notes, and Issues
  5. Create the overview section (lines 103-109). This is the paragraph that appears at the top of the query-builder page.
  6. Create the needed steps.
    1. Create the year step (lines 111-187).
      1. Enter the name and title (lines 112-113). The name should be descriptive, such as "year." Title is what you want to see on the blue bar after the step number. For Step 1: "Select year"
      2. Use the SELECTED_DIMENSIONS tag (lines 114-123) to specify the defaults for this step.
      3. If you are using multiple year options use a proxy variable (line 125). The selection (line 131) for each of the possible year options will have a value of the year variable name (line 133).
      4. Specify the text for the step and the description (lines 126-127). The description will show in a mouseover.
      5. Specify the selection type. Use one of the following options:
        • SINGLE = radio buttons, only one option can be selected at a time (lines 128-130).
        • MULTIPLE = checkboxes, many options can be selected.
        • LIST = listbox. Uses SIZE and either SINGLE or MULTIPLE tags within the list tag (lines 139-142).
        • TEXT_INPUT = text input box. Uses MAX_LENGTH tag within the text input tag to specify the maximum length of text string allowed (lines 180-182).
      6. Specify the dimension to use (line 137). The dimension must match a dimension named at the end of the module file (lines 212-228). The dimension name must match the html name used in the configuration file (see line 50). Optional - an 'all' type selection can be added to the list of years by using a selection tag (line 136).
  7. Create the remaining steps needed (lines 188-208).
  8. Create the dimension tags (lines 210-249). The order of the dimension tags will determine the order of the variables listed in the display by step as illustrated in Figure 3-5. Dimension tags should be created for each variable.
    Display Showing Available Dimension Tags Figure 3-5. Display Showing Available Dimension Tags
    1. The DIMENSION NAME tag (line 213) must match the name given in the DIMENSION_NAME tag (line 137). In this example the name is Year99-Pres. This must also match the html name in the configuration file (see line 50) .
    2. If this variable is associated with a proxy variable then the PROXY_DIMENSION_NAME tag must contain the name of that variable, YearProxy (line 216). The YearProxy must also have its own dimension tag. For proxy variables only the NAME and TITLE tags are used.
    3. The VALUE tags must match values in the data. The years listed (lines 218-225) are the years contained in the dataset.
    4. Values that you do not want listed within the step, such as unknown or total, can be listed with a NOT_ASSOCIATED_FLAG tag (line 226).

Test and Debug

Display the pages and make sure clicking on the Crude Rate measure on the selection page takes you to the query-builder page. (See Figure 3-2.) The name of the measure should appear in the URL for the query-builder page. You can also submit the query and make sure the appropriate information is displayed at the top of the confirmation page.
  1. If the xml pages don't display check the code with an xml editor such as Aioob.
  2. If the measure doesn't link to the query-builder page, check the module file name and the configuration name in the Module File to make sure they match with the names in the measure selection tags in the Measure Selection File.
  3. To see the sas log file set SAS to '2' in the module file PARAMETERS. Run the query and then 'View the XML.' The results will be near the bottom of the page. Another option is to run the query, 'View the XML' and then copy the REQUEST/QUERY_APPLICATION_URL and paste it into another browser window. Modify the URL so that sas=2 and hit enter. You may see the query information or you may have to use 'View Page Source' (access by right clicking on browser window) to see the query information.

For more detailed testing procedures and troubleshooting see Testing Modules and General Troubleshooting Steps.

For step-by-step instructions for creating the back-end files see Create Back-end Files.
For an overview of back-end files and their location see Create IBIS-Q Control Files.
IBIS-PH Community of Practice, Utah Department of Health, Salt Lake City, UT 84114-2101, Telephone: 801-538-9191, Fax: 801-538-9346
The information provided above is from the Utah Department of Health's Center for Health Data IBIS-PH web site (http://ibis.health.utah.gov). The information published on this website may be reproduced without permission. Please use the following citation: "Retrieved Mon, 23 November 2009 19:00:15 from Utah Department of Health, Center for Health Data, Indicator-Based Information System for Public Health Web site: http://ibis.health.utah.gov".

Content updated: Mon, 3 Mar 2008 11:40:27 MST