Handling UI interaction when working with web services
Whether you're publishing or consuming web services, exceptions and dialog boxes that might be displayed while code runs must be handled correctly. Exceptions must be handled to prevent the system from ending the web service client execution. You can handle exceptions in the following ways:
- Writing conditional code inside Business Central.
- Writing the code in the web service client application.
The most robust solution is to use both methods.
Publishing web service endpoints
When publishing a web service endpoint, you must make sure that the AL code that you're publishing doesn't assume the ability to interact with a user through the UI. You can use the GUIALLOWED Method to suppress UI interactions. For example, you can use this method to determine whether a codeunit is being called from the client or from a web service client. You must make sure to suppress errors when a codeunit is called from a web service client.
When implementing a conditional code check-in Business Central, you should implement the check only around code that could cause an error. You shouldn't encapsulate the whole business logic.
Note
The server returns the following exception when trying to invoke a dialog UI through a web service call or in a background session: NavNCLCallbackNotAllowedException: Callback functions are not allowed.
AL methods that throw exceptions in web service endpoints
Variables of the Dialog data type or any of the methods listed as dialog methods can cause "callback not allowed" exceptions when they're called from a web service call or a background session. The Message Method (Dialog) is the only method in this category that doesn't cause an exception.
The following table describes how dialog boxes are handled in a background or web service session, which has no UI.
| Method that creates the dialog box | Behavior |
|---|---|
| Dialog.Confirm | - Dialog box is suppressed. - The following error occurs on the Business Central instance: Business Central attempted to issue a client callback to show a confirmation dialog box. |
| Dialog.Error | - Dialog box is suppressed. - AL code execution ends. - The error is logged to the event log of the Business Central instance. - The error is added to the Comments field of the Session Event table. Note: Stopping the main codeunit with Dialog.Error('') is considered a successful operation, so the failure codeunit isn't executed. |
| Dialog.Message | - Dialog box is suppressed. - The message is recorded in the event log of the computer that is running Business Central instance. The log entry has type Information and includes the context of the message. |
| Dialog.Open | - Dialog box is suppressed. - Dialog box text is not displayed or logged. |
Other AL methods that you shouldn't use in web service endpoints or background sessions are:
- Page.Run
- Page.RunModal
- Activate
- Report.Run
- Report.RunModal
- Hyperlink
- File.Upload
- File.Download
You should also avoid operations on client-side Automation and .NET Framework interoperability objects.
Consuming web services
You must handle exceptions in client code that calls a Business Central web service. Appropriate exception capturing code should be included around any call to a Business Central web service.
For more information about common HTTP status codes and how to deal with them in your client code, see Troubleshooting web service errors.
See also
Troubleshooting web service errors
Web Services Overview
Publish a Web Service