Troubleshooting best practices for developers

Summary

This article is intended to provide best practices for troubleshooting and debugging third-party solutions integrating with Sage products.

Process

Description

When developing or maintaining your third-party solutions for alternative software, it is common to encounter various exceptions and issues along the way. This article has been created to provide debugging/ troubleshooting advise to help locate and resolve problems from within your integration, program, environment or data.

NOTE: Developer services do not support the debugging or troubleshooting of your application. Further information regarding the Sage Developer Services support boundaries can be found here.

Code / Add-On Issues

When encountering issues while developing third party integrations the problem is often originates from within your solution. The following section advises how to investigate your application and outlines some common errors and suggestions on how to resolve them.

Check to ensure your code, which is integrating with the SDK, is correct and up to date. Visit our help documentation for official examples.
Is the exception thrown an expected program error or an allowable warning? When running through the same functionality from within the Sage program does the error display? Check the official product help documentation to ensure the error expected.
Is the version of SDK installed, and the assemblies referenced, consistent with the version of the Sage product you are testing against? Check the version and visit our downloads portal to download relevant resources.
Test to ensure the code is at the fault by creating a new clean solution and running the same process/code; does the issue remain?

Data Specific Issues

Certain situations like direct SQL injection, or rare processing events, can cause the data to become corrupt or incompatible. These scenarios can commonly make the program data the cause of problems and exceptions. The following points suggest methods to debug data related issues.

The most common test for data related issues is to try your functionality against a clean company with a fresh set of demonstration data.
Certain users can be configured incorrectly, lack relevant access or also become corrupt. Try your functionality with another user.
Attempt a different transaction or record.
For programs that uses a SQL database, such as Sage 200 Professional, we would recommend running SQL profiler whilst replicating the issue. This will show all of the queries being ran at point of the error, or exception, being thrown and may highlight where the problem occurs.

Program Issues

Exceptions which occur through the SDK can also can caused by underlying issues within core business logic, which is used by both the SDK and the Sage program. The following section advises how to identify if the issue originates in the Sage application. Should you require further assistance troubleshooting issues in the vanilla Sage application we would recommend contacting your support provider.

Are you able to replicate the issue you are experiencing through the SDK within the program? If the issue replicates in the Sage program this may be a known issue or application defect.
Check if the exception has already been documented within our product help or SDK documentation.
Is the product currently undergoing any maintenance? You can track the current status of our services here, along with details of previous outages and any upcoming maintenance.

Environmental Issues

Due to the variation in client environments, you may encounter an issue which can only be replicated on the client's site. It can be difficult to pinpoint exact causes of issues when the environment is a factor, as you may not be able to replicate this on an alternative systems. The following suggestions cover how to identify environmental issues and what could be at fault.

Check to ensure there are no other add-ons installed or running against your software as these may cause issues for your bespoke. If add-ons are present uninstall these and ensure everything is cleared down from the relevant folders. Then reinstall your add-on, testing against a vanilla version of the product to ensure no old files or other add-ons are affecting yours.
Older versions of the product, or other Sage products installed on the effected system, can cause issues because of outdated/mismatched files.
Attempt to replicate the problem on another clean test system with the client's version and database, outside of the production environment, as this will confirm if the client's environment is at fault.
Check if any IT maintenance has taken place in the environment that could have affected the Sage software.
A common issue tightly related to environmental factors is out of memory exceptions. How much memory or processing ability is available on the impacted environment and can you replicate with a machine with more memory available?

Intermittent Issues

Exceptions which are intermittent may be difficult to troubleshoot and to identify the exact cause of; Sage Developer Services require full replication steps to investigate these further.

Often intermittent issues like this are environmental, especially if you only encounter the issue on certain client machines. Please view our environmental issues section for further troubleshooting recommendations.

If you are unable to reliably replicate the issue, we would recommend adding additional debugging/reporting and monitoring the exact actions required to replicate the issue on the affected machine.

Useful Resources

Our API/ SDK help documentation found on our download's portal which covers much of the functionality you will require. We recommend visiting here for all our official SDK examples and walkthroughs.

You can also visit our program help documentation for product information and descriptions on specific errors and why they may occur. Specific product help documentation can be found within your program or accessing via our Help Centre.

Our Knowledgebase is a great source for resolving any issues and has articles on how to achieve specific functionality or handle certain exceptions. Visit our Knowledgebase. We have also produced an index of available Developer Knowledgebase articles which can be found here.

You can also visit our GitHub repository which we upload many of our example projects and solutions we believe would be beneficial to our developer community. Our GitHub is always being extended with new resources and your ideas or solutions are always welcomed.

If you are unable to find answers within our other available resources, we recommend asking our developer community. This forum is the home to likeminded developers with years of experience integrating with the Sage product line; search previously asked questions or post your own.

You can also search or ask questions on Community Hub.

Help and Further Support

We continuously update this article with further content and information. We would love your suggestions on how this article can be improved. Feel free to also contribute to this article or provide any improvement suggestions on our submit an idea form.

If you believe there is a defect with the SDK you can contact developer services by creating a new case.