ZEBRA Workforce Connect PTT Pro Location Area Service User Guide

ZEBRA Workforce Connect PTT Pro Location Area Service

Copyright
ZEBRA and the stylized Zebra head are trademarks of Zebra Technologies Corporation, registered in many jurisdictions worldwide. All other trademarks are the property of their respective owners. ©2021 Zebra Technologies Corporation and/or its affiliates. All rights reserved.
Information in this document is subject to change without notice. The software described in this document is furnished under a license agreement or nondisclosure agreement. The software may be used or copied only in accordance with the terms of those agreements.
For further information regarding legal and proprietary statements, please go to:
SOFTWARE: zebra.com/linkoslegal.
COPYRIGHTS: zebra.com/copyright.

WARRANTY

zebra.com/warranty.

END USER LICENSE AGREEMENT: zebra.com/eula.

Terms of Use

Proprietary Statement

This manual contains proprietary information of Zebra Technologies Corporation and its subsidiaries (“Zebra Technologies”). It is intended solely for the information and use of parties operating and maintaining the equipment described herein. Such proprietary information may not be used, reproduced, or disclosed to any other parties for any other purpose without the express, written permission of Zebra Technologies.

Product Improvements

Continuous improvement of products is a policy of Zebra Technologies. All specifications and designs are subject to change without notice.

Liability Disclaimer

Zebra Technologies takes steps to ensure that its published Engineering specifications and manuals are correct; however, errors do occur. Zebra Technologies reserves the right to correct any such errors and disclaims liability resulting therefrom.

Limitation of Liability

In no event shall Zebra Technologies or anyone else involved in the creation, production, or delivery of the accompanying product (including hardware and software) be liable for any damages whatsoever (including, without limitation, consequential damages including loss of business profits, business interruption, or loss of business information) arising out of the use of, the results of use of, or inability to use such product, even if Zebra Technologies has been advised of the possibility of such damages. Some jurisdictions do not allow the exclusion or limitation of incidental or consequential damages, so the above limitation or exclusion may not apply to you.

This guide provides information about using the Workforce Connect Location Area Service (WFC Location Area Service).
NOTE: Screens and windows pictured in this guide are samples and can differ from actual screens.

Chapter Descriptions

Topics covered in this guide are as follows:

• About this Guide provides an explanation of document conventions and related documentation.
• Getting Started provides information about accessing and logging in to WFC Location Area Service.
• Location Area Service Configuration provides information about administering and configuring  WFC Location Area Service.
• WFC Location Area Service REST API provides information about updating information in WFC Location Area Service.

Notational Conventions

The following conventions are used in this document:

• Bold text is used to highlight the following:
  • Dialog box, window and screen names
  • Drop-down list and list box names
  • Checkbox and radio button names
  • Icons on a screen
  • Key names on a keypad
  • Button names on a screen.
• Bullets (•) indicate:
  • Action items
  • List of alternatives
  • Lists of required steps that are not necessarily sequential.
• Sequential lists (for example, those that describe step-by-step procedures) appear as numbered lists.

Related Documents

For the latest version of this guide and all guides, go to zebra.com/support

Service Information

If you have a problem with your equipment, contact Zebra Global Customer Support for your region.
Contact information is available at: zebra.com/support.
When contacting support, please have the following information available:

• Serial number of the unit
• Model number or product name
• Software type and version number

Zebra responds to calls by email, telephone, or fax within the time limits set forth in support agreements.
If your problem cannot be solved by Zebra Customer Support, you may need to return your equipment for servicing and will be given specific directions. Zebra is not responsible for any damages incurred during shipment if the approved shipping container is not used.
Shipping the units improperly can possibly void the warranty.
If you purchased your Zebra business product from a Zebra business partner, contact that business partner for support.

This guide is intended for Customer administrators when configuring the Location Area Service.

This chapter covers the following topics:

• Introduction to WFC Location Area Service (LAS)
• Process Overview
• Prerequisites
• Location Area Service Administration URLs

Introduction to WFC Location Area Service

WFC Location Area Service (LAS) provides a capability to provide friendly names to wireless Access Points (APs).
As users move throughout the facility, the APs continually report the location of the user using the user-friendly name.
The following is an example of the concept of wireless access points within a facility:

Figure 1    Location Area Service for a Store

The WFC Location Area Service portal allows customers to view the BSSID/Location Name along with other information fields to assist with administration tasks. The LAS portal also provides an import APs function, which allows addition/changing of BSSID/Location Names.
When LAS is configured correctly, the location information displayed represents the user association to an Access Point. Depending on the user’s connection to the access point, this association of the user to an AP might an AP different from the nearest AP.

Process Overview

Configuring the LAS Server consists of the following steps:

1. Configuring the PTT Pro Android client with the necessary information to access the LAS Server.
2. Configuring the LAS Server with the AP information.

Prerequisites

The following prerequisites are mandatory to enable for the WFC Location Area Service:
Table 1    Prerequisites – Customer Administrator

customer https://prod1-essentials.pttpro.zebra.com:9443/apname/v1/ swagger- ui.html?urls.primaryName=Api
Prerequisites Data| Description
---|---
LAS Instance Portal URL| Required to access the portal and manage LAS data. Portal URL https://prod1-essentials.pttpro.zebra.com/
LAS URL for PTT Pro Application| Required to configure the PTT Pro app to connect to the LAS and provide location information. This URL is

specified in the wfclasServerURL parameter https://prod1- essentials.pttpro.zebra.com:9443/apname/v1

Customer ID| Required for PTT Pro clients to use LAS, as well as for direct use of the LAS API. Zebra provides the Customer ID to the customer.
API Key (token)| Required for PTT Pro clients to use LAS, as well as for direct use of the LAS API. Zebra provides the API Key (token) to the customer.
Customer Username and Password| Required to log in the LAS Portal, where customer can import a CSV file containing AP information. See Import File Format information regarding the CSV file format.
WFC PTT Pro Client Version| Use version 3.2.10087 or later.
WFC PTT Pro JSON file| Current PTT Pro JSON file. LAS objects are added to this file as mentioned in PTT Pro Client Configuration on page 12.
Device location MUST be enabled| This is required to access the associated BSSID information and to pass it to the WFC Location Area Service Server.
Access Points Configuration Information| Mapping information between BSSIDs and Location Friendly Name for each site is required. For more information on these fields, see Import File Format.
Site for Each PTT Pro Client| The proper site must be identified for each user.

Location Area Service Administration URLs

The following URLs point to the default WFC Location Area Service Server.

URL for Web Portal

https://prod1-essentials.pttpro.zebra.com
Figure 2    Location Area Services Login Screen

URL for Swagger / APIs

https://prod1-essentials.pttpro.zebra.com:9443/apname/v1/swagger-ui.html
Figure 3    Swagger API Screen

Location Area Service Configuration

This chapter covers the following topics:

• Administration Steps
• PTT Pro Client Configuration
• Sample PTT Pro Client Screenshots

Administration Steps

This section describes the procedures to set up the AP database for the LAS Server. There are two methods for setting up and modifying this database. This section describes doing a bulk upload of AP information using the LAS Portal. This is the simplest method of loading the initial AP database.
Refer to the LAS API REST API  for information on modifying individual APs and users (i.e. the PTT Pro client users).

Prerequisites for uploading CSV files follows:

• Customer Wireless Access Point (WAP) Infrastructure for each site
  • List of APs with listed identifiers
  • BSSID for each AP
  • User-friendly name for each BSSI
• LAS  Portal Administrator privileges

Procedure to set up Location Area Service follows:

1. Create a CSV file, The file format is  described in Import File Format (CSV) .
2. Log in to https://prod1-essentials.pttpro.zebra.com .
3. Navigate to  Imports AP page.
4. Select and upload the CSV file.
5. Navigate to Home page to verify the additions.

PTT Pro Client Configuration

PTT Pro Client applications are configured via the JSON file to enable LAS capabilities.

The JSON file includes the following:

• LAS URL (defined in table 1)
• Token/API-key (defined in table 1)
• Site ID for this device. This is the same as the site name defined in the CSV that was created and imported in
• Customer ID (defined in table 1)
• ShowServerConfig parameter, which controls whether the user of this device can view LAS parameters in PTT Pro.

These parameters are necessary to accurately correlate the client to a customer and a site to exchange LocationFriendlyNames based on associated BSSID.
If you already have a PTT Pro Android Client JSON file, this parameters can be inserted into the existing file.

NOTE: This sample shows only LAS objects.

• {
• “wfclasShowServerConfig”:true,
• “wfclasServerURL”:https://prod1-essentials.pttpro.zebra.com:9443/apname/v1,
• ” wfclasServerToken”:”insert_your_token”, “
• wfclasSiteID”:”insert_your_site”, “
• wfclasCustomerID”:”insert_your_customer_id”
• }

NOTE: When LAS is used with WFC Profile Client, the Site ID and Customer ID are not required in the JSON file.

Sample PTT Pro Client Screenshots

The following samples screenshots display the location-related information that is available in the Contacts and Favorites screens for users who are both online and configured to provide user location to the LAS server.

Figure 4    PTT Pro Client Screens

WFC Location Area Service REST API

The WFC LAS REST API is used to manage sites, APs, and AP users.
The API can be accessed using tools like Curl, Postman, built in Swagger interface, or programmatically.

The WFC LAS Swagger API provides three specifications:

• Tenant – Used by the Zebra administrator  to manage customers on the multi-tenant LAS server.
  This specification is visible but not accessible by the customers.

• API – Used by customer to manage access points and Portal.

• Portal – Currently unused.

The API specification is described below. This documentation assumes that the reader is familiar with REST APIs and  Swagger.

Prerequisites for LAS Configuration

To use the API Swagger Specification, the following information is required:

• The URL of the appropriate LAS server.

• Customer ID and Customer API Key are provided by Zebra.
  If you do not have this information, contact https://www.zebra.com/ap/en /about-zebra/contact-zebra.html

• Parameter Information for the specific methods being used.

When using methods in the API Swagger Specification, the following headers must be included:

• The API-Key header must be populated with the Customer API Key.
• Customer ID header must be populated with the Customer ID.

When using Swagger directly, click the green Authorize button at the top right and enter the Customer ID and Customer API Key.

API Specification

The API Specification includes the Access Point API controller and the Access Point User API controller and is used to set up the customer Access Point database..

• Sites are locations, which may be different stores, hospitals, or other entities that have different AP and AP user information. Sites are not explicitly added, but created when the APs are added. The specification allows displaying sites.

WFC Location Area Service REST API

• Access Points, or APs, are the Wi-Fi entities in which AP Users are attached to and used for communication. The specification allows adding, deleting, and displaying APs.  APs are uniquely defined by BSSID and may also be identified through an Asset Name. APs are associated with a location-related name which can be displayed to users.
• AP Users are the users/devices those are  attached to the APs. The specification allows adding, deleting, and retrieving AP users.

The REST API Specification can be found at https://prod1-essentials.pttpro.zebra.com:9443/apname/v1/swagger-ui.html and and is described in the LAS Customer Administrator Guide.

Customer Specification Controllers

Customer Specification Controllers

• Access Point Controller – Provides methods to add, delete, and get Access Points.
• Get All Access Points – Returns all APs in JSON format.
• Create New Access Point Entry – Creates an AP.
• Get Access Point by BSSID – Returns information for the AP as identified by BSSID plus Site ID.
• Delete Access Point by BSSID – Deletes the AP as identified by BSSID plus Site ID.
• Export Access Point Entries – Exports all APs in a CSV file with the same format as the import CSV file, with the addition of the Date  Added and Date Modified columns.
• Import Static Access Point Tables from CSV File – Uploads a CSV file as input and adds the APs contained in it.
• Get All Sites – Returns all site names.
• AP User Controller – Provides methods to associate AP users (For example, PTT Pro Users or Assets) with APs, deletes the associates, and retrieves AP user information through Access Point or User ID.
• Create New Access Point User – Creates or updates the association between a user ID and a particular site / BSS.
• Delete User Info for the User ID – Deletes the AP user as identified by user ID and site ID.
• Get All Users Info for the Access Point BSSID – Returns the user and AP information for all users associated with a specific BSSID and site ID.
• Get All Users Info for the List of User IDs – Returns the user and AP information for the users identified by a list of User IDs and site ID.
• Get User Info for the Access Point by User ID – Provides user and AP information for the user identified by user ID and site ID.

Using curl to add an Access Points

The following example provides the information about how to add an AP using Curl:

curl -X POST “https://:9443/apname/v1/api/ ap” -H “accept: /” -H “API-Key: key0” -H “customerId: 0” -H “Content-Type: application/json” –  d “{ \”ap_created_name\”: \”Plumbing\”, \”bssid\”: \”B8-8A-60-61-8E-E7\”, \”name\”: \”ap-name\”, \”siteId\”: \”store1\”}”

Parameters

The following parameters are used in the API Swagger Specification:

Table 2    API Swagger Specification Parameters

displays this name when the client is associated with access point. Usually, it is the department name in the store.
userId| User associated with access point.

Import File Format

Importing Access Point information requires a named CSV file containing minimum fields. The content management of this CSV is important as the content represents the Location Friendly Name that is displayed in relation to the associated BSSID.
NOTE: The CSV file format must be without UTF-8.
The field description of  CSV file should contain the follows:
Table 3    CSV File Fields with Description

each store.
Used with JSON file and to import to associate BSSID and facility site name.
NOTE: When LAS is used with the Profile Client, the LAS SiteName must match with the SiteID configured in the Profile Client.
BSSID| Format must be a 12-digit hexadecimal MAC Address format with character pairs separated by colons. characters separated by colons. Other formats are not accepted.
AssetName| This is the name that the customer may use – i.e. Cisco5340, which is not displayed in the client UI. It allows 64 alpha-numeric characters, spaces, and special characters.
CSV File Fields| Description
---|---
LocationFriendlyName| Referred to “AP Created Name” in the portal. This is the name that is displayed in the client UI. It allows 32 alpha-numeric characters, spaces, and special characters.

Table 4    Sample CSV File

www.zebra.com

References

• WFC Location Area Services
• prod1-essentials.pttpro.zebra.com:9443/apname/v1
• prod1-essentials.pttpro.zebra.com:9443/apname/v1/
• Swagger UI
• WFC Location Area Services
• Contact Zebra

Read User Manual Online (PDF format)

Download This Manual (PDF format)

Download this manual  >>