Developer Handbook
Developer Handbook
Handbook
__
1/10/2020 1
Contents
__
1. About this handbook
2. Overview of support
3. Contact Information & Checklist
4. Expectations of Developers
5. Case Management & Lifecycle
6. Support polices & Tools
7. Support Downloads
8. Defect Resolution Process
9. Escalation Process
10. Feedback & Product Improvements
11. Appendix & Useful links
Developer Handbook 2
01 About this
handbook
Developer Handbook 3
1/10/2020 3
This handbook provides insight into Developer Support and
About this enables you to quickly identify helpful information you may need
when contacting the Developer Services Team.
handbook It will help set expectations and allow you to plan how to best
serve our customers. Acting in accordance with its contents will
__ help us support you as efficiently as possible to meet your
business needs.
We hope and expect that your relationship In order to provide you with a quality service, we would ask that
you and anyone across your business who uses support read this
with Sage will last many years. This document and adhere to the outlined procedures and guidelines.
Developer Handbook introduces you to the
Developer Services Team and provides This handbook describes and covers support available
for the following software:
guidance on making the most of your
• Sage 50cloud SDO
contact with us. • Sage 200c Professional SDK
• Sage 200 Web APIs (Sage 200c Standard and Extra)
• Sage 200 CRM APIs
• Sage Accounting Web API
Developer Handbook 4
Business Partner Handbook 4
02 Overview of
Support
Developer Handbook 5
1/10/2020 5
However, sometimes the software does not If your customer is not on the current release, we would
updates along with advice on installation as and Where a problem is intermittent and immediate diagnosis
when they become available. is not possible, or non-defect-related issues adversely
Confirmation of fault cases and provision affect the software, appropriate advice, assistance or
As legal and fiscal requirements alter, the product workarounds will be provided.
of program fixes and workarounds.
may require enhancements to take account of
these changes. Sage will provide these changes, Sage’s maintenance policy covers the current release so
Sage operates under a Quality Management as they become available. The customer should you should always test any potential issues in the SDK
System, within which it makes every effort to ensure that these enhancements are installed in a for the latest version before contacting us.
supply defect free software. timely manner.
Our Product Terms and Conditions are available on our
Should you encounter a problem with the software, website, click here
we would expect detailed replication steps to be
submitted in order for us to formally report the issue
as a defect.
Developer Handbook 6
Business Partner Handbook 6
Standard
In every case, it’s important that you help us to reproduce your problem as well as understand what
Support you’re ultimately trying to achieve and why. This can help us work around limitations or provide
alternative solutions for you and our customers making it just as important to provide explanations with
__ your code samples.
In order to retain the integrity between you and your customer we do not provide direct support to your
customers. We would always involve you in any dialogue with your customers.
The Developer Services team
provides support for developing The Developer Services team reserves the right to decline support to any member who does not have
the required development experience or who conducts themselves in an unprofessional manner towards
professionals who are working
members of the Developer Services Team.
with the Sage Software
Development Kits (SDKs) and APIs. Sage is committed to providing world class service in line with our values and corporate vision and we
appreciate any feedback you can provide.
Developer Handbook 7
Business Partner Handbook 7
03 Contact Information
& Checklist
Developer Handbook 8
1/10/2020 8
Availability
In order to provide the most efficient service to you our support is accessed and
Support provided primarily via Case Management. When using this service, you should include
all the information in the checklist on page 10 to avoid unnecessary delay. This service
can be used for:
Email: [email protected]
Developer Handbook 9
Business Partner Handbook 9
Information required when contacting Support
Contact When you contact Developer Support, please provide the following information:
Checklist •
•
•
Your company name
Case Reference (for ongoing cases)
__ •
Any password on the account
The exact name and version number of the product you’re working with
• Full details of the problem including all errors, exceptions and traces captured along with steps
You must perform your own troubleshooting which allow us to reproduce where applicable
prior to calling us to establish if the issue is • Full details of any error messages you are receiving
• A complete understanding of the impact this is having on your customer and why (see: the Business
data, program or environment specific.
impact section)
Developer Handbook 10
Business Partner Handbook 10
04 Expectations
of Developers
Developer Handbook 11
1/10/2020 11
01.
Expectations 08.
Prepare
02.
__ Feedback
Use
Available
Resources
We expect all of our Developers to have
familiarised themselves with the following
prior to contacting us.
03.
07. 09. Appropriate
Follow Up Behaviour Trouble
shooting
06. 04.
During the Support
Case Boundaries
05.
Code
Examples
Developer Handbook 12
Business Partner Handbook 12
01. Prepare 02. Use Available Resources 03. Appropriate Troubleshooting
• Create a My Sage login for sage.co.uk Before contacting us please ensure you have You must perform your own troubleshooting prior to
(Article 35944) reviewed all digital collateral online before contacting us to establish if the issue is data, program or
• Maintain your My Sage login on regular raising a new case. This includes: environment specific and it is essential that you let us know of
basis
any fault finding/ problem solving processes you have carried
• Ensure you have copies of the software • SDK help files
for testing, that mirror what your • Developer Forums out so far. These are guidelines only, but will provide structure
customers use • Ask Sage around your troubleshooting methodology. If there has been
• Define a strategy for knowledge • Downloads - Full version downloads including insufficient troubleshooting carried out we will recommend
collection and knowledge sharing within runtimes, service packs, SDKs, and further work is undertaken by the Developer before
your business. Developer Tools commencing with the case.
• Define a strategy for sharing knowledge • Tech Tips - Tutorials and guides broken down
learned from Sage training courses. by product area • Is your code based on a help file example? Does the
• News – Latest news, important updates, original still work?
software release dates
• What happens if you try your code in a different
• Training material - webinar videos
assembly?
• Case Management – log new cases and
update existing ones with the support team • Is your project targeted to the correct .NET version and
CPU architecture?
• Have you checked the available help files?
• Have you isolated the line of code that’s causing the
unexpected results?
• What exceptions are appearing and do you understand
the details?
• Can any of your colleagues assist you?
Developer Handbook 13
Business Partner Handbook 13
04. Support Boundaries
The following lists are a quick guide to give you an idea of our support limitations. It is not exhaustive but is intended to help you understand
how we can support you with meeting our customer’s needs:
SUPPORTED: UNSUPPORTED**
• Advice on accessing and setting up SDK tools • Installation queries – these are supported by our Technical Support Team
• Potential issues or defects with SDK • Functionality questions – these are supported by our Business Partners, or your
• Reproducing or integrating with existing functionality Sage Support provider
• Advice on how to isolate an issue for troubleshooting/debugging • Information available through self-service options such as in-product helpfiles, Ask
• Integration and/or customisation using SDK and where appropriate Sage, support website, etc.
• Report Designer API • Basic troubleshooting as outlined in this handbook
• Sage SDO • General development queries which are not specific to our SDKs
• Sage One API* • Bypassing business logic for direct data/SQL manipulation
• C# and VB.NET are supported • Debugging your application for you
• With Sage 200 CRM, we will also support JavaScript/Jscript, jQuery • Producing code examples which require no specific knowledge of the SDK
and Classic ASP and client-side scripting (Sage CRM .NET API only • Producing code examples for non-developers
supports C#) • Unsupported or incompatible operating systems /environments
• Web APIs for Sage 200 Standard and Sage 200 Extra* • 3rd Party Add-ins
• Report Designer
*For Web APIs, we don’t support any specific languages, we only support • Standalone CRM (Except in cases of the Connector)
the endpoints • ODBC
• IIS/Web Services
• Sage Modules that do not have any SDK e.g. Manufacturing
**For queries we don’t fully support, we encourage you to make use of the Forums to
interact with other Developer Programme members as you may find your answers there
Developer Handbook 14
Business Partner Handbook 14
05. Code Examples
Our documentation contains tested code examples which will help you replicate most of the common functionality in the applications. You will occasionally wish to
replicate some behaviour which is not already covered in the documentation. In this case we will endeavour to provide you with a custom example if it is appropriate.
For this reason, we will factor our code so that it is easy to follow rather than most efficient. Please remember that all code examples are illustrative and are not
guaranteed to be production safe. It is your responsibility to fully test any software written using our code examples.
Where possible we will opt to provide pseudo-code examples to highlight how you might approach the problem as a developer rather than produce a full, working
example.
We will often ask to see an example of your code which shows your problem. So we can support you as efficiently as possible, we’ve provided some guidelines to ensure
we can spend our time focussing on your issue:
• Please include helpful comments to show what the code is intended to do. This helps us quickly navigate the structure of your program and will make our
investigation more efficient. You do not need to comment every line but generally, it should be clear what your code is doing from your comments alone. Similarly,
variable and method names should be descriptive and meaningful.
• All examples should be complete, self-contained, and buildable. We will often need to work through the code to troubleshoot so we need to see all variable
declarations and values set.
• Programs should be as simple as possible and just enough to show the query you have while being free from unrelated information. We rarely accept full projects
and source code for investigations and would typically expect you to isolate the issue before contacting us as part of your troubleshooting.
• Code should be sent in selectable text and not as an image. Microsoft Visual Studio users may wish to install the popular “Productivity Power Tools” extensions from
Microsoft as this will preserve the colour-coding of your theme when you copy and paste code.
• Include screenshots if they help. Although we need your code as text, please send in screenshots which show any supporting information such as error messages.
• All code should be accompanied by a description of any assumptions which have been made, and/or any data configuration changes which need to be made to
allow the code to run.
• Code should be accompanied by a description of the desired outcome of running the code successfully.
• Providing as much information to us in your initial contact with us will ensure there is no delay in the progress of your case.
Developer Handbook 15
Business Partner Handbook 15
06. During the Case 07. Follow Up
• Wherever possible keep one main contact throughout the lifespan of an • For any cases on a status of solution given our system will
case. send 2 chase emails and then a closure notification. We
• Please refrain from creating duplicate cases for the same query as this would ask all our business partners to let us know if the
adds confusion and may slow down our response. solution provided resolved the problem, if not what the
• When asked to provide answers to questions regarding your query or alternative solution was. This will assist us in helping you
problem, please make every attempt to fully supply the technician with the and your fellow business partners in the future.
detail required. • For cases on a status of more info we cannot progress the
• House keeping comments will be appended to your case where the answer case without information from yourselves. The system will
is available in our digital material or insufficient troubleshooting has been send 2 auto chase emails and then a closure notice.
performed. These comments will be used to analyse a developers • The team may send you a reminder or chase email
performance. themselves in order to progress the ticket rather than wait
for the automated chase to go out.
• We would ask all Developers to give us the information we
need to progress as quickly as possible
08. Feedback
• It is important to us that you complete the surveys with detail in the
comments box whenever possible, adding further information to support
your scores. 09. Behaviour
• The information is essential in helping us to understand what went well • We are here to work in partnership with you. Remember,
during the life cycle of an case and where we can improve. We we’re all here to service the customer and we should all have
appreciate all comments and ensure that they are shared with all their best interests at heart striving for Extraordinary
involved. Customer Experience.
Please treat us as you would like to be treated yourself.
• If you have any further comments and feedback regarding the survey
process, please email [email protected]
Developer Handbook 16
Business Partner Handbook 16
05 Case
Management &
Lifecycle
Developer Handbook 17
1/10/2020 17
Raising a Case
__
Raising a Case
When raising a new case you will be required to submit a priority level along with
a full business impact. You can change the priority of a case at any time by
updating your case via Case Management.
It is important you have the right priority level assigned to the case as this will
ensure we have the correct level of focus on your case and it also helps to
prioritise the appropriate resource. To increase the priority you will need to have
your business impact to hand.
Advice on how to establish an accurate business impact for your customer can be
found in Ask Sage article 37063.
Please ensure you have reviewed all digital material online before raising a new
case. This includes Ask Sage, software help files and the Known Issues database.
Developer Handbook 18
Business Partner Handbook 18
The following functionality is available to help you manage your cases:
Online My Cases
View a list of cases raised by all individuals within your company with the option to filter by date, status,
Case product and classification.
View details of each individual case and add additional updates and attachments to them if necessary.
Updates are added to the case immediately to avoid delay between yourself and the technician
Management monitoring your case.
You will require a Sage ID to log in. Once you have saved your case, you can upload any additional attachments that you feel will assist us
with the investigation. This includes any relevant screenshots, log files, reports etc.
Details on how to create/ maintain your
Sage ID are available by clicking here.
Developer Handbook 19
Business Partner Handbook 21
Priority Table
It is therefore important to provide accurate • Involves partial, non-critical loss of functionality of the software/bespoke.
• Some software/bespoke components are affected, but allow the user(s) to continue using
and appropriate information to ensure the Medium Limited Impact the software.
correct priorityis assigned. • Users can reasonably work around such inconsistency or impairment.
*The Developer should have made reasonable attempts to ensure their development and testing work is
Developer Handbook completed in a timely manner to avoid cases being raised with urgent deadlines. 20
Business Partner Handbook 20
Priority Priority Table
(Single or Multiple
Critical cases should be reported via email
with a full business impact provided.
Updates will be
provided every working
day.
Sites)
Updates will be
Depending on circumstances Medium Limited Impact Assigned to a technician within 1 provided within every 7
surrounding the case we working day working days.
may agree alternative update
intervals with you Updates will be provided
Cosmetic/
Low Assigned to a technician within 1 within every 12 working
How do I?
working day days.
Developer Handbook 21
Business Partner Handbook 23
Case This may involve gathering additional information (further code examples,
screenshots etc), recreating the case or liaising, if necessary, with other
If you need assistance at any time during the life of the case, please contact
__ the developer services team by updating the case via Case Management.
Case References
Once the cause of your case All new Cases reported to Developer Services are logged and given a case
reference number. Please use this unique case reference on all
has been determined, the correspondence with us.
technician will identify an
existing solution or continue to If you need to refer to the case through the Case Management utility or
telephone, use the case reference to speed up retrieval of the associated
investigate the case until a data.
solution is found.
You will be provided with the case reference if your case is not closed first
time, however all cases are assigned a unique reference number and can be
provided on request.
Developer Handbook 22
Business Partner Handbook 24
Troubleshooting Business Impact
The pre-requisite prior to contacting Developer One of the most critical aspects of raising an case is to understand the impact that
Services is that standard troubleshooting is carried “non-resolution” of that case would have on you or your customer - we refer to this as
out. This will maximise the ability to progress with the Business Impact.
case as efficiently as possible, therefore minimising
further impact on you or your customer. Without this it is impossible to prioritise the importance of the case and subsequently
the urgency and priority that should be applied. Within any organisation prioritisation of
Troubleshooting is a key skill for any support work is essential, so this should be a fundamental part of your conversation on initial
function; it is therefore imperative that the right contact with your customer.
questions are asked, the relevant information
gathered and then any corrective advice provided. For the same reasons above this is a mandatory requirement when contacting the
Developer Services team.
Developer Services have compiled article 37063
which will help you through this process. These are Below are a number of questions to help determine a business impact and therefore
guidelines only, but will provide structure around your the priority, these are not exhaustive however.
troubleshooting methodology.
• How often is the affected area of the program used?
If there has been insufficient troubleshooting carried • Is it fundamental to a process or part of a wider process?
out we will recommend further work is undertaken by • How many users are affected?
the Developer before commencing with the case. • Are there short-term alternatives to the problem?
• Does the affected area have financial consequences to the business
(people/productivity)?
• Is there a workaround to the problem and is this acceptable?
Please refer to Ask Sage article 37063 for more help and information.
Developer Handbook 23
Business Partner Handbook 23
Case Status Case Status / Description
During the lifecycle of an case we will assign a status to signify the current
activity or state of that case. If your case status is ‘Partner Pending’ and we have Status Description
not had a response to our request for information or to a solution we have
provided, you will automatically receive a reminder email. New Case has just been logged and is awaiting investigation.
If after attempts of sending reminders we receive no response, the case will be Work has started and an investigation is underway but not yet
closed automatically. The table to the right provides an explanation of the Service – Work in Progress complete.
different states an case can be in. We may also close the case manually if we
feel the case has reached a conclusion and have had no reply from yourself More information has been requested by the Support team from the
within a given timeframe. Business Partner/Developer.
Partner - Pending OR
Case Closure
A solution has been provided, Developer services areawaiting
A case will be closed in the following circumstances: confirmation of closure from the Business Partner/Developer.
Developer Handbook 25
1/10/2020 25
Remote Diagnostics Data Software Release
On the very rare occasion that you are experiencing If a particular problem can’t be identified/resolved All software is released via our support website.
a problem that is best observed in real time we offer during the resolution process, the technician may ask Business Partners are strongly encouraged to
remote diagnostic assistance at Sage’s discretion. for a copy of the data if appropriate. bookmark our support site address shown below to
ensure they are kept up to date on the latest
To enable this to function, you will need a PC which Data can be sent to Developer Services via Sage releases, Service Packs and Hotfixes:
can connect to the Internet. This process will involve Dropbox. It is vitally important that the Sage case
you downloading a coded file which, once activated, reference is included as a unique identifier when my.sage.co.uk
will establish a connection between Sage and sending in your data.
yourselves. Please make sure you always review the latest
Please note we do not accept uninvited datasets. documentation that accompanies each release. All
Whilst most queries can be successfully resolved via Data can only be submitted on the request of a documentation is listed in the Resource Centre on
email if you feel that a dial in would be required technician. the page for the product in question
please discuss this with the technician.
Due to system restrictions we may not be able to News & Urgent Information
accept datasets depending on size.
Any additional urgent information we need to
provide, such as details of product releases and
changes in technology will be added to the News
panel on your Developer Dashboard.
Developer Handbook 26
Business Partner Handbook 26
07 Software
Downloads
Developer Handbook 27
1/10/2020 27
Software Release
All software is released via our support website.
Developers are strongly encouraged to bookmark
our support site address shown below to ensure they
are kept up to date on the latest releases, Service
Packs and Hotfixes:
my.sage.co.uk
Developer Handbook 28
Business Partner Handbook 28
08 Defect
Resolution
Process
Developer Handbook 29
1/10/2020 29
Defect Approach
Resolution It is our aim to address such defects in a timely manner based on the
impact the defect has on you or your customer’s business.
Sage operates under a Quality Equally imperative is that an agreement in terms of the priority is
Management System, which makes every reached between Sage and yourselves. Should the priority of the
effort to supply defect free software. case change from when originally logged, it is important that
However, sometimes the software does not Developer Services are made aware of the change (up or down) so
function as designed, which affects the the technician can apply it to the issue.
operation of the product.
Note: It is our policy that we only maintain the current build of the
software.
Developer Handbook 30
Business Partner Handbook 30
R&D Defect Review Process How we prioritise
Every defect will go through an investigation to Defects are prioritised using a number of criteria;
understand root cause, and the approach required to • Priority
correct and the risk surrounding the fix. • No of customers impacted
• Risk
Once the team has evaluated a defect and the • Complexity
possible solutions, it can reveal that pervasive code • Compliance
changes are required. It may not be suitable to
release a solution as a Hotfix due to the level of
testing required, risk to other customers, potential
development work planned in that area for a new
release which would disrupt potential solutions etc.
Where these types of fixes are identified we can only
consider them for a major product release and would
need to discuss all options and workarounds with
you to minimise the impact on you and your
customers during the intervening period.
Developer Handbook 31
Business Partner Handbook 31
09 Escalation
Process
Developer Handbook 32
1/10/2020 32
Escalation Process
For cases that aren’t defects For cases that are defects For product ideas
Should you have concerns about the progress of an All defects are subject to our defect resolution There is no escalation process for software ideas.
outstanding case, in the first instance contact the process. This is because the software is working as designed.
owner of the case to discuss the matter further.
Not every defect can be fixed and may actually Features being enhanced or added, is at the request
Please ensure you have the case reference represent significant risk to our customers and to the of our customer and partner community. Every voice
available. You will then be directed to the appropriate product to resolve them. and business type must be heard so votes and
person dealing with this case. comments on the ideas hub are consulted.
In order for us to escalate a defect for resolution
If you are unhappy with the response you receive details of the business impact are required to ensure Each release of the software includes new features,
from the support team, please contact the team that they are prioritised within our defect fix list details are included within our release documentation
manager who will ensure that your concerns are correctly. and our roadmap is also updated.
investigated.
The defect will then undergo a review by our R&D During development of new features you may be
teams to assess if & how we can rectify the issue. contacted by our team of business analysts who will
David Griffiths explore the feature requirements and use this
Customer Services Manager Where possible we’ll add it to our next product information when we develop the feature.
0191 294 4186 release.
[email protected]
If the priority and business impact is significantly
severe, and where it is technically possible we will try
to deliver a fix for the customer for their version. This
is subject to the product being a supported version
and will not be any more than 2 versions prior to the
latest release.
Developer Handbook 33
Business Partner Handbook 33
10 Feedback &
Product
Improvements
Developer Handbook 34
1/10/2020 34
Ideas Hub (Sage 200 only) Product Roadmaps Satisfaction Surveys
Your opportunity to shape the future of Sage 200 Outlines what's been delivered and what is coming Developer Services are committed to providing
soon. industry leading support. Our company ethos is to
If you believe the functionality of the product can be deliver a valued service to our customers and
enhanced or if you have a request for a new feature, You can access the roadmaps, via this link. partners which we can only achieve with the help of
you can submit your idea via the Ideas Hub. your feedback.
Developer Handbook 35
Business Partner Handbook 35
11 Appendix &
Useful Links
Developer Handbook 36
1/10/2020 36
Essential Links
Area Link
Digital Material
Developer Handbook 37
Essential Links
Area Link
Developer Handbook 38
1/10/2020 38
Essential Links
Area Link
Getting Started
Product Entitlement
Developer Handbook 39
1/10/2020 39
Essential Links
Area Link
Renewals
Developer Handbook 40
1/10/2020 40