BlackBerry AtHoc Networked Crisis Communication Localization Guide Release 7.5, May 2018
Copyright 2018. BlackBerry Limited. All Rights Reserved. This document may not be copied, disclosed, transferred, or modified without the prior written consent of BlackBerry Limited. While all content is believed to be correct at the time of publication, it is provided as general purpose information. The content is subject to change without notice and is provided as is and with no expressed or implied warranties whatsoever, including, but not limited to, a warranty for accuracy made by BlackBerry Limited. The software described in this document is provided under written license only, contains valuable trade secrets and proprietary information, and is protected by the copyright laws of the United States and other countries. Unauthorized use of software or its documentation can result in civil damages and criminal prosecution. Trademarks Trademarks, including but not limited to ATHOC, EMBLEM Design, ATHOC & Design and the PURPLE GLOBE Design are the trademarks or registered trademarks of BlackBerry Limited, its subsidiaries and/or affiliates, used under license, and the exclusive rights to such trademarks are expressly reserved. All other trademarks are the property of their respective owners. Users are not permitted to use these marks without the prior written consent of AtHoc or such third party which may own the mark. This product includes software developed by Apple (http://www.apple.com). This product includes software developed by Google (http://www.google.com). Patents This product includes technology protected under patents and pending patents. BlackBerry Solution License Agreement https://us.blackberry.com/legal/blackberry-solution-license-agreement Contact Information BlackBerry AtHoc 2988 Campus Drive, Suite 100 San Mateo, CA 94403 Tel: 1-650-685-3000 Email: athocsupport@blackberry.com Web: http://www.athoc.com
Contents CHAPTER 1: OVERVIEW 1 CHAPTER 2: SUPPORTED LOCALES 2 CHAPTER 3: ORGANIZATION LOCALES 3 Identify an organization locale/language 3 Change the default organization locale settings 3 Impact of localization on the operator user interface 4 CHAPTER 4: DELIVERY LOCALES 10 Set delivery locales for an organization 10 Select a delivery locale for an alert 10 CHAPTER 5: PHONE NUMBER VALIDATION 13 Overview 13 Areas of the system that validate phone numbers 13 Validation rules 13 Best practices 14 Special note 15 APPENDIX A: SUPPORTED CHARACTERS 16 APPENDIX B: LOCALIZED AND NON-LOCALIZED PAGES IN BLACKBERRY ATHOC 17 1
Chapter 1: Overview Chapter 1: Overview A locale is a specific dialect of a language spoken in a region such as Canadian French, Mexican Spanish, and American English. Localization is the process of customizing an application for a given language and region. This document describes how the BlackBerry AtHoc Networked Crisis Communication system has been localized to accommodate users in locales beyond US English. Within the BlackBerry AtHoc system, Organization locales define the way the UI appears to Operators, while Delivery locales define the way BlackBerry AtHoc alerts appear to alert recipients. Although an Organization can be associated with only one Organization locale, it can be associated with multiple Delivery locales. This is explained in the Set delivery locales for an organization section of this guide. This first part of this document lists the organization locales supported by the BlackBerry AtHoc system. The second part explains the process by which the system determines a user's locale and the impact of localization on the Operator user interface. The third part explains how to set Delivery locales for an organization and how to specify a Delivery locale when creating an alert. The appendices contain a table listing the characters supported in the system and a list of the localized and non-localized pages in the BlackBerry AtHoc system. 1
Chapter 2: Supported locales Chapter 2: Supported locales Each organization created within the BlackBerry AtHoc system is associated with one of the following nine language/locale combinations. This combination cannot be changed after it has been set. Dutch (Netherlands) English (UK) English (US) French (Canada) French (France) German (Germany) Italian (Italy) Spanish (Mexico) Spanish (Spain) Organizations created at the Enterprise level within the same system can have different language/locale combinations associated with them. So, for example, an organization set to Spanish (Spain) can exist in the same system as an organization set to French (Canada), as long as neither one is a sub-organization of the other. All organizations created as sub-organizations of an Enterprise organization are automatically assigned to the same language/locale combination as the Enterprise organization. So, for example, if an Enterprise is set to the Spanish (Spain) language/locale, then all of its suborganizations will also be set to Spanish (Spain). All text in the Operator UI is locked to the selected locale, so all Operators within the same organization see the same language displayed throughout the BlackBerry AtHoc system. 2
Chapter 3: Organization locales Chapter 3: Organization locales Organization locales define the way the user interface appears to Operators. In addition to determining the language to be displayed on BlackBerry AtHoc screens, the Organization locale determines the language of the default templates available to Operators. These templates include the default date, time, and phone number formats displayed in the user interface and the language of the in-product guided tours. Identify an organization locale/language When you access the BlackBerry AtHoc system login screen for the first time, the system has no way of knowing what organization you belong to or what language you will be viewing the system in. The system decides which language to display on the Log In screen by running through the following series of checks: 1. The system searches for any language-related cookies in your browser from past log ins. If you have never logged in before, the system cannot make a determination about the language to display, so it proceeds to the next check. 2. The system tries to use the browser s preferred locale information to determine the language to display. If the preferred language is not supported within BlackBerry AtHoc or if there is no browser preferred locale information, the system proceeds to the next check. 3. In the absence of any language preference indicators, the system displays US English by default. The bottom of the Log In page contains a language selection dropdown list that enables you to switch the language displayed on the Log In, Forgot Username, and Forgot Password screens. Regardless of the language that you select from the dropdown menu, when you successfully log in to the system, the language that is displayed will match the language associated with your organization. So if you set the Log In screen to display UK English, but your organization is associated with US English, you will see UK English before you log in and US English after you log in. Change the default organization locale settings Operators with the necessary permissions can change the default Organization locale settings for their organization by completing the following steps: 3
BlackBerry AtHoc Localization Guide 1. Log in to the BlackBerry AtHoc system. 2. Click the (Settings) icon in the top Navigation bar. The Settings screen opens. 3. In the Basic section, click the General Settings link. 4. On the Settings screen, scroll down to the Locale Setting region. 5. Select the value that you want to use as the default in each of the following lists: o o o Date Format Time Format Time Zone 6. (Optional) In the Phone Call Settings region, change the value in the Default Country Code field. 7. Click Save. Impact of localization on the operator user interface The language/locale that is selected affects the following features and components of the Operator user interface: Operator facing pages, excluding some Administrative pages that will be localized in a later release. The image below shows the BlackBerry AtHoc Homepage localized for the Italian (Italy) locale. 4
Chapter 3: Organization locales For a list of the manager screens that have been localized for this release, refer to Appendix A, Localized and non-localized pages in BlackBerry AtHoc. Out of the box default content, including alert templates, distribution lists, user attributes, and delivery templates. The following image shows the Target Users section of an out-of-the-box alert template localized for the Dutch (Netherlands) locale. Date/time default formats. The following image shows the User Details screen localized for the Dutch (Netherlands) locale, with the date and time information presented in the format most commonly used in the Netherlands. 5
BlackBerry AtHoc Localization Guide The default Date, Time, and Time Zone values for a locale can be overwritten by modifying the corresponding fields on the Settings screen. Refer to the Change the default organization locale settings section of this guide for more information. Phone default formats. The following image shows the out-of-the-box settings for phone numbers on the New User screen, localized for UK English. The British flag icons in each field indicate that all numbers will be automatically prefaced with the British country code 44. The default country code for a locale can be overwritten by modifying the corresponding field on the Settings screen. Refer to the Change the default organization locale settings section of this guide for more information. The self-service experience. The following image shows the User Profile screen within Self Service, localized for the Spanish (Mexico) locale. 6
Chapter 3: Organization locales The in-product guided tours of BlackBerry AtHoc features and functionality. The following image shows the screen that lists all of the guided tours related to the Homepage, localized for the Spanish (Mexico) locale. Although not visible in this image, the text that appears within each tour is also localized to the Spanish (Mexico) locale. The system tray menu for connected desktop applications. The following image shows the menu localized for the French (France) locale. 7
BlackBerry AtHoc Localization Guide Desktop alerts. The following image shows a desktop alert localized for the French (France) locale. Mobile alerts. For the mobile phone app, the app locale is based on the operating system settings of the phone. If you change your operating system settings, the app will display in the language of your phone, regardless of the delivery locale of a single alert or your organization s settings. The following image shows the same alert as the desktop alert above, but displayed on a mobile phone with its operating system set to French (France). 8
9 Chapter 3: Organization locales
Chapter 4: Delivery locales Chapter 4: Delivery locales Delivery locales define the way alerts appear to alert recipients. In addition to localizing the delivery envelope of an alert the hard-coded text in the alert, such as the Severity, Type, and Response Options titles and the Copyright information the Delivery locale is used by the Text-to-Speech engine to determine how to pronounce the alert content when it is read aloud by the system. For the mobile phone app, the app locale is based on the operating system settings of the phone. If you change your operating system settings, the app will display in the language of your phone, regardless of the delivery locale of a single alert or your organization s settings. Set delivery locales for an organization Administrators with the necessary permissions can set the delivery locales for their organization by completing the following steps: 1. Log in to the BlackBerry AtHoc system. 2. Click the (Settings) icon in the top Navigation bar. The Settings screen opens. 3. In the Basic section, click the General Settings link. 4. On the Settings screen, scroll down to the Customization region and locate the Locale Setting fields. 5. In the Delivery Locales field, select each of the delivery locales you want to make available to alert creators within your organization. Note: Once enabled, support for a delivery locale cannot be disabled. 6. Click Save to associate the delivery locales with your organization. Select a delivery locale for an alert During the creation of an alert, an Operator can specify a Delivery locale that is different from the Organization locale. Only one Delivery locale can be associated with an alert, so if you need to 10
BlackBerry AtHoc Localization Guide send an alert in multiple languages, you must create separate alerts for each language. To select a Delivery locale for an alert, complete the following steps: 1. Navigate to the alert creation screen by either clicking the Create a Blank Alert link or by modifying an existing alert or alert template. 2. In the Content section of the alert creation screen, click the language button and select the Delivery locale you want to use for the alert. Note: Changing the Delivery locale of an alert has no impact on the language displayed in the UI. The Organization locale, which cannot be changed, controls the display language of the fields within the BlackBerry AtHoc system. 3. Create the alert, entering text written in the language that matches the Delivery locale. 4. Publish the alert. Alert recipients then receive an alert that is fully localized. The Operator-provided content and the Delivery template the field names and preset, unchangeable content match the Delivery locale. If a Text-to-Speech engine is used to listen to the alert, all preset and Operator- 11
Chapter 4: Delivery locales provided content is read aloud in the language of the Delivery locale. 12
Chapter 5: Phone number validation Overview An Emergency Mass Notification System is only as effective as the contact information it contains. For this reason, BlackBerry AtHoc provides a phone number validation feature that applies to all phone numbers, no matter which country they belong to. It also enforces clean data wherever data can be entered. The validation feature gives operators higher confidence before an alert is sent that end users with phone numbers are reachable. One way it does this is by ensuring that end users completing selfservice profiles enter actual phone numbers, instead of invalid data such as No Phone or N/A. Validating phone numbers when they are created in the system makes the alerting process more rapid and efficient by preventing the Telephony Delivery Service from wasting time trying to send telephone notifications to invalid numbers. BlackBerry AtHoc provides this feature alongside other improvements for customers operating outside or calling users who are outside the United States. Validated phone numbers can be stored in the internationally recognized E.164 format, ensuring that alerts sent by delivery services deployed throughout the world will reach their destinations. BlackBerry AtHoc uses a third-party library to validate phone numbers. BlackBerry AtHoc plans to work with customers to make sure that automated data imports, including Active Directory sync, CSV imports, and direct SDK integrations, will send phone numbers to the server in the correct format. The following sections provide the validation rules and best practices for getting the most out of this feature. Areas of the system that validate phone numbers The following inputs will use the same set of phone number validation rules: AtHoc SDK LDAP/Active Directory Sync module CSV Import Self Service User Details page in the Management System Validation rules The following validation rules are delivered by a third-party open source component. For more information, see: https://github.com/googlei18n/libphonenumber. 1. E.164 international format is preferred and is always accepted. The number should start with + followed by the country code and then the full number to call. A maximum of 15 digits can be used. For example: +18884628462 13
2. Numbers can have an extension. The user interface has a separate field for telephone extensions. When importing numbers, an x should be used to separate the main number from the extension. When dialing, the Telephony Delivery Service will wait for the call to connect before dialing the extension. For example: +18884628462x1340 Unlike the phone number field, the extension field is not validated. 3. Numbers not in E.164 are interpreted based on the Default Country Code for the Organization. The Default Country Code can be set on the General Settings screen in the Phone Call Settings section. For example, for the Country Code US, the following rules apply: If the number starts with 011, which is the international exit code from within US, it will be replaced with +. If the number contains only 10 digits, it will be stored as +1 followed by the number. If the number contains 11 digits and starts with 1, it will be stored as +1 followed by the number. For example: (888) 462-8462 will be interpreted as +18884628462 4. Common formatting punctuation is ignored. The following characters are removed: ().-_ For example: +1 (888) 462-8462 will be interpreted as +18884628462. If you are using control characters such as, (comma) or # (pound sign), they must be in the extension field. 5. If the number contains letters, they will be converted to numbers according to a standard keypad. For example: (888) Go AtHoc will be converted to +18884628462. 6. If the number starts with +, it will be assumed to be an international number. For example: A number starting with +440 will dial the UK, even though 440 is a valid US area code. Best practices Send all numbers in E.164 format. Although E.164 format is not required, it is the best way to send a number to the system, especially if user data can contain numbers from different countries. 14
Make sure you set the correct Default Country Code in the Phone Call Settings section on the General Settings screen. This specifies what country is the default for user-entered phone numbers. This also is used to interpret phone numbers that are not in E.164 format. If the number contains any special control characters that must be dialed, such as, (comma) ; (semicolon) * (asterisk) or # (pound sign), the characters must be part of the extension. This is especially important for numbers that connect to a conference bridge. Special note If you are unable to comply with the new validation rules, fields that do not contain valid phone numbers will not be updated. For BlackBerry AtHoc versions 6.1.8.88 and earlier, you must continue to use 011 instead of + at the beginning of all international phone numbers. BlackBerry AtHoc IWS version 6.1.8.89 and later fully support the leading + method. Dialing 011 will continue to be supported after upgrade to 6.1.8.89 for organizations with a US country code since 001 is the US exit code. 15
Appendix A: Supported characters The BlackBerry AtHoc system supports Windows-1252, a set of characters that includes all of the foreign characters that are required for the languages currently supported in the system. For additional details about Windows-1252, see https://en.wikipedia.org/wiki/windows-1252. In addition, some of the key fields for alerting support the Unicode character set, which is much larger than Windows-1252. This is important because it enables users to create alerts that have delivery locales that are different from the Organization locale. For more details, see Select a delivery locale for an alert. The following table defines which fields in BlackBerry AtHoc allow which characters: Text fields or components Allowed characters Notes User profile fields Username All fields on General Settings page: Name, Organization Code, Name on User Pages, Homepage Welcome Message, Footer Text Friendly Name for User Attributes Friendly Name for Device Common Name: Devices, User Attributes, User Attribute Values Values: Device Values, User Attribute Values, Organization Hierarchy XML Layouts: Self Service, User Detailed Layout including Section names, Page Details, help sections Import and Export Users with CSV Supported alpha-numeric characters 1 Supported alpha-numeric characters 1 Supported alpha-numeric characters 1 Supported alpha-numeric characters 1 Supported alpha-numeric characters 1 Supported alpha-numeric characters 1 Supported alpha-numeric characters 1 Supported alpha-numeric characters 1 Alert Title, Alert Body Unicode support Alerting Avoid spaces and these characters [ ] : ; =, + *? < > Avoid special characters in general. `! $ % ^ ( ) = { }, ; :? " < > Avoid special characters such as `!$%^()={}.,;\:?"<> [] &. Although the UX supports Unicode, it will break other flows like import, SDK Sync. Avoid special characters such as `!$%^()={},;\:? <> Avoid special characters such as `!$%^()={}.,;\:?"<> []& Keep the values for attributes to sup-ported characters. Special characters create problems when searching for or targeting users. The "&" special character is supported. Use the XML escaping for characters for < > & ' and ". System will show error messages if these are typed in directly. Response Options Unicode support 1 The following alphanumeric characters are supported: 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz ÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖØÙÚÛÜÝÞß àáâãäåæçèéêëìíîïðñòóôõöøùúûüýþÿ ŒœŠšŸŽžƒ 16
Appendix B: Localized and non-localized pages in BlackBerry AtHoc Localized Home Page New Alert page Alert Templates Delivery Templates Audio Files Incoming Alert Rules Connect Profile Security Policy Invite Organization to Connect Invitations Hierarchy Builder Inbox Sent Alerts and Alert Reports User Manager Distribution List Manager Connected Organizations User Attributes Alert Folders General Settings Alert Placeholders Change Organization My Details Disable and Delete End Users Operator Audit Trail Organizations Manager Activity Log Complete a Task Online Help Not localized Organization Settings Mobile Alert Settings Situational Settings Map & Layers Global System Health System Health Diagnostic Log Archive Device Manager Alert Usage Summary Report User Summary Report Personnel Reports Help & Support Page IIM Management Advanced Operator Manager Integration Manager Mass Devices Manager AtHoc Cloud Delivery Gateways AtHoc Connect Gateway Desktop App menu Other Gateways Advanced Alert Reports 17