7. Managing On-Premise Subscription Management Applications

A subscription management application organization is a special type of entity in Red Hat Network — it is an on-premise entity that manages local systems. Red Hat Network registers the subscription management application organization and attaches large blocs of subscriptions to it. The application organization itself then manages inventory, subscriptions, and systems locally.
Customer Portal Subscription Management transfers subscriptions from the company's global Red Hat account to the local application. The subscription management application organization entry is the method Customer Portal Subscription Management uses to transfer those subscriptions.
A subscription management application organization entry in Customer Portal Subscription Management has direct parity with an organization entry in the on-premise application. The organization structure can be flat, with a single local organization. Alternatively, it can be multi-tenant, with multiple organizations managed by the same application but independent from each other. Multi-tenancy within the on-premise application allows multiple, independent groups to be attached and to manage their own subscriptions and systems through local services. (The organization structure in the on-premise application is transparent to Customer Portal Subscription Management. Customer Portal Subscription Management works with each subscription management application organization entry separately.)
The subscriptions attached to the application organization are the entirety of the subscriptions and products available to the systems within that organization. The subscriptions, products, and quantities are listed in the subscription management application organization's manifest.
Local organizations and environments can be managed through a variety of different subscription management applications, such as Subscription Asset Manager and CloudForms System Engine..

7.1. Registering Application Organizations

  1. Open the Subscriptions tab in the Customer Portal, and select the Overview item under the Subscription Management menu area.
  2. In the Usage area on the right, click the Subscription Management link.
  3. In the Subscription Management Applications column, click the Register link.
  4. Select the application type and fill in the name of the new subscription management application organization.

    Note

    This name should correspond to the organization name in the on-premise application.
  5. Click the Register button.
After the subscription management application organization is created, attach subscriptions to it, and download and install the manifest so that the organization can begin attaching subscriptions to its client systems.

7.2. The Subscription Management Application List and Details

The bottom of the Subscription Management page lists the applications, by type and number of registered organizations. Clicking the number in the count column opens up the list of organizations configured for that application type.
Subscription Management Applications in the Overview

Figure 24. Subscription Management Applications in the Overview

The Subscription Management Applications inventory has tabs for each available and configured application type, and each organization for that type is listed.
Viewing the Subscription Management Application Inventory

Figure 25. Viewing the Subscription Management Application Inventory

The columns have three important pieces of information:
  • The organization name, which links to the entry details page
  • The total number of subscriptions (across products and contracts) attached to that organization
  • The UUID for the organization, analogous to the UUID for a system
The organization details page is for managing the organization. Like the system details, has tabs for managing subscriptions for that organization and a tab for the identity certificate. It also has a button to download the manifest, which is the file imported into the on-premise application which informs the application what subscriptions it has.
Organization Details

Figure 26. Organization Details

7.3. Attaching Subscriptions to Organizations

7.3.1. About Manifests

As the introduction to Section 7, “Managing On-Premise Subscription Management Applications” covers briefly, there is a direct relationship between the subscription management application organization in Red Hat Network and the organization definition in an on-premise application like Subscription Asset Manager. This relationship is the method that Red Hat Network uses to transfer subscriptions from Red Hat to the on-premise application to administer locally.
This transferred block of subscriptions is listed in the subscription management application organization manifest. This manifest is a ZIP archive which is downloaded directly from Red Hat Network from the subscription management application organization entry and then is uploaded to the on-premise application.

Important

Any changes to the subscriptions for the organization are made to the subscription attached to the subscription management application organization entry in Red Hat Network. The manifest is then regenerated, downloaded, and re-uploaded to the application.
The manifest itself is a collection of directories and JSON files which contain the subscriptions, entitlement certificates, products, and list of rules for the subscription management application organization. 
manifest.zip
      |
      |- consumer_export.zip
                   |
		   |- export/
		         |
			 |- consumer_types/
			 |
			 |- entitlements/
			 |
			 |- entitlement_certificates/
			 |
			 |- products/
			 |
			 |- rules/
			 |
			 |- consumer.json
			 |
			 |- meta.json
consumer.json and meta.json

These JSON files contain a little information about the application organization entry (the UUID) and the manifest itself (version and creation date).

consumer_types/

consumer_types/ contains a list of JSON files, one for each supported application type. The JSON files indicate which type the subscriptions are attached to. For example, for Subscription Asset Manager, the sam.json has a manifest value of true. 

{"id":"5","label":"sam","manifest":true}
entitlements/

entitlements/ contains a JSON file for each subscription attached to the application organization. Each filed is named UUID.json.

The file contains the complete subscription information, including the contract number, pool ID, contract start/end dates, keys and certificates for the subscription, the product ID for each included product, quantities, and any other information associated with the subscriptions.
For example, this is the information for a single Red Hat Enterprise Linux product in a subscription JSON: 
...
{"id":"8a878dcd3520d43501353f6f98f911e9","productName":"Red Hat Enterprise Linux Server","productId":"69","updated":"2012-02-02T18:59:32.000+0000","created":"2012-02-02T18:59:32.000+0000"}],"endDate":"2012-10-13T03:59:59.000+0000","quantity":50,"productName":"Red Hat Enterprise Linux Server, Premium (4 sockets) (Up to 4 guests)","contractNumber":"2625891","accountNumber":"1506376","productId":"RH0153936","subscriptionId":"2267347","consumed":31,"exported":30,"sourceEntitlement":null,"activeSubscription":true,"restrictedToUsername":null,"productAttributes":[{"productId":"RH0153936","name":"support_type","value":"L1-L3","id":"8a878dcd3520d43501353f6f98f811de","updated":"2012-02-02T18:59:32.000+0000","created":"2012-02-02T18:59:32.000+0000"}
...
entitlement_certificates/

entitlement_certificates/ contain PEM files with the base 64-encoded blob of the entitlement certificate for each subscription.

products/

products/ contains JSON file for every product included with the subscriptions. This contains detailed information about supported versions and content sets, dependencies, repositories, and other product-specific (but not necessarily subscription-specific) information.

For example, for part of the JSON file for one version with a basic Red Hat Enterprise Linux product: 
...
{"name":"Red Hat Enterprise Linux Server","id":"69","attributes":[{"name":"type","value":"SVC"},{"name":"arch","value":"i386,ia64,x86_64"},{"name":"name","value":"Red Hat Enterprise Linux Server"}],"multiplier":1,"href":"/products/69","productContent":[{"content":{"name":"Red Hat Enterprise Linux 5 Server Beta (Source ISOs)","id":"861","type":"file","vendor":"Red Hat","modifiedProductIds":[],"contentUrl":"/content/beta/rhel/server/5/$releasever/$basearch/source/iso","label":"rhel-5-server-beta-source-isos","gpgUrl":"http://","metadataExpire":86400,"requiredTags":"rhel-5-server"},"enabled":false}
...
rules/

rules/ contains a single JavaScript file which sets the functions that the application uses to interact with the backend Red Hat subscription management service.

7.3.2. Attaching Subscriptions to Organizations

Attaching subscriptions to an organization sets the number of that type of subscription which the organization can attach to the systems it manages. (This is in contrast to a system, which attaches the subscription to itself for its own, local installed products.)
The Attached Subscriptions tab shows what subscriptions are currently attached to the organization. Clicking the Attach a subscription link shows all of the subscriptions that are available to the application organization, based on the overall account subscriptions.
To attach subscriptions to an organization:
  1. Open the Subscriptions tab in the Customer Portal, and select the Overview item under the Subscription Management menu area.
  2. In the Usage area on the right, click the Subscription Management link.
  3. In the Subscription Management Applications column, click the organization type.
  4. Click the organization name in the application inventory.
  5. Open the Attached Subscriptions tab.
  6. Click the Attach a subscription link to open the subscription selection window.
  7. Select the checkboxes by the subscriptions to attach and set the total quantity for the application organization in the Quantity column.
    The list of available subscriptions provides three important pieces of information:
    • The contract number for the purchase of the subscription, which is important for record keeping and tracking.
    • The quantity still available for that subscription. Subscriptions are purchased in quantities; this number tells how many are still left of the total quantity purchased.
    • The start and end dates of the subscription. This keeps you from attaching a subscription that may only be valid a few days before it expires or which are not yet active.
      There should probably be a mix of subscriptions, with different end dates, attached to the organization to make it easier to renew subscriptions without having to update the manifest.

    Note

    The quantity defaults to be the total number of subscriptions available for that contract. Be aware of how many subscriptions are being attached to a single application organization so that the subscriptions can be attached appropriately among other units and subscription management applications.
  8. Click the Attach selected button in the lower left corner.

7.3.3. Downloading the Manifest

Once subscriptions are attached to a application organization, the complete list of subscriptions and products, including product certificates and entitlement certificates, are bundled together in a single manifest. The manifest is essentially a master list of everything that the application organization requires to handle local subscription management services.
The manifest can be downloaded from the application organization's details page simply by clicking the Download manifest button. This saves the manifest.zip archive to the local filesystem, so it can then be uploaded to Subscription Asset Manager or CloudForms System Engine.
Downloading the Application Organization Manifest

Figure 27. Downloading the Application Organization Manifest

7.3.4. Updating the Manifest and Changing Subscriptions

If the organization needs to change its subscriptions — by altering quantities, adding products, or renewing subscriptions — this is done by editing the subscriptions attached to the organizatin in Customer Portal Subscription Management.

Important

Do no attempt to update the on-premise organization entry by creating a new organization in Customer Portal Subscription Management. Change the subscriptions attached to the existing organization in Customer Portal Subscription Management, and then have the on-premise organization entry use the updated manifest.
  1. Open the Subscriptions tab in the Customer Portal, and select the Overview item under the Subscription Management menu area.
  2. In the Usage area on the right, click the Subscription Management link.
  3. In the Subscription Management Applications column, click the organization type.
  4. Click the organization name in the application inventory.
  5. Open the Attached Subscriptions tab.
  6. Delete any previous subscriptions which need to be updated. Select the checkbox by the subscription, and click the Remove Selected button.
    A subscription quantity attached to a subscription management application organization cannot be changed directly. If additional numbers need to be added or removed from an attached subscription, delete the original assignment and then attach the subscription with the new quantity.
    For example, if your subscription bloc has a quantity of 30 and it should increase to 35, you can delete the old bloc and add a new one with a quantity of 35; that leaves you with one subscription and a quantity of 35. Alternatively, you can simply add a new bloc with a quantity of 5; that results in two separate subscription entries, one with a quantity of 30 and one with a quantity of 5.
  7. Add any new subscriptions, as in Section 7.3.2, “Attaching Subscriptions to Organizations”.
  8. Click the Download manifest button and save the updated manifest, as in Section 7.3.3, “Downloading the Manifest”.
  9. Upload the updated manifest to the on-premise application.