How to connect Cisco CMX to Mapwize

Cisco CMX is a location engine using the data acquired by the Cisco WiFi Access Points to locate WiFi-enabled devices. By connecting Cisco CMX to Mapwize, you can:

• Show a user where he is located on the map (if he is connected to the WiFi network).
• Visualize the location of assets.
• See heatmaps and get location analytics about how your building is used.

There are 2 steps to connect your CMX to Mapwize: retrieve the CMX map configuration and configure notifications.

Retrieving the CMX map configuration

CMX contains technical maps of the buildings that are used to position APs. Locations computed by CMX are related to those maps. In order for Mapwize to understand the locations it is receiving, the CMX map configuration needs to be imported in Mapwize.

Note that Mapwize does not need to know the location of the access point, just the way the underlying maps are configured.

There are 2 options to share the CMX map configuration with Mapwize:

Give Mapwize access to the CMX API

If your company policy and your firewall easily allows, you can give Mapwize access to the CMX API. In this way, Mapwize can get all the data it needs without bothering you further. Also, this allows to update the map configuration on a regular basis.

In this case, please send the URL of the CMX instance, as well as login and password information to your Mapwize representative.

Manually send the data

For most clients, the CMX instances are buried in secure data centers with the rest of the network appliances and access can only be granted through complex procedures. In that case, a one-time extract is the most efficient way to go.

The map configuration can be retrieved using the CMX API /api/config/v1/maps. Please send the complete JSON response.

The above JSON makes reference to the images used in CMX. All those images (with the exact same size in pixels as used in CMX) need to be sent along with the JSON file. If you do not have the files anymore, you can retrieve them from the CMX API /api/config/v1/maps/image/:campusName/:buildingName/:floorName or /api/config/v1/maps/imagesource/:imageName.

Updates of the configuration need to be sent to Mapwize if the maps (images) are changed within CMX. Mapwize does not need to know about the access points and therefore a change on the configuration of the access points does not need to be sent to Mapwize.

Configuring notifications

Locations computed by CMX will be sent to Mapwize using HTTP notifications. Those are simple HTTP requests sent from CMX to Mapwize. For your firewall, this is only outbound traffic.

Your Mapwize representative will provide you with the URL to use for the notifications. It should look like yourdomain.mapwize.io/cmx. Please ensure that outbound traffic is authorized to that URL on your infrastructure. Please note that Mapwize is deployed in the cloud and that fixed IP addresses are not available.

To configure the notifications, go to your CMX dashboard and then to Manage and Notifications. Create a new notification using the following parameters:

• Name: Mapwize or any name to help you identify it.
• Type: Location Update is the most common. If you are concerned with the volume of data sent, you can also select Movement with a distance of 10 feet, or any value you want.
• Device Type: All or you can limit to Client.
• Status: All if you want Mapwize to give you analytics. Associated is sufficient for wayfinding only.
• Hierarchy: All Locations or only the locations you want to use Mapwize at.
• MacAddress: leave empty.
• Receiver: HTTP or HTTPS, yourdomain.mapwize.io, 80 (for HTTP) or 443 (for HTTPS), /cmx.
• HTTP Headers: none
• Mac Hashing: Off if you want to be able to do asset tracking. On if only wayfinding or analytics are activated. The hash key can be chosen freely.
• Message Format: JSON

Many of our clients are experiencing issues in sending notifications using HTTPS, and the reasons for that are not clear. It might be wize to use HTTP at first to validate that everything is working and then transition to HTTPS.