Troubleshooting Guide

Overview

This comprehensive troubleshooting guide provides solutions to common issues encountered when using the Municipality Gateway system. Issues are organized by functional area with step-by-step resolution procedures.

General System Issues

Login and Authentication Problems

Issue: Cannot log into Business Central

Error Messages:

• "Invalid username or password"

• "Your account has been locked"

• "Authentication failed"

Common Causes:

• Incorrect username or password

• Account lockout after multiple failed attempts

• Network connectivity issues

• Azure AD authentication problems

Solutions:

1. Verify Credentials: Confirm username and password are correct

2. Check Caps Lock: Ensure caps lock is off

3. Wait for Lockout: Wait 15 minutes if account is locked

4. Contact Administrator: Request password reset if needed

5. Clear Browser Cache: Remove stored authentication data

6. Try Different Browser: Test with alternative browser

Issue: "You do not have permission to access this page"

Solutions:

1. Check User Permissions: Verify user has appropriate roles assigned

2. Contact Administrator: Request access to Municipality Gateway modules

3. Refresh Session: Log out and log back in

4. Company Selection: Ensure correct company is selected

Performance Issues

Issue: System running slowly

Common Causes:

• Large data volumes in queries

• Complex filtering criteria

• Network connectivity issues

• Database performance problems

Solutions:

1. Reduce Query Scope: Limit date ranges and filter criteria

2. Use Pagination: Process large datasets in smaller chunks

3. Clear Browser Cache: Remove temporary files

4. Check Network: Verify internet connection stability

5. Contact IT Support: Report persistent performance issues

Issue: Timeouts when loading pages

Solutions:

1. Simplify Queries: Reduce complexity of data requests

2. Optimize Filters: Use more specific filtering criteria

3. Break Down Tasks: Process large operations in smaller steps

4. Schedule Large Reports: Run intensive reports during off-hours

Web Applications Issues

Application Creation Problems

Issue: Cannot create new web application

Error Messages:

• "Application type is not available"

• "Registration period is closed"

• "Insufficient permissions"

Solutions:

1. Check Application Type Status:

   • Navigate to Web Application Types

   • Verify the type is active and not expired

   • Confirm registration dates are current

2. Verify User Permissions:

   • Ensure user has Web Application creation rights

   • Check role assignments in User Setup

   • Contact administrator for permission updates

3. Validate Date Settings:

   • Confirm system date is correct

   • Check registration period start/end dates

   • Verify time zone settings

Issue: Application validation errors

Error Messages:

• "Invalid social security number"

• "Age does not meet requirements"

• "Post code not eligible"

Solutions:

1. Social Security Number Issues:

   Correct Format: 1234567890 (10 digits, no spaces or dashes)
   Invalid: 123-456-7890, 123 456 7890
   

2. Age Eligibility Problems:

   • Verify birthdate is entered correctly

   • Check service age requirements in Application Type setup

   • Confirm registration date impacts on age calculation

3. Post Code Restrictions:

   • Verify address is entered correctly

   • Check Post Code Rules for geographic restrictions

   • Contact customer to confirm residency status

Application Processing Issues

Issue: Applications stuck in "Open" status

Common Causes:

• Missing required information

• Approval workflow errors

• Capacity constraints

• Payment processing delays

Solutions:

1. Review Application Completeness:

   • Check all required fields are completed

   • Verify guardian information for minors

   • Confirm all necessary documentation is attached

2. Check Approval Workflow:

   • Verify approver availability and permissions

   • Review approval criteria and rules

   • Escalate to supervisor if needed

3. Validate Capacity:

   • Check available spots for requested services

   • Review capacity limits in Line Type setup

   • Consider alternative services or time slots

Discount Calculation Issues

Issue: Discounts not applying correctly

Error Symptoms:

• Expected discount not showing

• Wrong discount percentage applied

• Family discounts not calculating

Diagnostic Steps:

1. Verify Discount Rule Configuration:

   • Navigate to Discount Rules setup

   • Check rule effective dates

   • Confirm eligibility criteria

2. Validate Participant Data:

   • Verify age calculation is correct

   • Check address/post code accuracy

   • Confirm family relationships

3. Review Calculation Log:

   • Check discount calculation details

   • Identify which rules were applied

   • Look for rule conflicts or exclusions

Solutions:

1. Rule Configuration Fixes:

   • Update discount rule date ranges

   • Correct eligibility criteria

   • Resolve rule conflicts

2. Data Quality Improvements:

   • Update participant information

   • Verify National Registry integration

   • Correct family relationship data

Payment Processing Issues

Credit Card Payment Problems

Issue: Credit card payments failing

Error Messages:

• "Payment declined"

• "Invalid card information"

• "Transaction timeout"

Common Causes:

• Insufficient funds

• Expired card information

• Incorrect card details

• Payment gateway issues

Solutions:

1. Verify Card Information:

   • Check card number accuracy

   • Confirm expiration date is current

   • Verify CVV code

   • Ensure billing address matches card

2. Payment Gateway Troubleshooting:

   • Check gateway service status

   • Verify merchant account status

   • Test with different card types

   • Contact payment processor if needed

3. Customer Communication:

   • Suggest customer contact their bank

   • Offer alternative payment methods

   • Provide payment assistance

Issue: Successful payments not reflected in system

Solutions:

1. Check Payment Reconciliation:

   • Run payment reconciliation process

   • Verify general ledger posting

   • Check for pending transactions

2. Review Integration Status:

   • Validate payment gateway integration

   • Check API connection status

   • Review transaction logs

Invoice Generation Problems

Issue: Invoices not generating automatically

Common Causes:

• Application not approved

• Missing G/L account setup

• Posting permission issues

• Date range restrictions

Solutions:

1. Application Status Check:

   • Verify application is approved

   • Check approval workflow completion

   • Confirm all required approvals obtained

2. Financial Setup Verification:

   • Check G/L account configuration

   • Verify posting group setup

   • Confirm VAT setup is correct

3. User Permissions:

   • Verify posting permissions for user

   • Check role assignments

   • Ensure posting date is in open period

Bank Transfer Issues

Issue: Direct debit failures

Error Messages:

• "Invalid bank account number"

• "Authorization not found"

• "Bank file format error"

Solutions:

1. Account Verification:

   • Confirm bank account number format

   • Verify routing/sort code accuracy

   • Check account ownership details

2. Authorization Management:

   • Verify signed authorization on file

   • Check authorization expiration dates

   • Update customer consent if needed

3. File Format Validation:

   • Review bank file format requirements

   • Check data field mappings

   • Validate file generation process

Integration Issues

National Registry Integration

Issue: Person lookup failures

Error Messages:

• "Person not found in registry"

• "Registry service unavailable"

• "Invalid social security number format"

Solutions:

1. Data Format Validation:

   • Ensure social security number is 10 digits

   • Remove spaces, dashes, or special characters

   • Verify number follows Icelandic format

2. Service Connectivity:

   • Check internet connection

   • Verify registry service status

   • Test with different social security numbers

3. Credentials and Permissions:

   • Verify integration credentials are current

   • Check service permissions

   • Contact system administrator if needed

Issue: Address information not updating

Solutions:

1. Refresh Registry Data:

   • Run manual registry update

   • Check last update timestamp

   • Verify integration schedule

2. Data Mapping:

   • Check field mapping configuration

   • Verify address format compatibility

   • Review data transformation rules

External System Integration

Issue: Batch import failures

Error Messages:

• "File format not recognized"

• "Data validation errors"

• "Mapping configuration missing"

Solutions:

1. File Format Validation:

   • Check file format matches expected structure

   • Verify column headers and data types

   • Validate file encoding (UTF-8 recommended)

2. Data Quality Check:

   • Review data for completeness

   • Check for invalid characters

   • Verify date formats

3. Mapping Configuration:

   • Review field mapping setup

   • Check code mapping tables

   • Validate transformation rules

Reporting Issues

Report Generation Problems

Issue: Reports not generating or showing no data

Common Causes:

• Date range restrictions

• Permission limitations

• Filter criteria too restrictive

• Database connectivity issues

Solutions:

1. Review Filter Criteria:

   • Expand date ranges

   • Remove restrictive filters

   • Check for typos in filter values

2. Check User Permissions:

   • Verify report access permissions

   • Check data visibility restrictions

   • Contact administrator for access rights

3. Validate Data Availability:

   • Confirm data exists for selected period

   • Check data processing status

   • Verify source system connectivity

Issue: Report performance problems

Solutions:

1. Optimize Report Parameters:

   • Limit date ranges to necessary periods

   • Use more specific filter criteria

   • Reduce data volume where possible

2. Schedule Large Reports:

   • Run intensive reports during off-hours

   • Use batch processing for large datasets

   • Consider breaking reports into smaller sections

Dashboard and Analytics Issues

Issue: Dashboard not loading or showing incorrect data

Solutions:

1. Refresh Data:

   • Clear browser cache

   • Refresh dashboard manually

   • Check data refresh schedule

2. Check Data Sources:

   • Verify underlying data availability

   • Check data processing job status

   • Validate data transformation logic

API and Integration Issues

API Authentication Problems

Issue: API calls returning authentication errors

Error Codes:

• 401 Unauthorized

• 403 Forbidden

• Token expired errors

Solutions:

1. Verify Credentials:

   • Check client ID and secret

   • Confirm tenant ID accuracy

   • Validate environment name

2. Token Management:

   • Request new access token

   • Check token expiration time

   • Implement automatic token refresh

3. Permissions Check:

   • Verify API permissions in Azure AD

   • Check Business Central user permissions

   • Confirm service principal setup

Issue: API calls timing out or failing

Solutions:

1. Network Connectivity:

   • Check internet connection

   • Verify firewall settings

   • Test connectivity to API endpoints

2. Request Optimization:

   • Reduce query complexity

   • Implement pagination

   • Use field selection ($select)

3. Rate Limiting:

   • Check API rate limits

   • Implement request throttling

   • Monitor API usage patterns

Database and Performance Issues

Data Corruption or Inconsistency

Issue: Data appears corrupted or inconsistent

Symptoms:

• Missing records

• Duplicate entries

• Incorrect calculations

• Relationship integrity problems

Solutions:

1. Run Data Consistency Checks:

   • Execute built-in consistency checks

   • Review data validation reports

   • Check referential integrity

2. Identify Source of Corruption:

   • Review recent system changes

   • Check integration processes

   • Analyze user activity logs

3. Data Recovery:

   • Restore from backup if needed

   • Manually correct specific records

   • Re-run data processing jobs

System Configuration Issues

Issue: Features not working as expected

Common Causes:

• Incorrect setup configuration

• Missing or incomplete setup

• Version compatibility issues

• Customization conflicts

Solutions:

1. Review Setup Configuration:

   • Check all required setup tables

   • Verify configuration completeness

   • Compare with working environments

2. Validate Permissions:

   • Check object permissions

   • Verify setup table access rights

   • Review role assignments

3. Test in Isolation:

   • Create test scenarios

   • Isolate problem areas

   • Compare with baseline functionality

Emergency Procedures

System Outage Response

If the system becomes unavailable:

1. Immediate Actions:

   • Document the issue and time

   • Notify system administrator

   • Inform affected users

   • Implement manual procedures if available

2. Communication:

   • Update stakeholders on status

   • Provide estimated resolution time

   • Document workaround procedures

3. Recovery Process:

   • Work with IT support for resolution

   • Test system functionality before reopening

   • Document lessons learned

Data Loss Recovery

If data appears to be lost:

1. Stop All Processing:

   • Halt data entry activities

   • Stop automated processes

   • Document the extent of data loss

2. Contact Support Immediately:

   • Notify system administrator

   • Contact Microsoft Support if needed

   • Escalate to management

3. Recovery Planning:

   • Assess backup availability

   • Plan data reconstruction if needed

   • Implement preventive measures

Getting Additional Help

Internal Support Resources

System Administrator

• Contact For: Permission issues, setup problems, integration failures

• Response Time: Same business day

• Escalation: Department manager

IT Support

• Contact For: Network issues, hardware problems, system outages

• Response Time: Within 2 hours for critical issues

• After Hours: Emergency contact available

External Support Resources

Microsoft Support

• Contact For: Business Central product issues

• Requirements: Valid support contract

• Documentation: Detailed error logs and reproduction steps

Wise Support

• Contact For: Municipality Gateway specific issues

• Contact Method: Through partner channel

• Documentation: Complete system information and error details

Documentation and Training

Online Resources

• Wise Documentation: https://docs.wise.is/sve/

• Microsoft Docs: Business Central documentation

• Community Forums: User community discussions

Training Resources

• User Training: Scheduled training sessions

• Administrator Training: Advanced configuration training

• Custom Training: Specific organizational needs

Best Practices for Problem Prevention

Regular Maintenance

1. System Health Checks:

   • Monitor system performance regularly

   • Review error logs weekly

   • Check integration status daily

2. Data Quality Management:

   • Validate data entry procedures

   • Review data consistency reports

   • Maintain data cleansing routines

3. User Training:

   • Provide regular training updates

   • Document common procedures

   • Share best practice guidelines

Proactive Monitoring

1. Performance Monitoring:

   • Track system response times

   • Monitor database growth

   • Review capacity utilization

2. Security Monitoring:

   • Review access logs regularly

   • Monitor failed login attempts

   • Keep security software updated

3. Integration Monitoring:

   • Check external system connectivity

   • Monitor data exchange processes

   • Validate integration data quality

This troubleshooting guide is regularly updated. For the latest information and additional resources, visit the Municipality Gateway documentation portal.