Create Multi-Tenant Cloud Partner Apps

Procedure

Step 1

Go to https://partners.dnaspaces.io/ to log in to the Cisco Spaces - Partner Dashboard.

Step 2

Click the Create New App tile under the Partner Apps section. For details, refer to the Create Partner Apps section.

The Choose App Type dialog box displays the Multi Tenant Cloud, Single Tenant Cloud, and On-Prem options.

Step 3

Select Multi Tenant Cloud and click Create.

A new page with the App Center, Uses Cases, App Tile, Behaviors, Events, and the Integration Details tabs appears.

Step 4

The App Center tab displays by default.

  1. Choose the desired region. To create, activate, publish and manage app for the Europe region, choose the Europe Region option. Otherwise, choose Rest of the World (Except Europe region) option.

  2. Enter a relevant APP Name.

  3. Enter a relevant APP Tagline for your App.

  4. Click the Choose File button to select and upload the APP Icon image.

  5. Enter a relevant APP Description.

  6. Choose the Primary Industry for the App.

  7. (Optional) Under the More Industries section, choose the business segments that the app applies to.

    The options available are listed below:

    • Retail

    • Hospitality

    • Health Care

    • Manufacturing

    • Education

    • Financial Services

    • Venues

    • Workspace

    • Real estate

    • Others

  8. (Optional) You can also add the following details:

    Note
    The information collected here will be displayed on the App details screen, when you view the App information on the Cisco Spaces - Partner App Center. Please ensure the developer details provided here are up-to-date.

    • Developer Info: Under Developer Info, click Browse to choose the Company Logo and upload the file.

    • Company Name: Enter the Company Name of the App developer.

    • Company Website: Enter the Company Website of the App developer

    • Support Contact: Enter the Support Phone number and Support Email address.

    • Sales Contact: Enter the Sales Phone number and Sales Email address.

    • Phone

    • App Media: You can also add the following info for your app:

      • Screenshots: You can upload Screenshots of your application from your local drive either through Drag & drop or by using Click here to upload.

      • Youtube Video URL: Enter the Youtube Video URL of your app and click Save.

Step 5

Under the Use Cases tab, click the Add a Use Case button to add a use case.

  1. Enter a relevant Use Case Headline.

  2. Click the Choose File button to select and upload the Use Case Icon.

  3. Enter relevant Use Case Short Description.

  4. Enter the optional Use Case Long Description, if any.

  5. Enter the optional Compatibility Notes, if any.

  6. Choose the relevant Use Case Category. The available options are: Analytics, Captive Portal, Marketing & Engagement, Asset Management, Wayfinding, Mapping, and Others. Choose Others if the use case does not belong to any of the available categories.

  7. Provide other optional use case options, for the Who is this use case applicable to?, What value does this drive for the customer? questions.

  8. Optionally, select the appropriate Infrastructure Compatibility options.

  9. Optionally, select the upload relevant Screenshots, and Youtube Video URL, if any.

  10. Click Save to save changes.

  11. Click Add Another Use Case button to add additional use cases.

Step 6

Click on the App Tile tab. The App Tile Configuration section displays.

  1. Enter a relevant App Tile label.

  2. Enter the desired App Tile Tagline description.

  3. Enter the App Dashboard URL. Ensure the URL uses the https:// protocol.

  4. Check the OAuth check box.

  5. Enter your Client ID.

  6. Click Regenerate Secret to generate a Client Secret key. This value is automatically populated the Client Secret field.

  7. The Redirect URI field is automatically populated with the https://partners.dnaspaces.io/partner/OAuthValidation value. Enter the OAuth Login URL and ensure the URL uses the https:// protocol.

    Under the OAuth Configuration section, enter the OAuth Login URL, OAuth Token URL, and the App Info URL. These details need to be confirmed and provided by the partner.

    Note

    If your app does not have an authentication site configured for App activation, then you can choose to use the Cisco Test Authentication site for testing App authentication.

    For the US domain Cisco Spaces - Partner Dashboard, enter the following details:

    • Client ID: dnaspaces

    • Client Secret Key: c567560ad2e84795a8f16c32586e1f69b78cab02

    • OAuth Login URL: https://trigue.dnaspaces.io/auth/login.

    • OAuth Token URL: https://trigue.dnaspaces.io/auth/token

    • App Info URL: https://trigue.dnaspaces.io/appInfo

    • Dashboard URL: https://trigue.dnaspaces.io/auth/appLogin

    For the EU domain Cisco Spaces - Partner Dashboard, enter the following details:

    • Client ID: dnaspaces

    • Client Secret Key: c567560ad2e84795a8f16c32586e1f69b78cab02

    • OAuth Login URL: https://trigue.dnaspaces.eu/auth/login

    • OAuth Token URL: https://trigue.dnaspaces.eu/auth/token

    • App Info URL: https://trigue.dnaspaces.eu/appInfo

    • Dashboard URL: https://trigue.dnaspaces.eu/auth/appLogin

Step 7

Click on the Behaviors tab. Enter details in the App Behaviors section, if you wish to support automated sign-up for new customers.

  1. The NEW CUSTOMER ONBOARDING section allows you to enter the redirect URL for new customers' sign-up. Enter the redirect URL in the Sign Up URL field.

  2. Enter correct address in the Contact Company Info field.

  3. To enable customers to view details when they remove/delete the App, enter details in the Delete App Confirmation field. Ensure the URL uses the https:// protocol.

  4. Under the APP MONITORING section, enter the correct link addresses in the App Health Check URL, API Health Status URL, and the App Status Page URL fields. Make sure to use the https:// protocol when entering the App Monitoring URLs. The App monitoring configurations help Cisco Spaces to monitor and report the app health and the partner app uptime status. For more information, see Monitor Partner App Health.

Step 8

Click on the Events tab. The available app Events Types and Event Settings are listed.

The events listed on the Event Types screen are triggered in sequence, from the time of App activation occurs, till the time a device exists and various other event types data are collected. Each event type is triggered on the occurrence a particular activity.

  • For example: The first time a Customer activates the partner app, the App Activation event is triggered in the background with information update such as the Customer has activated your App.

  • Next, the Location Information Change event triggers, which provides location changes information of all activations at the various locations as configured in the location hierarchy.

  • If your Wi-Fi location infrastructure is setup, then you will receive a Device Location Update when a visitor connects to the SSID.

  • However, for the very first time when the device connects to the SSID, you will also receive the Device Entry and the Device Presence event information at the time of entry. If the visitor device is associated with a User ID, you will receive a User Presence event type. Based on a user's device state, you will receive other event data information. For example: If a user device is passive or when there is no device update for a specified interval of 10 minutes, then both User Presence and Device Presence events information will indicate as Inactive. For example: If a visitor is entering a location with multiple devices, such as a mobile device and a laptop at the same time, and there are no location updates received for both devices for 10 minutes, then the User Presence and Device Presence events indicate as Inactive.

  • As soon as one of the devices is active at the location, the User Presence and Device Presence event status automatically changes to Active. If one of the devices or both devices are inactive for a longer period or a specified time-interval, then the Device Exit event is triggered.

  • If a business location has TelePresence devices configured, then such TelePresence devices will post information on the People Occupancy and People Count data in the room by using the built-in sensors. Though the People Count data is approximate, the People Occupancy data is accurate. The system automatically posts the updated data, whenever it identifies a change.

    Note
    It is highly recommended that you select only those Event Types that are applicable and required for your business use cases, thereby limiting the number of events and avoiding unnecessary system overheads. Specifically, the TelePresence event must be subscribed only if you have your TelePresence device configured to interact with Cisco Spaces in order to limit the number of events that you receive and to avoid unnecessary overheads on the system.

  1. The available Events Types displayed are:

    • Device Entry: This event is sent when a device enters a location.

    • Device Exit: This event is sent when a device has exited a location.

    • Profile Update: This event is sent when a device profile is updated. For example, this event is sent when an end-user provides information in a captive portal.

    • Location Information Change: This event is sent when a location is updated or changed. For example, a location is moved under a group, location is renamed or there is a change to the location metadata.

    • TelePresence: This event is sent when the TelePresence system encounters a people count update.

    • Device Location Update: This event is sent when a device location is updated. If you check the Receive Geo Coordinates option, you will receive the device latitude and longitude coordinates, along with the X and Y coordinates data for the device.

    • App Activation : This event is sent when a customer activates the application.

    • Account Admin Change: This event is sent when an account admin gets added/removed/updated for the partner account.

    • Device Presence: Used to track life cycle of a device at a location. Events are generated at device entry, when a device is inactive for 10 minutes, when a device is active after being inactive or when we determine that the device has exited. These events also provide current count of devices at location (active and inactive).

    • User Presence: Based on available authentication in use and information available from the network, Cisco Spaces can map group multiple devices owned by a user. Events are generated at user entry, when a user is inactive for 10 minutes, when a user is active after being inactive or when we determine that the user has exited. These events also provide current count of user at location (active and inactive).

    • IoT Telemetry: This event is sent when there are telemetry updates from BLE, RFID, and Zigbee IoT devices.

    • IoT User Action: This event is sent when user actions are performed on IoT devices.

    • Device Count: This event is sent when there is a change in the (count) number of devices at the location.

    • Device RSSI Update: This event is sent when a device RSSI is updated.

    • BLE RSSI Update: This event is sent when there is a ping from the BLE device at the location.

    • Camera Count: This event is sent when there is a change in the aggregated count of people (computed via the Meraki Video Camera) at the location.

    • Raw Camera Count: This event is sent when there is a change in the individual camera count (computed via the Meraki Video Camera) at the location.

    • Network Telemetry: This event is sent at a periodical interval with health and performance telemetries of the location.

    • Location Anchor Update: This event is sent when a new location anchor is added to, updated in, or removed from IoT Services.

    Note

    • For more information, see the Event Types section.

    • During app activation, you can now see the groups defined under IoT services. However, these groups are displayed only if you have selected one of the following events:

      • IOT_TELEMETRY

      • IOT_USER_ACTION

      To manage the groups selected during app activation, in the Activation window, click the Groups tab. Here, you can add or edit the groups.

      Note

      • For this feature to work, you must enable IoT services for the specified Cisco Spaces account. You must enable IoT services through both the Cisco Spaces Dashboard and the Cisco Spaces - Partner Dashboard for EXTEND accounts in order to use this feature.

      • You can see the groups mentioned above during app activations for activations done through both the Cisco Spaces Dashboard and the Cisco Spaces - Partner Dashboard.

  2. Under the Event Settings section, check the desired location option.

    • Under Choose Locations, you can choose to receive the above Event types data for the various location levels specified in the Cisco Spaces - Location hierarchy. The Location hierarchy in Cisco Spaces can be setup to correspond to your business needs and your organizational hierarchy, instead of corresponding only to the physical or geographical business hierarchy.

      In Cisco Spaces, you can set up your business organizational hierarchy by defining the main or the Root Level, which can include one or more Group and Network level. Each Network level may include one or more floors, while each Floor level can include one or more Zones. Access points can be associated with the different zones.

      • Check All Location Types if you wish to make the app available and receive the event data from all the business locations.

      • Check the Location Types option if you wish to make the app available and receive the event data only from specific location types that you choose. Root Level, Groups, Network, Floor, and Zone are the available location types.

        Note
        If you are operating only at specific levels in the location hierarchy, such as only at the Network, Floor or Zone levels, it is highly recommended that you choose to receive Event data only for those specific levels, in order to avoid unnecessary system overheads. Only if you need to process information from all levels in the Cisco Spaces - Location hierarchy, then choose the All Location Types option.

      • Select the desired location types.

      • Some of the event types listed above include the device MAC address in the Event payloads. For the MAC Address Sharing event setting, if you check the Yes option, you will receive the Client MAC addresses along with the associated events details. If you wish to receive MAC Address Sharing details, then you will be responsible for handling the GDPR compliance requirements. However, if you do not adhere to GDPR compliance standards requirements and your business requirement only needs the device ID, then you can use the device ID event type data provided by Cisco Spaces provides with all the device-related events.

      • Some of the event types listed above include the Social Identifier Sharing data in the Event payloads. For the Social Identifier Sharing event setting, if you check the Yes option, you will receive the Social identifier Sharing data along with the associated events details. If you wish to receive Social identifier Sharing details, then you will be responsible for handling the GDPR compliance requirements. However, if you do not adhere to GDPR compliance standards requirements and wish to avoid data privacy issues while handling or storing the Social Identifier Sharing data, then you can choose the No option, which is checked by default.

      • Likely, some Partners may not have their wireless network infrastructure fully set up and configured to receive the above Event types information to analyze the data that is received. To glance and get a quick preview of the typical sample data that is received from the above events, choose the Yes option associated with the Receive Simulation Events option. You will receive sample dummy data from Cisco.

        Note

        • Data that is provided as part of the Simulation Events is only dummy data. This sample data does not guarantee any interoperability or integrity across any other events or APIs.

        • Simulation data is available only for the US domain.

        Check No if you do not wish to receive dummy simulation events data from Cisco.

    The Permissions and the Location Permissions sections on the right-side displays information on the permission types that will be requested from customers during App activation. the Permissions are based on the event types that you selected. For example: If you wish to collect the MAC address of a device, then the app will request the MAC specific permissions from the Customer. These permissions will be based on the selected events, location, and the privacy configurations.

Step 9

Select the desired Integration Types details on the Integration Details tab.

Note
After creating a partner app and making it available in Cisco Spaces, when a customer activates the app, you can choose to receive the data from Cisco Spaces using push channels or pull channels. Listed below are the configurations required based on your selection of either the push channel or the pull channel.

Push Channels: The Cisco Spaces Firehose API push channels are easy to set up and run, if you are already on Amazon AWS, Google Cloud or Microsoft Azure. Just provide credentials and the end-point details and start receiving data immediately. Cisco Spaces starts transmitting the data continuously through the API channels immediately after the configurations are done. Refer to the Push Channels section for more details.

  1. Under the Push Channels section, check the desired options.

    • Check the AWS Kinesis check box to push events to the AWS Kinesis Data Stream.

      • Choose the required AWS Region.

      • Enter the exact stream name used while creating the Data Stream in AWS.

      • Enter the correct AWS Access Key.

      • Enter the correct AWS Secret Key.

    • Check the AWS Kinesis Firehose check box to push event details to the AWS Kinesis Data Firehose.

      • Choose the required AWS Region.

      • Enter the exact stream name used while creating the Delivery Stream in AWS.

      • Enter the correct AWS Access Key.

      • Enter the correct AWS Secret Key.

    • Check the Azure Events Hub check box to channel push events to an Azure Event Hub.

      • Enter the correct Connection String.

    • Check the Google Pub/Sub check box to push events to Google Pub/Sub.

      • Enter the correct Project ID.

      • Enter the correct Topic ID.

    Note
    The AWS Secret Key and Connection String fields are now masked while an app is created or being edited.

Pull Channels: Cisco Spaces starts transmitting the data once a request is initiated by the partner application. When initiating a request, the partner application can request to replay recent events. This option can be used to resume processing without loss of data. Your application needs an authenticated API key to pull the streaming data. Your application can use HTTP Pull channel to retrieve events over HTTP/2 or over HTTP 1.x protocol. Your application initiates a HTTP GET to Cisco Spaces Firehose API HTTP end-point. Events are continuously sent as they happen as a response to the GET request as long as the HTTP connection is active.

Pull channels allow resuming after a short period without any loss of data. This is particularly useful to system upgrades and short outages without loss of data. Refer to the Pull Channels section for more details.

  1. Under the Pull Channels section, check the desired options.

    • Check the HTTP check box to send pull channel events details over a streaming HTTP Connection.

    • Check the gRPC check box to send pull channel events over a streaming gRPC call.

    Note
    For more details, see the Pull Streaming section.

Step 10

Click Create to create the App.

The API Credentials for Pull Channels displays the Environment type and the API Key details that are automatically generated on creating an application. The same information also displays when you open the App in Edit mode.

Note

To ensure increased security for your activated cloud apps, it is recommended that you renew your app's API key at specific intervals, such as once in 90 days or as needed. To renew the app API key:

  • Open your Cloud App in Edit mode.

  • Click on the Integration Details tab.

  • Under the API Credentials for Pull Channels section, hover your mouse pointer on the desired Environment section to view the associated app API Key.

  • Review the recommended renewal date. Click Renew. A confirmation box displays. Click Renew if you wish to generate a new API key for the selected environment (if you have multiple environments).

    If an app is in Draft state, only the sandbox and pre-production keys can be renewed and copied. However, if the app is in Live state, only the production key can be renewed and copied.

  • A new API key is generated. Click Copy to copy the generated API key.

  • Click Save to save changes.

  • Navigate to your app and paste the new app API key that you generated and copied.

What to do next

  • View: To view the app and check its configuration and details

  • Edit: To edit the app configuration or details

  • More: To view additional options for the app depending on the app status

    • Preview: To check how the app appears in Cisco Spaces - Partner App Center

    • Test: To test the app

    • Submit app: To submit the app for review

    • Update app: To update a live app

    • App Activations: To view details related to app activation in the Cisco Spaces - Partner Dashboard such as Customer Name, Locations Activated, Last Activation Date, etc.

      This option is visible only if the app is in Live, Approved, or Coming soon status, not if the app is in Draft, Testing, or Submitted status cannot be activated.

    • Make a copy of app: To duplicate an app.

      If the copied app is for a different region compared to the original app, then the same name as the original app can be retained. However, if you need a copy of the app in the same region as the original app, you will need to rename the copied app, else you will receive the error message Partner app name already exists: <app name>.

    • Delete app: To delete an app from the Cisco Spaces - Partner App Center.

      For more information, go to Delete App.

    • Firehose Trace: To view or download Firehose data for an app from the Cisco Spaces - Partner Dashboard.

      For more information, go to Trace Firehose.