Creating a Product App Store or BSS integration

This tutorial will show you how to create a Product App Store or setup an BSS integration to toggle Products for Subscribers on the Mobility Services core network.

Prerequisites

This tutorial assumes you are able to create an OAuth 2.0 client and get an access token.

See Get client access token for detailed instructions.

Introduction

This tutorial shows you how to create your own App Store which will allow your Subscribers to enable Products, or to integrate Product bundling into your BSS.

Since all API consumers on the Mobility Services platform are referred to as "Products", this becomes a little meta. This guide will show you how to create a Product, which, when used by your Subscribers, will allow them to enable Products. Let's get started.

Join the metaverse

As mentioned, we need to create a Product with the power to enable Products.

Head on over to developer.mobility.cisco.com, select your organization, and create a new Product.

If you are creating a white-label App Store, you would typically call your Product something like "MyCompany General App Store" and select full market availability. If you are working on behalf of an operator to enable Mobility Services Products for just your Operator's Subscribers, you would typically call your Product something like "OperatorName App Store", "OperatorName BSS", "OperatorName MyPages", etc, and only make it available to your operator.

Once you have created the Product, you need to toggle the required scopes in the "Technical integration" tab.

The scopes used in this guide are:

• subscription.id:read
• subscription.consent:read
• subscription.consent:write
• products.list_for_tenant:read

When you make the client, you will need to enable these scopes. For obtaining access keys, you may follow the steps in:

• Create an OAuth client,
• Get an access token.

Enable distribution and distributable Products

This section is intended for integrators who are working for an operator.

If you are an external third party creating Products for operators, you can skip this section.

This is a two-step process:

• The app store product must be granted access to enable selected products on behalf of subscribers.
• The products that are available in the app store must be enabled for individual provisioning.

Products not enabled for individual provisioning will not be visible for the app store and can not be enabled by it.

Enabling the App Store Product:

This grants your App Store, My Pages, or BSS integration the access to enable products on behalf of your subscribers.

1. Head over to your Mobility Services Console (https://console.wgtwo.com)
2. Find your Product in the Marketplace section.
3. Click the "More" button to open the Product page.
4. You'll find an "Enable" button in the top right corner. Click this button.
5. You will be prompted to enable the Product for either "All subscribers" or "Individual provisioning." Select "All subscribers" to make sure that your App Store, My Pages, or BSS integration works for your entire Subscriber base.
6. Now the Enabler Product is able to enable Products on behalf of your Subscribers.

Enabling distributable Products (Products available in App Store):

This makes the Product visible to the App Store, My Pages, or BSS integration.

1. Head over to your Mobility Services Console (https://console.wgtwo.com)
2. Find the product to be available to the store in the Marketplace section.
3. Click the "More" button to open the Product page of the Product that you want to make available.
4. You'll find an "Enable" button in the top right corner. Click this button
5. You will be prompted to enable the Product for either "All subscribers" or "Individual provisioning."
6. Select "Individual provisioning". This will make the Product you enabled appear in the Products API, as described in Querying the Products API.
7. Now the Enabler product is able to find this Product and can present it to your Subscribers.

How to use the APIs

For documentation of the Product and Consent API, please see:

• List Products For A Tenant
• Create Consent For Subscription
• Get Consents For A Subscription
• Revoke Consent For Subscription.

Querying the Products API

The products.list_for_tenant:read scope that you enabled will allow the caller to list all the Products that the operator has approved for use on their platform. If you are calling this API and getting an empty result, it means that the operator has not approved any Products.

Using the Consent API

The subscription.consent:read and subscription.consent:write scopes that you enabled will allow you to list all the consents for a subscription (read), as well as add or remove a consent (write).

This API needs to be used in conjunction with the Products API. The Products API will list all the Products that the operator has approved for use on their platform. The Consent API will allow you to toggle the Products for a Subscriber.

Walkthrough

The same steps as below is implemented in an example project of a Product App Store that

1. Lists all available products for a tenant
2. Allows the Subscriber to toggle the products using the Consent API

See: github.com/working-group-two/storefront-example

List Products for Tenant

Required Scope: products.list_for_tenant:read

This API will list all the Products that the tenant has enabled in Console for individual provisioning.

grpcurl \
  -d '{ "tenant": "<<TENANT_NAME>>" }' \
  sandbox.api.shamrock.wgtwo.com:443 \
  wgtwo.products.v0.ProductService/ListProductsForTenant

Get ID for Subscription

Required Scope: subscription.id:read

All consents are stored using a unique identifier named wg2rn. This identifier is guaranteed to uniquely identify a subscription, and will never be reused.

It is recommended to use this identifier when handling consents, although phone number is also supported.

This API can be used to lookup the wg2rn for a given phone number.

grpcurl \
  -d '{ "phone_number": { "e164": "<<PHONE_NUMBER>>" } }' \
  sandbox.api.shamrock.wgtwo.com:443 \
  wgtwo.subscription.v0.SubscriptionIdService/GetSubscriptionId

Create Consents for Subscription

Required Scope: subscription.consent:write

This API will create a consent for a given subscription. The product must be enabled for provisioning for the tenant.

It is possible to include metadata in the consent, which can be used to store required information about the consent.

grpcurl \
  -d '
  {
    "id": { "value": "<<WG2RN>>" },
    "product_id": "484",
    "metadata": {
      "source": "Cisco Demo App Store"
    }
  }
  ' \
  sandbox.api.shamrock.wgtwo.com:443 \
  wgtwo.consents.v0.ConsentService/CreateConsentForSubscription

List Consents for Subscription

Required Scope: subscription.consent:read

This API will show the active consents for the subscription.

This can be used to show the user which products they have enabled in your webshop, app store, or similar.

grpcurl \
  -d '{ "id": { "value": "<<WG2RN>>" } }' \
  sandbox.api.shamrock.wgtwo.com:443 \
  wgtwo.consents.v0.ConsentService/GetConsentsForSubscription

Revoke Consents for Subscription

Required Scope: `subscription.consent:write

grpcurl \
  -d '
  {
    "id": { "value": "example:no:1337" },
    "product_id": "484"
  }
  ' \
  sandbox.api.shamrock.wgtwo.com:443 \
  wgtwo.consents.v0.ConsentService/RevokeConsentForSubscription

Conclusion

You have now

1. Created a product that lists other enabled products on the tenant
2. Enabled a product for a subscriber by granting a consent
3. Deactivated the product by revoking the consent