TABLE OF CONTENTS
- 1. Introduction
- 2. User Account
- 3. Connection Rebuilding
- 4. WIN-911 Mobile Runtime service
WIN-911 2021 comes with the latest version of our mobile app system, able to integrate with users via Android and iOS apps. We utilize Azure app servers and Microsoft authentication to keep your system accessible and secure. This article will go over troubleshooting steps to ensure that your users can get their accounts working properly with the latest versions of the WIN-911 Mobile app.
2. User Account
A. UserPrincipalName versus Email Address
As of the WIN-911 Mobile app update in late February 2022, changes were made to the Microsoft Authentication used by WIN-911. The new library reports back the UserPrincipalName, or UPN, stored with Microsoft. Previously, the app would just report the email address entered during sign-in. For most accounts, this UPN is the same as the email address linked to it. However, users of Microsoft 365 enterprise products, especially with Azure AD Sync, may encounter issues where the UPN is different to the primary email address for a user's account.
WIN-911 expects that the UPN and the Email address match, at least for the initial registration. When an email address is entered into the Workspace as a mobile connection, the cloud server will send an invitation email to that address. If the address cannot receive mail, it will not get the invitation. Microsoft registers the UPN/Account Name to your cloud instance, not the email address. As such, it's required that the UPN be entered into WIN-911's Workspace, and that this be able to receive email.
An end user cannot check their UPN, it's only available to Microsoft 365 admins. For more information on UPNs, how they can change, and their interaction with Microsoft Authentication, please review this document about Azure UPN Changes.
One way you can check this is inside the WIN-911 Mobile app itself. If a user is able to sign into the app, but is getting errors about retrieving alarms (and this is an isolated case, not a system wide failure), you can check what account name is being reported to WIN-911.
For iOS, open the app, tap the 'Settings' gear icon in the bottom navbar, then scroll down to the 'Other' section. Next to the "Logout" entry should be the user account reported to WIN-911.
For Android, open the app, tap the three menu bars icon at the top, then check the text below the WIN-911 Mobile logo. It should say "Hello, [user]." This is the user account reported to WIN-911.
If the user is unable to access the app, they can try to sign into the Mobile app splash page here: https://win911mobileproduction.azurewebsites.net/ If they have a proper account, it will show a screen with the WIN-911 Mobile logo, and a blue box with text stating you can sign into the app. However, in the top right, it will say "Hello, [user]." next to the sign out button. This is the user account reported to WIN-911.
However, if the user has not accepted an invitation yet, an error screen will be displayed stating that the user account is not in tenant WIN-911. This will be the user account reported to WIN-911.
This user account needs to be the same as listed in the WIN-911 Workspace. This user account also needs to be able to receive emails, even if just briefly, so it can accept the invitation email. If necessary, create an email alias for the UPN, enter it into WIN-911, accept the invitation, confirm the app works, then disable the email alias. The authentication will continue to work properly even if the email alias is disabled. Please note, though, if you ever need to rebuild the connection then this alias will need to be re-enabled.
B. Changing Email Address
WIN-911 uses a series of unique identifiers to link accounts between the different modules of WIN-911, the Mobile Gateway cloud server, and the mobile app. These identifiers are not intended to be broken, and as such, any changes to the connection's key components (username/address) will require the connection to be rebuilt. You can change permissions levels (whether or not a user can acknowledge alarms, what alarms they can request, etc) without rebuilding a connection.
If a user has a new email address, we recommend removing the old connection from the system and adding a new one. This will ensure that all links are created properly, and you don't run into issues where you can receive notifications without actually seeing the alarm data, or being able to acknowledge. For more information on how to rebuild an account, see the next section.
3. Connection Rebuilding
If you have a user account that seemed to be working, but suddenly isn't getting alarms properly, has errors in their app, and it's localized to a single user, you may want to rebuild their connection in WIN-911. There are a few steps to this process to confirm that it works and goes through without issue.
A. Sign User Out
If the user is still signed into their app, have them check their reported user account. For iOS, this is on the Settings page, under the Other heading, next to the Logout button. For Android, this is in the menu flyout, at the top of the list, underneath the WIN-911 Mobile logo. Note this account for later, to ensure it's the same as their email account (See 2.A above).
The user should then sign out of the WIN-911 Mobile app, and close the app completely so that it is not running in the background. This clears the app's connection cache.
B. Remove User from System
We need to remove the connection from WIN-911. Inside WIN-911 Workspace, locate the user's contact. Edit the contact by selecting it and clicking "Configure Contact", or by double-clicking the user in question. For V4 users, the connection is located under Contact > Connections > WIN-911 Mobile instead.
Click the drop arrow to the left of the connection to expose the options, then click the drop arrow next to "Used By" and make sure this is clear, saying "No objects are using this item". If it lists a callout list or workflow, make sure to remove the connection from that list. V4 Users can check the Utilizers tab of the connection, and ensure it's not listed in any Tactics. Take note of its settings so that you can restore the connection once the rebuild is complete. This includes whether or not it can ack alarms, what position in callout lists it was in, and whether or not it had any delays.
Once the connection is no longer utilized, click the Delete button to remove it from the system. There is one other place the connection exists in, and it's in the Online Gateway. Open the Online Gateway Management page found here: https://win911mobileproduction.azurewebsites.net/Routes/Routes and sign in with your [serial]@win911mobile.com credentials. Once signed in, it should show you a list of all connections tied to your sites. Make sure the connection you want to remove is no longer listed. If it is, select it using the check box on the left hand side, then click the Delete button in the bottom right.
Once this is complete, the user is no longer referenced in the system and is clear to be rebuilt.
C. Add User to System
At this point, return to your WIN-911 Workspace and add a new WIN-911 Mobile connection. Verify that the email address entered is correct, is able to receive emails, and, if applicable, matches the UserPrincipalName reported from the app/site. You can also use this time to set any additional settings for the user before hitting save.
Once a connection is saved, it queues an email invitation to be sent. Have the user check their inbox for the next 5-10 minutes. If they do not receive the invitation email, you can click the 'Re-send invitation' button in the Workspace. If they still do not receive it after another 5-10 minutes, have them check their spam filter. If the email still does not appear, you may need to restart the WIN-911 Mobile Runtime, which we will document in the next section.
Once the user receives their email invitation, they just need to click the 'Accept Invitation' text at the bottom of the message. If the email address entered is already associated with a Microsoft Account, it will take them to a sign in screen with WIN-911's branding. They just need to enter their email address and password. However, if the email address is not associated with a Microsoft account (such as a Gmail or Yahoo account), it will prompt them to create a password for a Microsoft account.
Once they have signed in successfully, they will be taken to https://win911mobileproduction.azurewebsites.net/ which should report their username in the top right, and tell them they can now sign into the mobile app. Before they sign in, please verify that they are now listed in the Online Gateway Management page here: https://win911mobileproduction.azurewebsites.net/Routes/Routes sign in with your [serial]@win911mobile.com credentials. If you were still signed in from the previous step, you may need to refresh.
If for some reason their connection does not show up in the Online Gateway Management page, please contact WIN-911 Support as there may be something wrong with their account. Our support staff will be able to help discern any trouble you are having.
D. Sign In to App
Once the user is listed in the Workspace and in the Online Gateway Management, they should be ready to log in to the WIN-911 Mobile app. Open the app, tap the Login button, enter your credentials and await sign in. First, make sure you receive no errors on the Alarms page. Then, open your Settings and make sure that the site you're looking for is listed under the Allow Notifications section.
At this point, return to the Alarms page and tap the icon in the top right of the interface. This should open the alarm request function. Leave the settings the same and tap the "Request" button on the right. If it returns a number of alarms, or 0 alarms, the app is functioning and the system is sending data to the mobile phone. If you get an error retrieving alarms, please contact WIN-911 Support, as this may be indicative of some networking or service issues with your system.
4. WIN-911 Mobile Runtime service
WIN-911's Mobile communications all run through the WIN-911 Mobile Runtime service. When the dispatcher queues a notification event, or a user requests information from the system via the app, the Mobile Runtime is responsible for handling these connections. However, there can be communications issues or configuration issues that may require you to reset the connection. This happens each time the Mobile Runtime starts up, and so if you are having unexplainable Mobile issues, we advise checking a few things.
1. Restart Service
If you encounter any unexpected errors, please restart the Mobile Runtime service. This can be found by opening Windows Services (services.msc), scrolling through the list to find WIN-911 Mobile Runtime, then restarting it. Please stop and start the service using the Services app, or the Services tab of Task Manager. Other methods may cause damage to the configuration files and/or database.
If you are using a Mobile Hub in your setup, you will also need to restart your Mobile Hub service as well. It will be listed in the same place on your Hub machine, just with the service named WIN-911 Mobile Hub.
Restarting the service can be followed up by a login test in the Workspace. Open the Mobile Gateway settings and locate the Test Gateway button. A successful test will have a green checkmark followed by "Communication established with Mobile Cloud." Failed tests will return a red cross and the error message encountered. Any errors at this stage should be reported to WIN-911 Support for assistance.
2. Network Testing
WIN-911 requires access to several sites for successful authentication and communications. However, if the traffic exceptions are implemented incorrectly, the app can still function halfway, but give errors that are hard to track down. If your mobile app is receiving push notifications, but seems to have trouble retrieving alarm information or handling acknowledgements, it is likely that port 443 is open, but the other required ports are still blocked, causing an issue. Also, if the system was working initially, but now fails to work, you may have lost connection to login.microsoftonline.com, which is used for authenticating the WIN-911 system to the Azure cloud.
For quick testing, on your WIN-911 System (or your Mobile Hub system, if using that), visit the following three websites:
https://login.microsoftonline.com (port 443)
https://win911mobileproductionrelay.servicebus.windows.net (ports 5671, 9350 - 9353)
Please make sure that all of these sites resolve DNS. The final one does not need HTTPS 443 communication to function, but it does need to return an accurate IP address. For further information, you can review our WIN-911 2021 - Mobile Security Overview article.
To create a support case, you will need either your Customer Care Code or your Serial number. You can create a Case online or contact the product support line: (512) 326-1011.