Issue Management Approach in software Integration

Here is a simple method or approach for an end to end issue management in software integration or installation. It can be used by integration consultants, support personnel, vendor teams and even customers to ensure a higher level of quality in issue resolution.

Definition

An issue arises when the behaviour of software/solution that is unexpected and results in an undesirable outcome. Or an outcome that was not an agreed test case or within scope. note this does not necessarily mean that items are failures, it may conclude successfully but not reach an agreed or desired outcome.

Source

issues are items that arise one of two ways

user (customer) encounters an issue while using your software
vendor – identifies an issue due to something reported by other clients or during investigation of other reported issues or even during routine maintenance

Approach

There are a number of steps that can be used to achieve the desired outcome

Background

It is essential to capture the background, what the customer was doing, not doing, how was it reported, in what context, location. how often does it occur, to how many users? some of the other specific things to consider are:

Current configuration: conduct an analysis of the current configuration, identify connected systems, any events in the context
Last known good: seek the last known good, this is important as urgent steps may be necessary to preserve backups as they may be deleted soon, or it provides a good starting point to look into what might have caused the issue to emerge
Any Recent changes: seek out any recent changes to the solution it self, or the context, such as did server get patched, were there recent maintenance tasks
Clients view of issue: this is an important one and one that is commonly overlooked, either because consultants believe they are the experts or that the client buries their views deep inside a lot of technical logs or observations. if it is not listed in the request, return back to the customer and ask if they have any thoughts on what might have caused the issue. even if the customer has documented it in the report, it might be useful to have a call/meeting to discuss it further to ensure that the consultant understands the issue at hand. this can be achieved by the consultant re-writing the issue reported in their own words and asking the customer if they have understood it correctly. Often assumptions made at this point lead to expensive investigations and time wastage later.
Replication: request the steps necessary to replicate the issue. often a step that is overlooked is whether the issue is replicable. sometimes it is easily replicable, in which case there are a number of items to consider. if it is replicable in the test environment then it could be an underlying software issue, if not replicable then it might be related to something in the customer context, such as configuration for that particular customer, integrations or even restrictions between test and production environments. simply replication tests can be done in local test, customer test and customer prod environments. if not permitted access to the prod environments a recording may suffice as replication steps

Financial impact

(optional – usually applicable only if you are a software vendor): this is a good juncture at which to also decide if the work is chargeable or not. is it out of warranty? was it part of the original scope? it doesn’t necessarily mean it is a bug even if the system fails. responsibility lies with the customer to ensure that adequate acceptance testing is conducted for all tests within warranty periods. It is better earlier on to have the discussion around whether the work is chargeable. it may be an option to provide the customer with an estimate and then a final quote once the actual fix has been identified. a smart way to do this is by seeking a commitment by the customer to pay an initial amount to cover the investigation, which can then be varied depending on the actual effort to implement the fix. the underlying reason for this is that during initial investigation, the consultant may find and implement a fix and it may be difficult at this point to retrospectively request payment for work done.

Hypothesis

this is another step that is often neglected, or done instinctively. it is common to see consultants hypothesise a root cause and immediately commence investigation. but it is recommended that a minimum of three hypothesis are developed and written down (unless it is glaringly obvious what the issue is or it is a known issue), each hypothesis is assessed based on potential effort vs a likelihood of being the cause of the problem. this assessment outcome can be used to score or prioritise the resolution process, but it is absolutely essential for communication. it is also important to note that if new hypothesis are made along the way during the investigation, they should be added to the list, even if they end up being tested or not. this further improves knowledge capture and subsequent investigations of similar issues. overall as a first step always assess whether this is a known issue or not, if known the first step should be to try the replication steps and resolution steps to confirm. this might short circuit trying to do the whole thing from scratch.

Capture

It is important that all work is captured along the way, this provides an evidence trail of the investigation, for later use, but if a resolution is found along the way, it is useful for replicating the resolution steps without trying to remember them. Lastly, in the event that new bugs are introduced it is useful as any changes made during the investigation can be reverted.

Communication

This is also a step that is often ignored, most times a consultant will do all the capture actively with the customer and then suddenly disappear into a black hole to surface later with either a solution or next steps. often this process takes days or longer. this often causes customers to disengage from the process and product. most times the reporting customer is not the end user encountering the issue, so they often have stakeholders to keep updated. so it is recommended that the customer is briefed on the hypothesis, estimated timelines and a commitment is made to brief them on a regular basis with either progress or immediately with success which even comes first. this helps the consultant control the narrative. the level of depth to which the briefing goes depends on how technical the customer wishes to be. all this may be unnecessary if the resolution process is being carried out with the customer, but note that there are always stakeholders that are not part of the process and having a common message is essential for managing stakeholder expectations, so it might be a good idea during the customer view conversation to ask who the impacted stakeholders are and agree on a communication approach/frequency/template(format)

Final resolution

once a resolution is found, steps to implement should be documented, and depending on where testing occurred (for example local environment) then it should be retested in the customer environment, and if successful, then appropriate release management documentation and approvals sought prior to releasing into production.

Client Testing and acceptance

It is common to only test the reported use case during acceptance, however it is recommended that testing scope is extended through random sampling to ensure that the fix has not introduced new bugs. commonly this is at 30% testing and expanded if errors are found. Once fully accepted in test environments,

Review and next steps

Once the fix has been fully implemented and signed off, all that is left is wrap up. this involves key activities such as listed below

seek client feedback and satisfaction: in addition to client acceptance of the implemented change it is essential to seek feedback from the customer on the way the issue was handled
update knowledge hub: if any new knowledge regarding the product and the client specific configuration has been identified, it needs to be added to the knowledge hub. either to the core knowledge of the product, generic knowledge regarding that client group or specific knowledge about that client itself.
update processes: in addition to the ‘what’, the ‘how’ may need to be changed as a result of the recent implementation. if an approach or method was used but modified to solve the problem. this needs to be updated either permanently or as a variation for that client/group.