Configuring Product visibility at a Catalog or Space level

How to set a limit on the visibility for all Products that are published to a Catalog or Space.

Before you begin

To configure Product visibility at the Catalog or Space level, you must be assigned to a role that has the Settings > Manage permission for that Catalog or Space. For more information on assigning Catalog permissions to a role, see Creating and configuring Catalogs.

Note: All references in this topic to a Catalog can also be applied to a Space in a Catalog, unless specified otherwise. For more information about Spaces, see Using syndication in API Connect.

About this task

The availability of a Product to users is determined by both the visibility setting (that covers which users can view the Product), and the subscribability setting (that covers which users can subscribe to the Product). When you create a draft Product, you typically define the visibility and subscribability in the Product document; see Specifying the visibility of your Product, and Creating a draft Product for details.

You can define a Catalog or Space setting to control the visibility of all of the Products that are published to that Catalog or Space, as described in the following instructions. When this Catalog or Space setting is enabled, it can be used for the following two purposes:

The setting can ensure that any Product published to that Catalog or Space, cannot have a visibility setting that exceeds the visibility limit set at the Catalog or Space level.
The setting can also be used as the default visibility setting for all Products that are published to that Catalog or Space.

When you're publishing a Product, the visibility setting can come from the following four places:

Product override; set during the API Manager UI sequence to publish a Product. If this setting is used, it supersedes any visibility setting in the draft Product.
Product document; set in the draft Product.
Catalog or Space setting. If Product visibility is enabled in the Catalog or Space, and the visibility is not set by a Product override or in the Product document, then the Catalog or Space visibility setting is used as the default setting. This setting can also be used as a limiter, to ensure that any Product that is published cannot exceed the Catalog or Space visibility setting.

Default setting. If there are no other visibility settings, then the following default visibility and subscribability settings are used:

visibility: {
    view: {
        enabled: true,
        type: 'public',
        orgs: []
    },
    subscribe: {
        enabled: true,
        type: 'authenticated',
        orgs: []
    }
}

Table 1 shows which Product level visibility settings are allowed when different Catalog level visibility settings are enabled.

Table 1. Relationship between the Catalog level visibility settings, and the Product level visibility settings.
Catalog level visibility setting	Product level visibility setting
Public	Public, Authenticated, or Custom.
Authenticated	Authenticated, or Custom.
Custom	Custom. Note that the Product level visibility organization and group URLs are limited by the Catalog level organization and group URLs.

Table 2 shows how the Product subscribe setting is limited by the Product visibility level. Only visible Products are available for subscriptions. For example, if you want the subscription audience to be authenticated, the visibility audience cannot be custom.

Table 2. Relationship between the Product visibility settings, and the Product subscribe settings.
Product visibility level	Product subscribe setting
Public	Authenticated, or Custom.
Authenticated	Authenticated, or Custom.
Custom	Custom. Note that the Product subscribe organization and group URLs are limited by the Product visibility organization and group URLs.

Note:

Changes to the Catalog visibility setting affects only future Product publishes. There is no change to Products that are already published.
Any updates to the visibility of a Product are always verified against the Catalog visibility setting, as the Catalog visibility setting sets the maximum visibility level that is allowed. Therefore, if Product visibility is enabled in a Catalog, and the visibility setting of a Product is less restrictive than is set in the Catalog, then the Product publish to that Catalog will fail. For example, if the Catalog visibility setting is authenticated, then any Products that are published to that Catalog cannot have a visibility setting of public.
You can also modify the Catalog visibility settings by using the API Connect REST APIs; see the API Connect REST API documentation.

Procedure

To modify the Catalog or Space visibility settings by using the developer toolkit CLI, complete the following steps.

Log in to your API Connect Management server as a member of a provider organization, by using the following command:
```
apic login --server mgmt_endpoint_url --username user_id --password password --realm provider/identity_provider
```
Where:
- mgmt_endpoint_url is the platform API endpoint URL.
- user_id is the user ID that you want to log in with. The user ID must be a member of a provider organization. This is an ID that you could also use to log in to the API Manager user interface.
- password is the password that is associated with the supplied user ID.
- identity_provider is the identity provider that is used to authenticate the supplied user ID.
For example:
```
apic login --server platform-api.myserver.com --username myuser --password mypassword --realm provider/myldap
```
You can determine which identity provider to use in the --realm parameter by entering the following command to see a list of all available identity providers (you do not need to be logged in to use this command):
```
apic identity-providers:list --scope provider --server mgmt_endpoint_url --fields title,realm
```
For example,
```
apic identity-providers:list --scope provider --server myserver.com --fields title,realm 
total_results: 2
results:
  - title: API Manager Local User Registry
    realm: provider/default-idp-2
  - title: Corporate LDAP user registry
    realm: provider/corporate-ldap
```
The title value should enable you to determine which identity provider to use; you can then copy the corresponding --realm parameter directly from the displayed realm value. For any identity providers that were created by your administrator after API Connect was installed, the names will have been determined at creation time. The default API Manager Local User Registry for login as a member of a provider organization is default-idp-2.
For full details on how to log in to your management server from the CLI, see Logging in to the management server.
Define your visibility settings by creating a YAML file with the following structure:
```
allowed_product_visibility: {
    view: {
        enabled: true_or_false,
        type: 'visibility_type',
        org_urls: [],
        group_urls: []
    },
    subscribe: {
        enabled: false,
        type: 'authenticated'
    }
}
```
Where, in the view section of the allowed_product_visibility property:
- enabled - can be set to true or false. The default setting is false.
  If set to true then any Product that is published to that Catalog or Space can have only a visibility that is the same or more restrictive than is configured in the type setting. If no visibility is set in the Product document, then the Catalog or Space setting is used as the default for the publish. If you want to always use the Catalog or Space setting as the default, then you must ensure that a Product visibility is not set.
  Note: If you are creating draft Products, and no visibility is set, then the value from the allowed_product_visibility field in the Sandbox Catalog is used as the default.
  If set to false, the feature is disabled, and the Product visibility settings that are defined in the Product document are used.
- type - if enabled is set to true, then this property specifies the maximum visibility of the Products that are published to this Catalog or Space. Valid settings are:
  - public - Products are visible to all users.
  - authenticated - Products are visible only to users who have successfully authenticated.
  - custom - Products are visible only to the consumer organizations and groups that are specified in org_urls and group_urls.
- org_urls - if type is set to custom, then this property specifies the URLs of the consumer organizations that you want the Products to be visible to. Otherwise, leave empty.
- group_urls - if type is set to custom, then this property specifies the URLs of the consumer organization groups that you want the Products to be visible to. Otherwise, leave empty.
The subscribe section cannot be edited at the Catalog or Space level. Subscribability is defined in the Product document subscribe section, and must be at least as restrictive as authenticated. For more information, see Specifying the visibility of your Product.
Modify your Catalog settings by using the following command:
```
apic catalog-settings:update --server mgmt_endpoint_url --catalog catalog_name --org organization_name filename
```
Where filename is the name of the YAML file that you created in step 2.

Note: If Spaces are enabled for the Catalog, then the visibility settings must be set at the Space level by using the --space option.

Confirm your updated Catalog settings by using the following command:

apic catalog-settings:get --server mgmt_endpoint_url --catalog catalog_name --org organization_name --output -