This document contains DRAFT material intended for discussion and comment by the InCommon participant community. Comments and questions should be sent to the InCommon participants mailing list.
Best Practice
- Error handling is integrated into the look and feel of a site.
- Contact information and reporting procedures are provided that lead to problem resolution.
- Errors resulting from correctable or avoidable user actions are presented in a fashion that leads to self-correction.
Federation software in most cases comes equipped with a default error handling experience that is limited in scope:
- The look and feel may be generic and lack visual coherency with an IdP's or SP's "standard" content.
- Error messages may be overly technical and lack context, or fail to direct users toward appropriate resolution strategies.
- Appropriate support contacts may be missing.
In short, out of the box error handling is functional, and helpful in debugging, but is typically lacking in providing a professional and appropriate experience for users of an IdP or SP.
Before moving to a production state, deployers should take steps to address these deficiencies. Obvious steps:
- Plug in your site "look and feel", style sheets, logos, color scheme, etc.
- Direct users towards appropriate points of contact to report problems, along with instructions for doing so. SPs should take care to "own" their services; federation is not an excuse to offload application support to partners; your service will never be well-supported by help desk staff who know nothing about its features, requirements, or diagnostic aids.
- Use relative links to embedded content; make sure all access paths into error pages produce appropriate results and not broken image icons or missing style sheets.
A less obvious, but important, step is to explore different error conditions in your federating software and/or application; consider what problems are likely to recur in production and how users ought to be advised to proceed. Often this will be best handled by translating overly technical messages into customized responses in plain language that lead users to solutions; most software will provide the capability to do this. Even if error message testing breaks after upgrades, a deployment is no worse off for having improved the experience in the meantime.
For example, consider how bookmarks of various kinds, or use of the back button, influences results. Turn those useless messages into a straightforward warning about these features.