Skip to main content

API Connections

Manage connections to external APIs, including Microsoft Dynamics 365 Business Central (Navision).

Overview​

API Connections store credentials and configuration for external services that GSM Middleware integrates with. Currently supported:

  • Business Central (Navision) - OData API for order export, inventory, and verification
  • Basic Auth - Username/password authentication
  • OAuth 2.0 - Token-based authentication (for future integrations)

Location: WordPress Admin → GSM Middleware → API Connections

Connection Types​

Basic Authentication​

Standard username/password authentication:

Fields:

  • Name: Descriptive name (e.g., "Navision Production")
  • Environment: live, beta, dev, or local
  • URL: API base URL (e.g., https://api.bc.example.com:7048/BC180/ODataV4/Company('Company%20Name'))
  • Username: API username
  • Password: API password
  • Active: Mark as active connection

OAuth 2.0 Authentication​

Token-based authentication (for future use):

Fields:

  • Client ID: OAuth application ID
  • Client Secret: OAuth application secret
  • Tenant ID: Azure AD tenant ID (for Microsoft services)
  • Token URL: OAuth token endpoint
  • Scopes: Required OAuth scopes

Managing Connections​

Add a New Connection​

  1. Navigate to GSM Middleware → API Connections
  2. Click "Add Connection" button
  3. Fill in the form:
    • Name: Navision Production
    • Type: basic
    • Environment: live
    • URL: Your OData endpoint
    • Username: API username
    • Password: API password
  4. Click "Test Connection"
  5. If successful, click "Save"

Edit Existing Connection​

  1. Find the connection in the list
  2. Click "Edit"
  3. Modify fields as needed
  4. Click "Test Connection" to verify
  5. Click "Save"

Activate a Connection​

Only one connection per environment can be active at a time.

  1. Find the connection
  2. Click "Activate"
  3. Other connections for that environment are automatically deactivated

Delete a Connection​

⚠️ Warning: Deleting an active connection will break sync operations!

  1. Click "Delete" next to the connection
  2. Confirm the deletion
  3. Connection is permanently removed

Test Connection​

Verify credentials before saving:

  1. Fill in connection details
  2. Click "Test Connection"
  3. Wait for result:
    • ✅ Success: "Connection successful - API responding"
    • ❌ Failure: Error message with details

Common errors:

  • 401 Unauthorized: Wrong username/password
  • 404 Not Found: Incorrect URL
  • Connection timeout: Network/firewall issue
  • SSL Error: Certificate problem

Business Central Setup​

OData URL Format​

https://[server]:[port]/[instance]/ODataV4/Company('[company-name]')

Example:

https://api.bc.example.com:7048/BC180/ODataV4/Company('MyCompany')

URL Encoding:

  • Spaces: %20
  • Apostrophes: %27
  • Example: Company('ABC Company') → Company('ABC%20Company')

Required Permissions​

The API user must have permissions to:

  • Read items (for inventory sync)
  • Create sales orders (for BC export)
  • Read sales shipments (for tracking sync)
  • Read item status codes

Creating API User in Business Central​

  1. Open Business Central
  2. Go to Users (search "Users")
  3. Click New
  4. Fill in details:
    • User Name: api_user_gsm
    • Full Name: GSM Middleware API
  5. Assign permissions:
    • SUPER (for testing)
    • Custom permission set (for production)
  6. Enable Web Services Access
  7. Set password
  8. Save

Web Services Configuration​

Ensure OData endpoints are published:

  1. Go to Web Services
  2. Verify these are published:
    • Item (Page 31)
    • SalesOrders (Page 42)
    • SalesShipments (Page 143)

Environment Management​

Multiple Environments​

You can configure multiple environments:

EnvironmentPurposeExample
liveProduction systemMain BC instance
betaStaging/testingPre-production BC
devDevelopmentDevelopment BC
localLocal testingLocal BC instance

Environment Switching​

Switch between environments without changing configuration:

  1. Go to API Connections
  2. Click "Activate" on desired environment
  3. All sync operations now use that connection

Test vs. Production​

Configure separate connections for testing:

Production:

  • Environment: live
  • URL: https://bc-prod.example.com/...
  • Active: ✅ (during normal operations)

Testing:

  • Environment: beta
  • URL: https://bc-test.example.com/...
  • Active: ✅ (when testing)

Security Best Practices​

Password Management​

  • Use strong, unique passwords
  • Rotate credentials regularly (every 90 days)
  • Never share credentials
  • Use dedicated API users (don't use personal accounts)

Access Control​

  • Limit API user permissions to minimum required
  • Use read-only access where possible
  • Monitor API access logs in Business Central

Network Security​

  • Use HTTPS only (never HTTP)
  • Configure firewall rules to restrict access
  • Consider VPN for additional security
  • Use IP whitelisting if available

Credential Storage​

All credentials are:

  • Encrypted at rest in the database
  • Never logged or displayed in full
  • Transmitted over HTTPS only
  • Accessible only to users with manage_gsm_middleware capability

Connection Status​

Status Indicators​

  • 🟢 Connected: Last test successful
  • 🟡 Warning: Connection slow or intermittent
  • 🔴 Error: Connection failed
  • ⚪ Inactive: Connection disabled

Last Tested​

Shows when connection was last verified:

  • Just now: < 1 minute ago
  • 5 minutes ago: Recent test
  • 2 hours ago: May need retesting
  • Never: New connection, not tested yet

Active Badge​

  • ✅ Active: Currently in use
  • ⭕ Inactive: Not in use

Troubleshooting​

Connection Test Fails​

401 Unauthorized​

Causes:

  • Wrong username or password
  • User account disabled in BC
  • User lacks Web Services Access

Solutions:

  1. Verify credentials in Business Central
  2. Check user is active
  3. Enable Web Services Access
  4. Reset password if needed

404 Not Found​

Causes:

  • Wrong URL
  • Wrong company name
  • Web service not published

Solutions:

  1. Verify URL format
  2. Check company name encoding
  3. Publish required web services
  4. Test URL in browser

Connection Timeout​

Causes:

  • Network/firewall blocking request
  • BC server down or slow
  • Wrong port number

Solutions:

  1. Check firewall rules
  2. Verify BC is running
  3. Test with telnet: telnet bc-server.com 7048
  4. Check port number in URL

SSL Certificate Error​

Causes:

  • Self-signed certificate
  • Expired certificate
  • Certificate hostname mismatch

Solutions:

  1. Install valid SSL certificate
  2. Renew expired certificate
  3. Update CA certificates: sudo update-ca-certificates

Connection Works But Operations Fail​

Check:

  1. API user permissions in BC
  2. Web services are published
  3. Required objects exist
  4. BC maintenance window (Sunday 19:00 - Monday 04:00 UTC)

Can't Save Connection​

Check:

  1. User has manage_gsm_middleware capability
  2. All required fields filled in
  3. No JavaScript errors in browser console
  4. Database connection is working

API Connection Settings​

Global Settings​

Configure in Settings page:

  • Connection Timeout: Max seconds to wait for response (default: 30)
  • Retry Attempts: Number of retries on failure (default: 3)
  • Retry Delay: Seconds between retries (default: 5)

Per-Connection Settings​

Some settings are per-connection:

  • Rate Limiting: Max requests per minute (for APIs with limits)
  • Batch Size: Records per request (for bulk operations)
  • Timeout Override: Custom timeout for slow endpoints

Next Steps​