Automated Error Resolutions

Database Permission Errors

Your instance of Business Central may have customizations or other ISVs which take advantage of event hooks in standard Business Central processes. If those routines access database business objects (tables, etc) that require permissions which have not previously been assigned to the iPayments Entra application, the routine may fail to complete due to this insufficient permission.

The corrective action for this scenario is to identify all of these routines which may be impacted and assign the iPayments Entra application sufficient permission to complete the routines involved.

Here’s a more detailed explanation. When an external system interacts with Business Central, it may do so using a REST API. In these instances, there is no logged-in user, so Business Central must have a user account assigned to the external system that has the correct permissions assigned to it for the tasks that it is to perform. The iPayments Entra application is this “user” account. When an interaction occurs, the iPayments Entra application must have full permissions to complete that interaction. If that interaction is modified or augmented from the default Business Central + iPayments process, the appropriate permissions must be granted for those modified or augmented scenarios. Since each Business Central environment may be customized in different ways and include various ISVs that may hook into any events raised within Business Central, each administrative team of the environment must evaluate their environment, modifications, extensions and compare those interactions with the permission set(s) assigned to iPayments users and the iPayments Entra application to ensure all transactions can complete without failure due to insufficient permissions.

Resolution

To resolve this class of errors, a Business Central administrator can search for “Microsoft Entra Applications” from within Business Central and locate the enabled iPayments application that has been granted consent to connect from an Azure administrator. Audit the “User Permission Sets” in the lower panel of the Microsoft Entra Application Card to verify that the application has accurate and complete permissions to successfully perform the necessary interactions and workflows. If you received a specific error message, refer to the contents of the error message to guide you in correcting the minimum permissions to resolve the specific error. Note, however, this may not be the only permission that is necessary to grant to the iPayments application to fully resolve the issue for your environment. These errors will typically occur for all transactions (or transactions that are impacted by the affected permission scope) until the issue is resolved.

Dimension Errors

If you are using dimensions in Business Central to group, categorize, or segment data and/or control data flow through the system (or for any other reason), you might encounter an error where the dimensions configured for a particular transaction may be in an invalid state of acceptance for the system. Because this are of the Business Central system is highly flexible and customizable, it can be misconfigured or set up to allow invalid scenarios. This can occur for a near infinite number of reasons. Thankfully, when an error occurs like this, Business Central often provides enough information about the error to quickly troubleshoot and resolve the issue.

Resolution

The corrective action for this scenario is highly dependent on how you are using dimensions in your environment and the specific error that you may have received. If you have received a specific error message for this type of error, refer to the content of the error message to help guide you on which dimension(s) might be causing the problem, where the problem is occurring within the transaction/process, and potentially how to resolve the issue. Note that in addition to out-of-the-box configurations of dimensions on various objects in Business Central, customizations and other ISVs may also take advantage of dimensions in those implementations. Your complete corrective action may involve resolving dimension issues that may include one or more of these customizations or other ISVs. Typically, dimension errors will continue to occur for transactions impacted by affected records/configurations until the issue is resolved.

In some cases, errors caused by invalid dimension configurations cause an immediate run-time exception. In those cases, you may be able to resolve the dimension configuration issue and retry the transaction. In other cases, however, the run-time exception may occur within a process where some of it has completed successfully. In those cases, after resolving the dimension configuration issue, manual correction or reconciliation may be required for the transactions affected by the error. In most cases, details about affected transactions will be included in the error message content so they can be audited and addressed.

Email Send Errors

Business Central allows for very flexible configurations when it comes to sending emails. When a user is logged into Business Central, they can directly send emails or indirectly send emails by invoking a process that results in sending emails. Emails used in these scenarios may be many different types and Business Central handles these scenarios with great elegance.

There is one limiting workflow, however, that Business Central does not currently offer such flexibility in configuration. When an external system interacts with Business Central via its REST API and invokes a process that results in sending one or more emails via Business Central, its behavior is limited to only allowing that email to be sent using an SMTP mailbox with basic authentication. Attempting to use a mailbox that requires OAuth authentication will result in a failure to acquire an OAuth token, thus a failure to send the email.

Resolution

The corrective action for this scenario is to create an email account in Business Central (Search > Email Accounts). This is a transactional email scenario, so we recommend following the industry best practices for sending transactional emails. This may include: using a dedicated transactional email service provider, using dedicated IP addresses, using a dedicate domain, complying with all anti-spam laws in your regions and protecting your domain’s reputation. In some cases, using a standard email service provider may limit emails per day and may not have sufficient protections in place to help protect your domain, IP addresses or remain compliant to all anti-spam laws.

Once you have selected the appropriate transactional email service provider and can confirm that it supports SMTP with basic authentication, you can set up the email account in Business Central. Once the account is created, you can assign the iPayments scenario assignments to the email account to instruct iPayments to use that account for those scenarios where the SMTP account is required to send the email. After this, you can test to ensure that the emails are now being sent. If you need help, you can contact iSolutions support and we can conduct a test for you. Email failures will continue to occur until the issue is fully resolved.

Posting Date Errors

Posting date errors can happen for a variety of reasons. Posting dates may not be open globally or even for a specific user. A user or administrator who is familiar with posting dates and how they are set up and used within your Business Central environment will be required to review the error and make the appropriate change.

Resolution

The corrective action to resolve posting date errors is to identify the source of the posting date range failure and adjust the posting dates accordingly to allow transactions to flow through again. If you are resolving a specific instance of an error, review the content of the error as well as the transaction information to help identify the posting date issue and guide you towards a resolution. In some cases, a user’s card may have already been successfully charged when the posting date failure occurred, so you may also have to reconcile this and other affected transactions. Typically posting date failures will continue to occur until they are resolved.

Concurrency Errors

Concurrency errors occur when a transaction is attempting to read or write records in a database that are being accessed and locked by another process. This could be another user, the same user editing the record in multiple tabs, or another process, system or job.

The Business Central database is a highly complex, highly transactional and highly customizable database. As a result, there is no one-size-fits-all reason that may explain why concurrency issues occur in your particular environment. Similarly, resolutions may be extremely specific to a particular environment. In general, though, a concurrency error typically results in a transaction (database read/write) failing due to a lock or deadlock situation. This may result in an entire process not completing or a process partially completing and partially failing. It is recommended that each transaction which experiences this type of error be reviewed end-to-end for completeness and accuracy. In some cases, manual reconciliation of part or all of the affected process may be required.

Resolution

The first step is to identify the affected transaction/document/records and begin to review them in context of the workflow where the failure occurred to identify where within that process the failure happened and what reconciliation/correction may need to take place to ensure the integrity of the data end to end.

Next, monitoring for recurring database concurrency issues in your environment may be required. If this class of errors continues to occur, or occurs with greater frequency, further analysis may be required to understand the database activity and interactions that may be causing the concurrency issues and begin implementing resolutions. This is a highly individual action that must be completed with more global knowledge of a particular environment. The fixes for On-Prem instances may be different from Cloud instances. Customizations, ISVs or other extensions may also play a role. The amount, size, structure and type of data may also be a contributing factor. The overall activity of the database could be a contributing factor as well.

Concurrency issues may require advanced troubleshooting, monitoring and optimization skills that require intense knowledge of Business Central and your particular environment. You may consider working with your partner to help resolve these issues if they continue to arise.

Account Missing Errors

There are various reasons why you may receive an error for a missing account. In all cases, however, the resolution will be to add the missing account or identify the reference to the missing account and correct that.

Resolution

The corrective action to resolve missing account errors is to either add the missing account or identify the source of the errant reference to the missing account and correct that. If you have received an account missing error, refer to the content of that specific error to help guide you towards fixing the errant account. In some cases, you may have to manually reconcile transactions or records that were impacted by the failure. In most cases that information will also be included in the error you received.

Report Errors

There are various reasons why you may receive an error for a report. There may have been a modification an existing report in Business Central that is used in processing a transaction, such as a receipt. The report may be a new custom report entirely. There may also be other reasons why the generation of a report may fail. Reports may be Word reports, SSRS reports or other reports from customized workflows or other ISVs. The methodology to correct the report may depend on how it was created. In all cases, however, the resolution requires identifying the failure, correcting it and testing end to end to ensure the failure has been properly addressed and the invoking process can complete successfully.

Resolution

The corrective action to resolve report errors is to identify the report that is causing the errors. Edit the report to resolve any missing, invalid, misconfigured or otherwise errant properties of the report and commit your changes. Test the report and run a test transaction using the same procedure that was used when the report error occurred to verify that the report errors are resolved and the affected procedure can now complete successfully. In some cases, you may have to manually reconcile transactions or records that were impacted by the failure.

Additional Help

If you need additional help resolving this or any other issues related to iPayments, please email help@isolutionspayments.com to create a support ticket.