Jesse Freeman

Jesse is an evangelist for anything OpenText Analytics related.

6 F-Type Examples in DevShare You Can Use Now

With the release of OpenText Information Hub, Free Edition (formerly BIRT iHub F-Type) we added corresponding content to the DevShare portion of the Developer Center. One section of that content, F-Type Examples, houses sample apps and working examples developed specifically for iHub, Free Edition. When it comes to working with a new product, or using aspects of a product I know well but have not used before, I find examples valuable for getting started. Whether I need ideas for what is possible or confirmation I am going down the right path, I find examples to be particularly useful. Currently, six different examples have been uploaded to the DevShare to demonstrate various ways that iHub, Free Edition can help you. These examples range from simple, well-designed reports to a full sample application. In this post, I will step you through these six examples and detail their various aspects and features. The Six Examples Call Center Example Dashboard – With the large number call centers around the world and companies increasingly focusing on custom experience, business leaders demand metrics about call center performance, and expect those metrics on quick-reading, real-time dashboards. This example demonstrates how the iHub, Free Edition can do exactly that by creating a dashboard to quickly and effectively analyze the metrics of a call center. It utilizes a well designed data object that uses CSV files as the data source, includes multiple data sets that have properly configured column properties (format, header, etc.), and uses a well designed data model with proper categories and hierarchies. Additionally, the use of multiple data sets within the data object is part of what makes this a well designed data model. When used against a relational database, the multiple data sets allow for optimal query trimming within the datadesign file and the generated data object will have better compression. The Dashboard itself has two tabs: Call Analysis (screenshot below) displays an interactive dashboard with drill-downs and selectors, and Calls By State displays a United States map; you click a state on the map to launch a sub-report for that state. InfographiX Examples – This example can create three different infographics. These samples can inspire you with ways to display your own data in highy visual formats. The three included samples are: Classic Models – This example uses the Classic Models sample database that comes with iHub, Free Edition and displays information about the customers in the database by geography, purchasing habits and more in graphic form. The result is shown below. Storage Statistics – This example uses static data and displays statistics for data in a cloud-based storage system – for example, data formats (audio, video, photos, etc.), traffic by data type, and downloads vs. uploads. Tornado – Uses example uses a data object for its data source. It displays statistics about tornadoes in the United States, such as the number of tornadoes per month, relative numbers of tornadoes by strength (on the Enhanced Fujita, or EF, scale) and fatalities by state. Chicago Crimes Example Dashboard – As a developer and a user, I am always interested in seeing location information integrated into applications. I find it particularly useful when a map is used to visualize location information as it allows you to quickly analyze important geographic information about a data set. This web application demonstrates how we can interact with location information. It uses the Custom Visualizations feature in iHub 3.1 to display a Google Map of the Windy City, and adds custom icons and marker clustering to show crime data. It also provides a data selector gadget so users can choose which types of crimes to display. This example, which can be deployed to iHub as an application, shows you how to display a Dashboard when opening a BIRT application. Simple and Well Designed Reports – This example includes two well designed reports that are simple and elegant. By “well designed,” we mean that elements of the data model have been configured to use libraries for styles, which unifies the whole report and makes its appearance consistent. Additionally, they conform to industry standards for layout and design. If you are new to report development, these are good examples to use as a starting point for developing quality reports with a uniform look and feel. If you are more experienced, these are still worth going over because you may find a feature you have not used before, and they will reinforce good practices on the features you already know. These reports demonstrate how to use a report library, and they highlight several features – such as alternate rows, hyperlinks, highlighting, aggregations and formatting – that help you to display complex data more efficiently and effectively. The reports also show how to use themes to standardize the look and feel of charts and tables, and demonstrate parameters with drop-down lists that use both static and scripted default values. A screenshot of one of the reports appears below. BIRT with the Power of jQuery – This includes two examples that use jQuery to add functionality to BIRT reports. Expand and Collapse – This example uses jQuery to automatically expand and collapse sections in a report. A plus (+) or minus (-) is added next to the report elements that, when clicked, will expand or collapse various sections for the report. For example, say you have organized your customers based on region and country. With this added interactivity, you can start with a compact table and then expand the table into the desired country and region in real time. This enables you to limit the displayed results without the need for filtering or re-rendering the report. Highlight on Mouse Hover – This example (shown below) uses jQuery to highlight rows and columns when the user’s mouse hovers over them, which helps users navigate through very wide or very tall tables. The jQuery used to achieve this behavior updates the CSS properties of the various elements, which gives you flexibility when modifying the styling of the report elements. The effects in this example are primarily achieved through modifying the background color, so any color you specify though standard CSS can be used for the highlight. City Taxi Sample App – This example, as the name implies, is a sample application for an imaginary urban transportation company. It demonstrates how BIRT can power compelling embedded analytic applications. Features demonstrated by this application include: Information graphics for displaying data in visually appealing formats Columnar reports with filtering capabilities Interactive reports that end users can modify from their browsers Geospatial visualization built into a report Dashboards designed for Big Data analysis Additionally, this application demonstrates how BIRT can seamlessly add analytic capabilities to existing web applications. All content is presented as part of the HTML web pages, providing a consistent overall user experience for data analysis. The app also demonstrates how to use the Javascript API to embed content with minimal coding. As you can see, this new DevShare section provides a unified area where iHub, Free Edition examples can be shared and distributed. The multiple examples already available range from simple, elegant reports for people who are just getting started, to full sample applications for developers who are ready to integrate BIRT into your existing applications. Thank you for reading this post on the Examples DevShare. We encourage you to download and work with the examples, then tell us what you like and what more you want to see.

Read More

How to Configure BIRT iHub F-Type to use Active Directory or LDAP

Developers often ask how they can use a single authentication source for multiple applications instead of managing and maintaining separate user directories for individual applications. This is where using Microsoft’s Active Directory or an application that utilizes a Lightweight Directory Access Protocol (LDAP) comes into play. Active Directory and LDAP enable a common location to manage user authentication instead of relying on each individual piece of software to maintain its own database of users. BIRT iHub can utilize Active Directory or LDAP to externalize user authentication. Thanks to a utility created by my colleague Rob Murphy, BIRT iHub F-Type can now also connect to Active Directory or LDAP. In this post, I will walk you through obtaining the utility and using it to connect your iHub to an existing LDAP installation. This tutorial assumes you have already installed BIRT iHub F-Type and have an existing LDAP installation already running. The first step is to obtain the LDAP utility from the DevShare. (If you do not already have an account at, you will need to create one.) After you have downloaded the utility, copy it to a location accessible from the machine where BIRT iHub F-Type is installed. For this how-to, I copied the utility (ConfigureDirService.tgz in the list below) into the home directory of the user that runs iHub.   Now, extract the utility by using the tar command or something similar. This is the result: After you have extracted the utility, take a look through README.txt for an overview of how to use the utility and for details on all of the utility’s valid options. The next step is to open the file with a text editor and add specific values for your environment. For a typical installation, you need to make changes to the Connection Settings and Mapping sections. Connection Settings Of the various Connection Settings, you need to modify server, port, queryAccount, queryPassword, principalDNPrefix and principalDNSuffix. You may also need to modify other settings to align with your specific environment. For this example I use an installation of Apache Directory Studio for my LDAP, so I have also modified the value of isActiveDirectory to false since I will not connect to Active Directory. The value of server needs to be changed to the hostname of the machine where your Active Directory or LDAP is installed, and the value of port needs to be changed to the port where the Active Directory or LDAP is listening. The value for queryAccount needs to be to set to an account with  permission to query the Active Directory or LDAP installation. For my example, I have used the admin account of the LDAP instance. The queryPassword for the queryAccount also needs to be set. The final two settings you will need to modify are the principalDNPrefix and principalDNSuffix. Think of these as the values that will encapsulate the username when it is passed to your LDAP or Active Directory. My LDAP includes a user named Jesse whose Distinguished Name (DN)  is uid=Jesse,ou=users,ou=system. Therefore, the DN prefix needs to be uid= and the suffix needs to be ,ou=users,ou=system to properly align with the LDAP. Mapping Settings Next, you will need to modify the Mapping section to include the values needed to map iHub to your Active Directory or LDAP. You will not need to provide a value for every field, and the fields you use may vary depending on your desired configuration. However, the majority of the fields need to be populated in order to properly map users and groups to your iHub. These are the LDAP mapping properties:   The value of userBaseDN should point to the structure where your users are housed. My userBaseDN is configured to ou=users,ou=system as the organizational unit (ou) users is located within the top level ou system in my LDAP structure. The userLoginNameAttr needs to be set to the attribute used to specify the users. My users are specified as a uid, so I have configured this properly as uid for my mapping. The userFullNameAttr should be mapped to the attribute that  specifies a user’s full name. Within my environment, I have mapped this to the cn (common name) property. The userDescriptionAttr should be mapped to the attribute used to specify a description of the user. This is not a required item, but it must be set if you wish to map the user description in iHub to a description set in your Active Directory or LDAP. In my environment, I do not use this setting. The userObject needs to be set with the name of the object class that is used to define the users. Within my environment, I have defined the users using the inetOrgPerson class and thus I have specified inetorgperson for this value. The emailAttr needs to be mapped to the attribute used to specify the email address for the user. Within my environment the email address is specified as a mail attribute so I have specified mail for this property. The value of groupBaseDN, similar to userBaseDN, should be mapped to the structure where your user groups are housed. My groupBaseDN is configured to ou=roles,ou=system because the ou roles is located within the top level ou system in my LDAP structure (as seen below). The ou roles houses the various roles I want mapped to user groups within the iHub. The value of groupDescAttr should be set to the attribute you have set to contain the groups description within your Active Directory or LDAP. I have configured my environment to use the cn property specified for each user group. The value of groupObject needs to be set to the object class name used for the groups within your Active Directory or LDAP. Within my environment, I am using the object class groupOfUniqueNames for each of my user groups and thus have specified groupofuniquenames for this value. The value of memberListAttr needs to be set to the attribute used to specify each member that is part of that group. Within my environment, each member is added to the group as a uniquemember attribute and thus I have specified this value as uniquemember. The value of memberIDType needs to be set to match the ID type you are using to map each member. Within my environment, the members are specified using the full DN of the member and thus I have specified the value DN. The value of homeFolderAttr needs to be specified to the attribute within your Active Directory or LDAP used to map the location of the users home folder within the iHub. Within my environment, I have used the attribute homePostalAddress to specify the users’ home folder path and thus have specified homePostalAddress for this attribute. The value of homeFolderDefault needs to be specified with the path you want to be the root directory of where the users’ home folders are created. You need to set this value if there is not an attribute to specifically set the users’ home folder. Within my environment, I have configured this as /home to align with my existing home folder configuration as well as with the default location used in the iHub. For example, one of my users, alice, does not have a homePostalAddress specified; however, homePostalAddress is the value I have mapped for the users home folder. Since she does not have a home folder explicitly specified, a home folder will automatically be created for her at /home/alice. Applying the Changes, Testing, and Undoing  Now that you have configured all of the needed values in your file, save the file and open a terminal window. Navigate to the directory where you extracted the LDAP utility and run the script (ConfigureDirService.bat on Windows). The utility, which does not require any user input at this point, will report errors that occur and generate a message (shown below) to indicate when it has completed successfully. Please note that your iHub must be running for the utility to properly communicate with it and to make the required changes. Once the LDAP utility has run successfully, log in to the Information Console using the Administrator account and navigate to the iHub Administrator interface. You should now see all of the Users and User Groups mapped to your Active Directory or LDAP within this interface. (The screenshot below shows the groups in the left column and the users in the main pane.) After verifying that the users and user groups you created show up properly, log out of the Administrator account and attempt to log in using one of the user accounts in your Active Directory or LDAP. The folder structure below shows our new user in place. You have now configured your BIRT iHub F-Type environment to use your existing Active Directory or LDAP to manage users and user groups. If something goes wrong, or you need iHub to stop using your Active Directory or LDAP, you can run (or ConfigureDirService.bat on Windows) script again with the -r true flag, as shown below. Thank you for reading this post on configuring your BIRT iHub F-Type to use an external Active Directory or LDAP application to manage users and user groups. If you have any questions, post them in the comments below or in the Working with BIRT iHub forum. -Jesse

Read More

How to Add Custom Visualizations in BIRT iHub 3.1

OpenText recently released BIRT iHub 3.1, the latest version of iHub. The release adds several features, including a REST API and support for Custom Visualizations. In this post, I will explain what custom visualizations are and show you how you can include third-party visualizations in BIRT content with essentially no coding. Custom Visualization Basics Data visualization helps you quickly identify valuable information in your data. iHub includes many data visualizations out of the box, including charts, maps and gadgets. Custom Visualization support extends iHub’s visualization capabilities by enabling developers to integrate third-party visualizations into BIRT content through the use of external JavaScript libraries. This is accomplished by marshalling BIRT Data Objects for consumption by the various third-party visualizations. To invoke a third-party visualization, look for a report item called “Custom Visualization” in iHub 3.1. As you can see in the image below, the graphical builder for custom visualizations uses the same style of interface as other report items to select, group, sort, and filter data before binding it to a visualization.   Out of the box, iHub 3.1 includes 16 pre-built templates that leverage third party visualizations, including templates for Google Maps, Highcharts, Fusion Charts, and D3, that enable you to include those visualizations in your design with minimal coding. In fact, the majority of these templates only require you add the relevant column bindings into the script. However, the templates are  flexible and may be customized if you need to modify them. Additionally, you are not limited to using only the 16 templates we provide; almost any external JavaScript visualization , including Google Charts, ChartJS, and many more, can be added to a report design. (A list of possibilities and sources can be found on this Wikipedia page.) You just need to perform more of the coding yourself to create a new template that leverages your desired visualization library. Creating Your First Custom Visualization To create a custom visualization, you need a BIRT Data Object to use as a data source. For this tutorial, I will use the Classic Models Data Object that comes with BIRT Designer Professional. As shown below, Classic can be found in the directory of your BIRT Designer Professional installation.   Once you locate your Data Object, return to your report design and create a new Actuate Data Object Data Source that points to Classic Then, add the Classic Models Data Model from the Classic Models Data Object, as shown below. You now have everything you need, data wise, to add a custom visualization to your project.   Locate the Custom Visualization Report Item in the Palette and drag it into your report design. The Custom Visualization Editor dialog (shown below) will launch automatically. Begin by selecting the Data Set that you want to use – for this tutorial, that’s the Classic Models Data Model that we added previously.   Once you have selected the Data Set, the Data Binding dialogue will launch automatically. This is where you select the desired columns to bind to the custom visualization. As shown below, I have selected to use the Order Date and Quantity Ordered columns for this example. Make note of the exact names of the columns you choose.   Next, select the Template tab within the Custom Visualization Editor, as shown below.   Pull down the Choose a Template menu to select your desired template. As you see below, I have selected Calendar Chart from Google Charts. This visualization is used to show activity over the course of a long span of time in order to display quantity variances based on the day of the week. This allows you to quickly discern any patterns that may exist based on the day of the week. Notice that there is a Config object within the template containing two values with <changeme> specified, numberColumn and dateColumn. (They’re in purple below.) These are the two columns from the Data Set that provide the data for the custom visualization. The JavaScript templates consistently use <changeme> to mark the column names you bind to the visualization.   For the numberColumn, replace <changeme> with Quantity Ordered. For the dateColumn, replace <changeme> with Order Date. (These are the column values we chose earlier.) You have now added everything needed to display Google’s calendar chart within your report design. Select OK to close the Custom Visualization Editor dialog and add the custom visualization to your  report design. Save the report design, then run the report in the Web Viewer, as shown below.   With essentially no coding, we have added this custom visualization to the report design. Some of the visualizations will have more than two values that need to be changed. However, the basic process for using any of the out of the box templates is essentially the same. Learn more about custom visualizations and other capabilities we’ve added in the BIRT iHub 3.1 Technical Summary of New Features. Thank you for reading this post on custom visualizations in BIRT iHub 3.1. If you have any questions, post them in the comments below or in the BIRT forums. -Jesse

Read More

Under the Hood – BIRT iHub F-Type: Troubleshooting

Welcome to the third installment of the Under the Hood – BIRT iHub F-Type blog series. Today, I will discuss troubleshooting practices in a iHub environment. I’ll share a process flow for isolating issues, offer details about using log files to investigate issues, and suggest a few tips and third-party tools that can make all the difference when troubleshooting. Isolating an Issue When troubleshooting, the first thing to do is isolate the issue as much as possible. This limits the number of areas you need to investigate, which in turn reduces the time required to determine the root cause of an issue. Most issues fall into one of three areas: design issues, server issues or web issues. To isolate an issue into one of these three areas, first ask this: “Did the report run properly in the designer?” If the answer is no, you have isolated the issue to the design, and it should be resolved in the Report Designer. If the answer is yes, then you can remove the design itself as a source of the issue and  focus on the server and web areas. Determining if an issue resides in the server or web areas can be a bit trickier. However, keep in mind that web issues are less common than server issues, so it makes some sense to eliminate them first. There are a couple of steps you can take to quickly determine if the issue is in the web area. First, try and reproduce the issue with a different browser. I typically test a report with three major browsers, Firefox, Chrome and Internet Explorer. If the issue only happens in one or two of the browsers, you have isolated a browser-specific issue. Then open the debugging tools of the browser with the issue (more about debugging tools below) and inspect the console output. The errors you find here can help you determine whether the issue is due to the browser’s settings or the browser version (for example, if it only appears in Internet Explorer 9). The security and JavaScript settings are a good first places to look for web area errors. If an issue cannot be reproduced in the designer, no browser-related issues can be isolated, and you can’t find other problems in the web area, you probably have a server issue. Investigating an Issue Now that you have isolated the issue to one of three areas, you can begin investigating logs and specific components of the isolated area. Here is how to approach each. Design Issues: If an issue can be reproduced in the Report Designer, then that IDE’s logs are key to determining the cause of an issue. If it is not already enabled, add the Error Log view to your designer. The Error Log can be found in the General folder of the available views in Eclipse. This view provides quick access to errors and stack traces that are thrown by the designer. In some situations, the full log file is more valuable than just the output from the Error Log. The designer’s log file can be found within the .metadata directory of the designer’s active workspace, and has .log as its name. Both the Error Log view and .log file are part of the Eclipse IDE which means anybody who is familiar with Eclipse will be right at home. If you’re not familiar with Eclipse, you will find a plethora of information  about Eclipse logs on the Web. Server Issues: When troubleshooting a server issue, it is important to understand iHub’s processes to determine which log files apply to the problem. If you have not done so already, read through my post about understanding the processes. The diagnostic log files for iHub are located in the AC_DATA_HOME/server/log directory. A log file is created for each iHub process. Understanding the processes will assist in isolating the search down to specific log files. Keep in mind the date and time when an issue occurred (or when you reproduced it) to make sure you are looking at the right entries within the log file. Otherwise, you may end up analyzing the wrong log entries. In the majority of situations, the ihubc log file is where you’ll begin to determine a root cause. This is because the ihubc process is the parent for the majority of iHub processes, and errors will typically bubble back up to it. When in doubt about which log files to analyze, search through them all. Using operating system-level search commands or a third-party tool, you can search all of the log files at once and isolate specific ones that need further analysis. Web Issues: Browser debugging tools will prove invaluable when troubleshooting web issues. In the majority of modern browsers, the F12 key opens debugging tools. (If you are not familiar with these tools, I highly recommend doing a bit of research to understand the tools and their usage.) I prefer the debugging tools in Chrome, and use them on a daily basis when developing new implementations and troubleshooting existing ones. In addition to the browsers’ built-in debugging tools, a third-party tool that captures a browser’s traffic can provide the crucial insight needed to determine the cause of a tricky issue. I will discuss these traffic-capturing tools in the Other Helpful Tools section below. General Tips I have a few additional troubleshooting tips to help you determine the cause of an issue. One question to ask after determining the major area of focus is, “Has the report ever worked?” If the answer is no, dig deeper into the log files for answers. If the answer is yes, this leads to the question, “What changed?” When something that worked previously has stopped working, determining what has changed will almost always help you find the cause of a problem. Another situation I have seen quite a bit is where an issue only occurs for a particular user or environment and not for others. In this situation, determine the difference between the users or environments that work and the one that doesn’t. This will often lead to the cause of the issue. Other Helpful Tools I find these four third-party tools very handy when troubleshooting issues. Notepad++ – This is my text editor of choice when performing log file analysis. It handles formatting in log files much better than the standard Windows Notepad. Seeing the formatting can make all the difference in quickly analyzing a log file. Additionally, Notepad++ enables you to search the contents of all files in a directory. Fiddler – This is one of the best tools for capturing HTTP traffic in your browser. Analyzing this traffic can be the golden ticket for determining the cause of issues at the web level. Wireshark – When it comes to capturing traffic, Wireshark gives you everything you need. If you have done any enterprise-level networking you will be familiar with Wireshark. It can be a bit intimidating at first, due to the vast amount of traffic it captures and its many features for analyzing said traffic. Don’t be scared; there are plenty of great tutorials online to help get you started with Wireshark. TCPMon – This is another tool for capturing traffic, but as its name implies, it is made specifically for capturing TCP traffic. This is particularly useful when working with Information Delivery API (IDAPI) or SOAP traffic. When troubleshooting, keep in mind that there is no magic button to handle every situation and there is an exception to every rule. However, following these steps and practices will help you quickly isolate issues, determine their cause, and work towards a resolution. Thank you for reading this installment of Under the Hood. If you have questions, post them in the comments below or in the BIRT iHub F-Type forum. Other topics in the Under the Hood series: Understanding the Processes Understanding the Primary Configuration Files – Jesse Maze image by 

Read More

Under the Hood – BIRT iHub F-Type: Understanding the Primary Configuration Files

Welcome to the second installment of the Under the Hood – BIRT iHub F-Type blog series. Today, I will discuss the three primary configuration files of a BIRT iHub F-Type installation: acserverconfig.xml, acpmdconfig.xml and web.xml. In most situations in which a configuration tweak is needed, you will work with one of these three files. However, please keep in mind that this not an exhaustive list of all configuration files, and there are situations where you may need to modify a file other than these three. Before I discuss these primary configuration files, please remember to always make a backup copy before you modify a configuration file. A backup can mean the difference between the extra work of trying to restore the contents of a file and a quick rollback to the most recent working version. 1. acserverconfig.xml – This configuration file uses XML version 1.0, UTF-8 encoding, and is structured just as one would expect for a standard XML file. The root element is Config and its child elements are System, Templates, ResourceGroups, Printers, MetadataDatabases, Schemas, Volumes, FileSystems and ServerList. Of these child elements, I will discuss in detail the System, Templates, and ResourceGroups elements. In most scenarios, changes should not be required or made to the MetadataDatabases, Schemas, Volumes, FileSystems and ServerList elements. Note: Any changes made to the acserverconfig.xml requires a restart of BIRT iHub for changes to take effect. System – The majority of the attributes of the System element should not be modified from their default settings. However, there are two exceptions I would like to discuss in detail: DefaultLocale and DefaultEncoding. Depending on the region where BIRT iHub is installed and maintained, these settings may need to be modified to align with the regional or company standards. DefaultLocale follows Java standards for its naming convention, so if you want the DefaultLocale to be “English – United States,” the value should be set to “en_US”. DefaultEncoding, as its name indicates, is the default encoding type to be used and inherited on the iHub. Depending on the installation and requirements, you may need to provide a different encoding type such as “utf-8″. I would not recommend changing the default encoding unless you determine that an issue is caused by the encoding type. Templates – Four different templates are configured within this element: small, medium, large and disabled. Only one template can used at a time by BIRT iHub. By default, the small template will be selected for a BIRT iHub F-Type installation. You can determine which template is currently in use within the acpmdconfig.xml; this will be discussed later in this article. Within each template are quite a few child elements, all of which have multiple attributes. In most situations, the majority of these attributes do not need to be modified. The values which most often may need to be modified are the StartArguments for the various resource groups. These are the start arguments for the JVM that hosts the various resource groups processes, and they use the standard syntax for JVM start arguments. One of the most common changes to the start argument is an increase in the maximum heap size (-Xmx) for a particular resource group. The small template is configured with a default maximum heap size of 512 MB for all of the resource groups. Any modifications to the heap size should be done on an as-need basis and within the resource limitations of the environment. ResourceGroups – There are very few situations in which you need to modify the resource groups, but I will discuss them briefly because it’s good to understand them. There are five resource groups that correspond directly to the resource group settings in the templates, based on the name attribute. Settings changes for the resource groups will almost always take place in the ServerResourceGroupSettings within the template, and not in the ResourceGroups directly. The “Disabled” attribute is the one you may need to modify. In most situations it should be left with the default setting of “false” so the resource group is enabled. However, if a particular resource group is not used or you want it to not be available, this attribute should be changed to “true”. For instance, you want to prevent background jobs from running and you want to disable scheduling, set the “Disabled” attribute in the BIRT Factory resource group to “true”. 2. acpmdconfig.xml – This configuration file contains settings for the shared environment variables, internal SSL settings, SOAP endpoint information, disk thresholds, the embedded Tomcat, ihubc and iHub processes. It also controls the capacity template selected from acserverconfig.xml. In this post I will focus on the environment variables, embedded Tomcat, some of the processes and the disk threshold settings. As with the acserverconfig.xml, any changes made to the acpmdconfig.xml required a restart of the iHub to take effect, and a backup should always be made before modifying a configuration file. EnvironmentVariables – As the name implies, this element contains the various environment variables that are shared with all BIRT iHub processes. Of all the environment variables, the three that I highly recommend memorizing are the AC_SERVER_HOME,  AC_DATA_HOME, and AC_CONFIG_HOME. AC_SERVER_HOME – As the name describes, this environment variable points to the home installation directory of BIRT iHub. That directory contains all of the various sub-directories, including bin, data, etc, jar, shared and tools. AC_DATA_HOME – This is where the majority of BIRT iHub log files will be written, so if you need to locate a log file, this is where to start. AC_CONFIG_HOME – This points to the location where the acserverconfig.xml is stored, as well as some of the files used for email notifications.  Embedded Tomcat – As discussed in my previous blog post, the process name associated with the embedded Tomcat is ihubservletcontainer. Of its various attributes and child elements, the ones that most often need modification are the CmdArguments and log settings. As with the resource group settings in acserverconfig, the CmdArguments are the arguments passed to the JVM that hosts tomcat. It accepts standard JVM arguments and syntax. The log directory and log output pattern can also be changed by modifying the LogDir and LogPattern attributes respectively. iHub Process – Although no modifications  to the settings for the iHub processes are required in most cases, it is good to know where to go if you decide that a change is required. The most likely changes relate to start arguments for the JVM, such as increasing the maximum heap size. As with the embedded Tomcat, the CmdArguments attribute contains the JVM start arguments and follow standard syntax. ihubc Process – The one main takeaway I want to emphasize about the ihubc process is that the value specified for type is “native” – not “java” like the iHub process. This is because ihubc is a native binary complied for a specific operating system type, not a Java process, so it does not take Java start arguments. You shouldn’t need to make changes to the configuration of this processes. BIRT Service – The one property to remember about this setting is “CapacityTemplate”. As indicated earlier, acpmdconfig.xml determines which template within acserverconfig.xml is in use, and the value specified for this property is the template that will be used. By default in a BIRT iHub F-Type installation, the value specified will be “small” to use the small template. If you change this value, you must match exactly the name attribute of a template within acserverconfig.xml. Disk Thresholds – There are two elements related to disk thresholds within acpmdconfig.xml: “LowDiskThreshold” and “MinDiskThreshold”. Although these values do not typically need to be modified, it is important to understand what they mean. LowDiskThreshold – Specified in MB, this value indicates the amount of free disk space remaining when BIRT iHub starts sending low disk space warnings to the log files. The out of the box value is set at 300, meaning that if free space drive where BIRT iHub is installed and stores it data reaches 300MB or less, warning messages will begin to appear in the logs. MinDiskThreshold – Also specified in MB, this value indicates the free disk space value at which BIRT iHub shuts itself down. As with LowDiskThreshold, warnings will show up in the log files when this threshold has been reached and the iHub is shutting itself down. 3. web.xml – If you have worked with a J2EE deployment before, you will already be familiar with a web.xml file. Within BIRT iHub, the web.xml file for the embedded Tomcat used in the front-end iPortal is located at “AC_SERVER_HOME/web/iportal/WEB-INF/”. A majority of the properties in web.xml are detailed comments about the property itself and the value specified. I will not go into depth on the properties or values within the web.xml because there are hundreds them. Instead, I want to draw your attention to the existence of this file, and tell you that it contains the servlet configuration settings for the front-end embedded Tomcat that hosts the Actuate Information Console (also known as iPortal). You may have noticed that, in the majority of situations, these configuration files should not need to be modified. Please remember this before modifying the configuration files – particularly in situations where you are unsure of the specifics of the settings or value that is being changed. When in doubt, ask a question before modifying a primary configuration file. The developer forums are the perfect place to ask a question if you are unsure. Changing values when you do not understand their setting or meaning can result in unexpected behavior that may not surface immediately. Whenever modifications are made, I highly recommend adding comments or creating a log with details on all modifications. And one last time, I would like to  emphasize the importance of making a backup of a configuration file before you modify it. If something goes wrong with a configuration file, the quickest and easiest way to restore BIRT iHub to a fully operational state is to restore a configuration file that is known to be good. Thank you for reading this installment of Under the Hood. If you have questions, post them in the comments below or in the BIRT iHub F-Type forum. The other topics in this series are listed below, and the image below that links to the download page for BIRT iHub F-Type. -Jesse Other topics in the Under the Hood series: Understanding the Processes

Read More

Under the Hood – BIRT iHub F-Type: Understanding the Processes

While your customers don’t need to see the inner workings of your app, as a developer, you need to be the master of its parts and processes. It’s time to get under the hood. Hello BIRT community! My name is Jesse Freeman. Although I am not new to BIRT or Actuate, I am transitioning into a significantly more community-centric role. I have spent the last two years working as a Customer Support Engineer for Actuate, specializing in the server and designer products. I am excited to bring my product and support knowledge to the larger BIRT community. I come from a Java/JavaScript background and am a big fan of multi-platform, open source and open standard technologies. I am an advocate of Linux operating systems and have used or dabbled with the majority of the larger Linux distributions. In particular, I am a big fan of Arch Linux and CentOS. Over the next several weeks I will publish a series of blogs that will bring my support knowledge to the community. The series will include posts on understanding the BIRT iHub F-Type’s processes and configuration as well as troubleshooting. This series will provide technical insight for anybody who will be configuring and/or maintaining a BIRT iHub F-Type installation. BIRT iHub F-Type is a free BIRT server released by Actuate. It incorporates virtually all the functionality of commercially available BIRT iHub and is limited only by the capacity of output it can deliver on a daily basis, making it ideal for departmental and smaller scale applications. When BIRT iHub F-Type reaches its maximum output capacity, additional capacity is available as an in-app purchase. Understanding the Processes The first topic of my Under the Hood blog series is titled Understanding the Processes. When I first started in support, one of the first pieces of information I learned was the breakdown of all of the processes and their specific roles. This information was invaluable for the duration of my time providing support. Understanding the processes and their responsibilities provides insight into how the product works for configuration and integration purposes, and helps us understand where to look for more information if an issue arises. With that in mind, here is the list of the BIRT iHub F-Type processes and their responsibilities: ihubd – This is the daemon process responsible for the initial startup of BIRT iHub F-Type. The ihubd process starts the ihubc and ihubservletcontainer processes.  If issues occur during startup, this is one of the first processes to examine. ihubservletcontainer – As the name implies, this process is the front end servlet container for the BIRT iHub F-Type. This process is hosted out of an integrated Tomcat within BIRT iHub, which means anybody who is familiar with Tomcat should feel right at home when configuring or troubleshooting of the process. ihubc – This is the parent of all other processes started by BIRT iHub,  including the ihub, jsrvrihub and jfctsrvrihub processes.  The ihubc is the SOAP endpoint for BIRT iHub’s communication, the job dispatcher, and resource group manager, and also takes requests from front-end applications such as the integrated Information Console. ihub – The ihub process is responsible for communication with the metadata database as well as the Report Server Security Extension (RSSE) if one has been implemented. jsrvrihub – Within a single installation there may be multiple jsrvrihub processes running simultaneously. A typical out-of-the-box installation will have at least two. One of these two typical jsrvrihub processes is used for the viewing of dashboards and the other is used for execution and viewing of reports transiently. jfctsrvrihub – The jfcsrvrihub process is used for the execution of background jobs on BIRT iHub. This includes any report that is explicitly scheduled to run at a specific time (or immediately) and allows reports to be output to a directory within the ihub process rather than viewed immediately within the current browser session. Whether beginning an installation, working on an integration project, or troubleshooting an existing installation,  this information will assist you with knowing the process that needs to be examined. Thank you for reading.  Subscribe to this blog and you will be first to know when I publish my next Under the Hood – BIRT iHub F-Type series with a review of the Primary Configuration Files. Download BIRT iHub F-Type today so you can follow along. If you have any questions, post them in the comments below or in the BIRT iHub F-Type forum. -Jesse

Read More