ZEBRA Workforce Connect PTT Pro Location Area Service User Guide
- June 8, 2024
- ZEBRA
Table of Contents
- ZEBRA Workforce Connect PTT Pro Location Area Service
- WARRANTY
- Terms of Use
- Notational Conventions
- Introduction to WFC Location Area Service
- Process Overview
- Location Area Service Administration URLs
- Location Area Service Configuration
- WFC Location Area Service REST API
- API Specification
- WFC Location Area Service REST API
- References
- Read User Manual Online (PDF format)
- Download This Manual (PDF format)
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
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:
- Configuring the PTT Pro Android client with the necessary information to access the LAS Server.
- 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
Prerequisites Data | Description |
---|---|
LAS Instance Swagger URL | Required to access the LAS API. Swagger URL for |
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:
- Create a CSV file, The file format is described in Import File Format (CSV) .
- Log in to https://prod1-essentials.pttpro.zebra.com .
- Navigate to Imports AP page.
- Select and upload the CSV file.
- 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://
Parameters
The following parameters are used in the API Swagger Specification:
Table 2 API Swagger Specification Parameters
Parameters | Description |
---|---|
siteId | Name of the site. All the Access Points are defined for each site. |
bssid | Physical address of the access point. |
name | System defined name if any. |
ap_created_name | Location Friendly name for the access point. PTT Pro client |
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
CSV File Fields | Description |
---|---|
SiteName | Name of the site or store. All the Access Points are defined for |
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
SiteName | BSSID | AssetName | LocationFriendlyName |
---|---|---|---|
1202 | 00:00:00:00:00:01 | AP_001 | Grocery |
1202 | 00:00:00:00:00:01 | AP_001 | Bakery |
2032 | 00:00:00:CF:08:B2 | AP-Shoes | Shoes |
2032 | 00:00:00:CF:08:F6 | AP-Auto | Auto |
2032 | 00:00:00:CF:09:33 | AP-Pharmacy | Pharmacy |
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)
Read User Manual Online (PDF format) >>