Troubleshooting APNS Issues on Web Help Desk

In Web Help Desk, APNS (Apple Push Notification Service) is used to push ticket alerts to the Web Help Desk Mobile app on iOS devices.

What it does

• APNS lets WHD send push notifications to Apple devices running the Web Help Desk Mobile app on a supported iOS version.
• When enabled, the device can receive a notification each time a ticket is created or updated, based on thresholds you configure (priority/alert level, etc.).

This article helps in troubleshooting issues with APNS.

1. Runbook: APNS notifications not firing in Web Help Desk

Use this as a step-by-step checklist.

1. Confirm the ticket should generate an alert

1. Check ticket priority & alert thresholds

   • Go to Setup → Tickets → Priority Types & Alerts → [Priority].
   • Confirm:
     • Due Date/Time is configured.
     • At least one alert threshold + optional repeat is set (Alert 1/2/3).

2. Check status type allows alerts

   • Go to Setup → Tickets → Status Types → [Status used on ticket].
   • Confirm:
     • Alerts Enabled is checked.
     • Ticket is not in a status where alerts are intentionally disabled (e.g., Closed/Canceled).

3. Check auto-reminders (if you rely on them)

   • Same Status Type screen:
     • Client Reminders enabled if you expect client reminder behavior.
   • Priority type:
     • Client Reminder Interval set if you rely on reminder-driven alerts.

If a ticket uses a priority with no alert thresholds or a status with alerts disabled, APNS will never be considered for that event.

2. Confirm tech recipients and their thresholds

1. Determine which tech(s) are supposed to get alerts

   • For the ticket, check:
     • Assigned Tech
     • Tech Group / Tech Group Level

2. Check Tech Group Level email/alert routing

   • Setup → Techs → Tech Groups → [Group] → Tech Group Levels → [Level]:
     • Force E-Mail Notification To – verify that Level Techs, Group Manager, or both are selected appropriately for ticket creation/update/API/SolarWinds Platform events.
     • Default Selected E-Mail Recipients – confirm expected roles are checked by default when techs click Save & E-Mail.

3. Check per-tech email preferences

   • Setup → Techs → Techs → [Tech]:
     • In Notification area, verify checkboxes for events that should send email (new ticket, ticket update, alert, etc.).

4. Check per-tech APNS/SMS thresholds

   • Same tech account, under Account Info:
     • Verify a device is registered under Mobile Devices Setup (after WHD Mobile registration).
     • Under E-Mail Setup:
       • SMS E-Mail Enabled is checked.
       • SMS email address is set (carrier email, e.g. number@vtext.com).
       • Minimum ticket priority is not higher than the ticket’s actual priority.
       • Minimum ticket alert level is appropriate for the alert you expect.
       • Repeating checked if you expect recurring notifications until alert condition clears.

Note: some providers are retiring SMS to Email services, and may do so without notice. For example Verizon is experiencing intermittent failures and is scheduled for full retirement March 31, 2027.

If the tech isn’t a selected email/alert recipient, or their SMS minimums are stricter than the ticket’s state, WHD won’t attempt APNS for that ticket.

3. Verify APNS certificate & keystore

1. Check APNS status in WHD

   • Go to Setup → General → Certificates.
   • In the APNS panel:
     • Confirm an APNS certificate is present and its expiration date is in the future.

2. If expired or missing: renew

   • From SolarWinds Customer Portal → License Management → My Downloads → Web Help Desk → Additional Downloads:
     • Download “Apple Push Notification (APN) Certificate”.
   • Unzip, then in WHD:
     • Setup → General → Certificates → “Upload a new APNS Certificate file” → Browse → select file → complete prompts.
   • If FIPS is enabled:
     • Ensure the certificate file is also placed under \<WebHelpDeskHome>/conf/apns as required.

3. Restart WHD

   • After any APNS/keystore change:
     • Click Restart in Certificates page or restart WHD service (OS-specific commands).

4. Use the test button

   • In Setup → General → Certificates click “Send Test Notification”.
   • Confirm the registered Apple device receives a test push.
   • If test fails but ticket events look fine, the problem is almost certainly cert / keystore / network.

4. Verify mobile app registration path

1. On the device

   • Install Web Help Desk Mobile from the App Store.
   • In the app, register using:
     • WHD host/FQDN
     • Port (8081 or 8443)
     • Credentials, then complete the in-app registration form.

2. In WHD

   • For the tech account, check Mobile Devices Setup:
     • Device appears as Registered.

3. Re-test APNS

   • Use Send Test Notification again. If this now succeeds, earlier failures were due to missing/invalid registration.

5. Network & TLS checks

Ports / directions to verify:

1. Inbound to WHD

   • HTTP (default): TCP 8081
   • HTTPS (default): TCP 8443
   • Confirm your LB / firewall forwards external ports to these internal ports, or that you’ve changed DEFAULT_PORT and URL port settings correctly in whd.conf and Server Options.

2. Outbound from WHD to APNS

   • Allow outbound TCP 443 from WHD host to Apple APNS endpoints.
   • If the cert is valid and test notifications still don’t reach devices, suspect:
     • Egress firewall blocking APNS
     • SSL inspection box interfering with APNS TLS.

3. TLS config

   • TLS version:
     • 12.8 supports TLS 1.3 for browser→WHD, FIPS uses TLS 1.2 with approved ciphers.
   • Keystore:
     • Non-FIPS: keystore.jks / PKCS12, KEYSTORE_TYPE=JKS/PKCS12 in whd.conf.
     • FIPS: convert to BCFKS for trust/certs and APNS, using BouncyCastle FIPS provider.

4. Check HTTPS/HSTS

   • If HSTS is enabled (12.7.4+ with trusted CA cert), ensure devices can still reach HTTPS without man-in-the-middle issues.

6. Logs & diagnostics

1. Log level

   • Setup → General → Logs:
     • Temporarily bump Web Help Desk Application or relevant packages to DEBUG or TRACE to capture notification-related behavior.

2. Log file

   • Check \<WebHelpDesk>/log/whd.log around:
     • Ticket event time
     • APNS test time
   • Look for:
     • Keystore / TLS errors
     • “invalid certificate” / “handshake failure”
     • APNS HTTP errors (4xx/5xx).

3. Revert log levels

   • After troubleshooting, return log levels to defaults to avoid performance impact.

7. Common failure patterns

• APNS cert expired or never uploaded → test notification fails, nothing leaves WHD.
• Tech has SMS E-Mail Enabled off or thresholds too high → ticket events generate emails but not APNS.
• Device not registered (no Mobile Devices Setup entry) → APNS push has no valid target device.
• Firewall/proxy blocks outbound APNS → test notification fails despite good cert.
• FIPS enabled but keystores not converted / APNS cert not in conf/apns → TLS provider can’t use the cert, APNS flow breaks.

2. Conceptual network diagram (text form)

Actors:

• Client Browser (tech/customer)
• Tech iOS Device with WHD Mobile
• WHD Server
  • HTTP(S) listener (Tomcat)
  • Java keystore(s) (keystore.jks / PKCS12 / BCFKS)
  • APNS certificate
• Database (PostgreSQL embedded or external, or SQL Server/MySQL) – not directly in APNS flow, but holds tickets & settings
• Apple APNS service

2.1 Ticket creation / update path

Client Browser --HTTP/HTTPS (8081 / 8443)--> WHD Server --DB query--> Database
                                             |
                                             +--> Evaluate priority/status/alerts
                                             +--> Select tech recipients
                                             +--> For each tech: maybe queue APNS/SMS

• Transport: HTTP or HTTPS depending on your Server Options and Force HTTPS.

2.2 APNS registration path

Tech iOS Device (WHD Mobile)
  |
  | (1) HTTPS to APNS (Apple) -> gets device token
  |
  | (2) HTTPS to WHD (8443 or 8081) with host/port and credentials
  v
WHD Server
  - Stores mapping: Tech account <-> Device (token)
  - Device appears under Tech's "Mobile Devices Setup"

• Device registration uses same WHD HTTPS endpoint your browser uses.

2.3 APNS notification path

Ticket Event in WHD
  |
  +--> WHD evaluates:
        - Priority & alerts
        - Status type
        - Tech group routing
        - Tech SMS thresholds
  |
  +--> For each qualifying tech:
        build payload (text, ticketId, etc.)
        look up device token
        |
        v
      TLS connection (client cert from keystore / PKCS12 / BCFKS)
        |
        v
      Apple APNS over TCP 443
        |
        v
      APNS -> iOS device push

• Certificates used:

  • WHD server TLS: general HTTPS cert in keystore (keystore.jks / PKCS12 / BCFKS).
  • APNS TLS: APNS cert (included with WHD / downloaded from Customer Portal) stored either in main keystore or dedicated PKCS12, or conf/apns under FIPS.

• FIPS mode overlay:

WHD Server (FIPS-enabled JVM)
  - BCFKS keystores (keystore.bcfks, cacerts.bcfks)
  - APNS cert in conf/apns (FIPS requirement)
  - TLS 1.2 with approved cipher suites
  |
  +--> Same APNS flow as above, but via BC-FIPS provider

This gives you both the logic map (ticket → event → APNS decision) and the network/TLS picture for troubleshooting and design reviews.