Ask Reuben

Keeping Your Support Contact Happy

Any tips for using the support portal? 

When should I create a new case? 

What information should I include in a support case?

With the upgrade to our Support Portal that occurred just prior to the end of the year, it is an opportune time to remind you of the practises that will keep your support contact happy when you communicate via the Support Portal, and lead to faster and more effective resolution of issues and questions you may have.

One Issue per Support Case

Pleas try and keep support cases to be one issue per support case.

When you report multiple issues per case, the comments thread eventually becomes a mess of quoted text and replies as attempts are made to indicate what sub-issue is being commented on in that particular comment.  When this happens the communication not only becomes unclear but sub-issues are lost as what tends to happen is that a sub-issue dominates the conversation.

By trying to stick to one issue per case …

  • communication is clear as to what issue is being discussed
  • communication is not lost as one issue dominates the conversation
  • there is an accurate title per issue
  • when the case is closed, there is a concise accurate summary of the issue and resolution
  • when an engineering task is required to fix an issue, it is more clear that this engineering task is for this particular issue
  • able to close issues as they are resolved

Provide Individual Product Version Information

When proving version information, please don’t supply just the version of Genero Studio.  This does not indicate what versions of FGL, GDC, GBC, GAS, GRE, FLM you are using.

You need to be aware of the individual products in our product suite and you need to be aware of how to get the version information.  This maybe by running a command with -V option at the command line e.g. flgrun -V, httpdispatch -V etc.  There may also be a VERSION file in the products root directory e.g. $FGLDIR/VERSION, $GBC_PROJECT_DIR/VERSION etc, that contains version information inside it.  For GUI tools, this maybe by using the standard way to get a version from a GUI product as per your O/S.  (Help->About etc).

To illustrate, note in the downloads area, the individual products, the different release dates and the different versions shown next to the individual products)

In Genero Studio, there is a semi-useful options Help->Product Info that gives a lot of version information, it is missing the odd piece of information so you maybe asked for more if you copy and paste the output it provides..

For those that tend to supply just Genero Studio version information, I often need to point them at this to get them in the habit of thinking about individual packages.

Check to see if issue has been resolved by us in the interim

There are two tasks you should perform to see if the issue has been reported and/or resolved in the interim.

  1. Search in the Issue Tracker to see if you can find a similar issue.  Learn the nuances of the Issue Tracker to look for issues resolved in particular releases.
  2. Test to see if the issue still occurs with the latest maintenance release

Even if your production sites are not using the latest maintenance release, the expectation is that at any point in time you have downloaded the latest maintenance release and have the ability to compile and run your application using the latest maintenance release.  You are then in a position to test and determine if the issue has already been detected and fixed at our end.

As part of this note occurrences where you see numbers in a yyyymmdd format in our filenames, or in version output.  For example if you see “Build 202311291122…”, the 20231129 equates to 29th November 2023.  If you are using a version that is years old, then you ought to be thinking to yourself, this issue may have been detected and resolved in the interim.  What am I doing differently?

Provide links to what you have read

Occasionally we will see a comment that says something like …

“I have read the documentation but …”

If you do this, please tell us what documentation you have read by providing a link to the section of documentation you have read.

If using the Studio help, you may need to go View ->Toolbars -> Address Toolbar in order to see the qthelp: URL which you can then copy and paste into your support case.

The two most common errors when misinterpreting documentation are …

By providing links we can determine that you have read the right documentation for what it is you are attempting to do.

Define The Problem Clearly

Define the issue clearly.  The best things are a minimal reproducible example or to utilise demo programs.

As I am fond of saying …

Nothing spins a geeks propellor like an isolated reproducible example

… give a developer a simple example and they will look at it wiht more enthisiasm than if you give them 1000+ lines of production code.

I am also a big fan of the Swiss Cheese Model.  Ask yourself what am I doing differently than the Four Js developers, and the users of Genero who have used this product before me.  What is the extra layer of swiss cheese I am providing that causes the holes to line up and the issue to become apparent?

With Code Examples Consider …

The following in code examples often result in a request for additional files to be sent …

  • A 4gl or .per with LIKE and use of SCHEMA, but no schema file attached to the case
  • Pre-processor &include file or IMPORT [FGL|JAVA] syntax but these files not included
  • Changes made to shipped files such as FGLDIR/lib/default.4st but not providing us your FGLDIR/lib/default.4st

… try to remember to include them in the first instance.

Test With Standard

Where you have utilised some customisation such as GBC Customisation, please test against using the standard .  So for example, if you have used GBC Customisation, test against a standard GBC runtime.

Doing these sorts of tests help determine where the problem lies.  If a rendering issue occurs with your customisation and not our standard then we can start looking at your GBC customisation, not the 4gl code.

Capture Information

There are a number of log files and debugging options for the various products.  These include …

The log files are not just for our benefit.  We expect our community to be aware of these options and to have tried to do some analysis from them before reporting an issue.

Don’t clip logs

Log files can be large.  You may think you are being helpful by clipping a log file to contain just the error message.  However often the important information in a log file is …

  • what is at the beginning as it includes version and environment information
  • what is at the end as it tells us if the process terminated normally or abnormally
  • the lines immediately prior to an error

If the log file is too large to be attached to a support case, communicate with the support contact and make arrangements to send a large file via some other technique such as dropbox, wetransfer.

Please use the Code and Quotes options when editing case

The updated portal editor is more WYSIWYG.  The ability to enter quotes and code has been improved. You no longer have to remember cryptic markdown when editing comments although some do still exist if you don’t want to click toolbar icons.

Please Respond Promptly

If you don’t respond in a week then the message that gives is that the issue is not important to you.

Don’t send screenshots of Code, Log Files, and Error Text

This point can be illustrated by the simple example below, which of these below can you copy and paste into your code editor, the code snippet or the code screenshot  🙂

If you send a screenshot of code then we cannot copy and paste it into our editor, nor can we search on it.  So either attach your code file to the case, or copy and paste from your source files into the support portal comment editor.

With log files, the important thing is being able to search on it so we can find other instances of where that content of the log has appeared.  Again a screenshot of a log file does not allow us to search on the text inside the screenshot.

In the case of an error message, it is normally good to receive both a screenshot and for the error message to be typed into the support case.  A screenshot helps show where the error message appears and provides good context.  Copying and pasting the error text into the portal ensures that it can searched on.  Text inside screenshots does not appear in search results!

   DISPLAY "Hello World"

Avoid doc, ppt and pdf

If you type up a summary of a case and send it to us as a Word Document, Power Point presentation, or PDF whilst we can no doubt read and understand the issue, our search indexes do not go inside the file.  This not only hinders our ability to search for previous cases that had the same issue, but it also hinders your ability to search in the support portal to see if you have reported the case previously.

The preference is for you to type the issue into the support portal.  The search indexes are comprised from the text that can be found in the Title/Summary field, Detail field and Comments.

Please tell us how the issue is resolved when closing an issue

If you report an issue and we reply with a solution, rather than just silently moving on, please inform us so that we can close the case, and please tell us what solution you went with.