Create a Catalog With an External Subscription

An organization administrator in an organization that has permission to subscribe can create a catalog whose contents are downloaded from an external source. You cannot use catalogs created this way to hold catalog items that are created locally.

Organizations that are permitted to subscribe to external sources can create catalogs whose contents are downloaded from a catalog hosted on another instance of VMware Cloud Director, or any Web site that implements the VMware Content Subscription Protocol (VCSP) . See Synchronization.

If a catalog has an external subscription, you cannot enable it for external publication.

Prerequisites

This operation requires the rights included in the predefined Catalog Author role or an equivalent set of rights.
Verify that at least one VDC exists in your organization. You cannot create a catalog in an organization that has no VDCs.
Verify that your organization has permission to create catalogs with external subscriptions.
The OrgGeneralSettings in the AdminOrg element that represents your organization must have a CanSubscribe element with a value of true.
```
<CanSubscribe>true</CanSubscribe>
```
The external source must implement the VMware Content Subscription Protocol. See Synchronization.
You must know the URL of the external source, and the password if one is required.

Retrieve the XML representation of the organization to which you want to add the catalog, and examine the response to locate the Link element that contains the URL for adding catalogs to the organization. See Add a Catalog to an Organization.

Procedure

Create an AdminCatalog element that includes ExternalCatalogSubscriptionParams.
See the request portion of Create a Catalog With an External Subscription.
POST the AdminCatalog element to the organization's add URL for catalogs.
See the request portion of Create a Catalog With an External Subscription.

Results

The server creates an empty catalog and returns its representation in the response. See the response portion of Create a Catalog.

Example: Create a Catalog With an External Subscription

This request creates a catalog with a subscription to the VCSP URL https://vcloud2.example.com/vcsp/catalog/5. Because the LocalCopy element in ExternalCatalogSubscriptionParams has a value of false, files that comprise a vApp template or media image that a catalog item references are not downloaded until a user requests them. If you create a catalog where LocalCopy has a value of true, these files are downloaded the first time that the catalog subscription is synchronized, and on each subsequent synchronization where any of the catalog items has a newer version number. The default value of LocalCopy isfalse.

Request:

POST https://vcloud.example.com/api/admin/org/26/catalogs
Content-Type: application/vnd.vmware.admin.catalog+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<AdminCatalog
   xmlns="http://www.vmware.com/vcloud/v1.5"
   name="SubscribedExternally">
   <Description>Example Catalog With External Subscription</Description>
   <ExternalCatalogSubscriptionParams>
      <SubscribeToExternalFeeds>true</SubscribeToExternalFeeds>
      <Location>https://vcloud2.example.com/vcsp/catalog/5</Location>
      <Password>Pa55w0rd</Password>
      <LocalCopy>false</LocalCopy>
   </ExternalCatalogSubscriptionParams>
</AdminCatalog>

The response is similar to the one shown in Create a Catalog, but includes the ExternalCatalogSubscriptionParams element that you supplied in the request. The Password element in the request is never returned.

Response:

201 Created
Content-Type: application/vnd.vmware.admin.catalog+xml
...
<AdminCatalog
   xmlns:vcloud="http://www.vmware.com/vcloud/v1.5"
   name="SubscribedExternally"
   id="urn:vcloud:catalog:34"
   type="application/vnd.vmware.admin.catalog+xml"
   href="https://vcloud.example.com/api/admin/catalog/34">
   ...
   <Link
      rel="up"
      type="application/vnd.vmware.admin.organization+xml"
      href="https://vcloud.example.com/api/admin/org/26" />
   <Link ... >
   <Link
      rel="sync"
      href="https://vcloud.example.com/api/catalog/34/action/sync"/>
   <Link ... >
   ...
   <Tasks>
      <Task 
         status="running"
         ...
         operation="Creating Catalog SubscribedExternally (34)"
         ...
      <Task>
   <Tasks>
   <Description>Example Catalog With External Subscription</Description>
   <CatalogItems/>
   <IsPublished>false</IsPublished>
   <DateCreated>2013-06-18T10:00:03.012-07:00</DateCreated>
   <VersionNumber>1</VersionNumber>
   <CatalogStorageProfiles/>
   <ExternalCatalogSubscriptionParams>
      <SubscribeToExternalFeeds>true</SubscribeToExternalFeeds>
      <Location>https://vcloud2.example.com/vcsp/catalog/5</Location>
      <LocalCopy>false</LocalCopy>
   </ExternalCatalogSubscriptionParams>
</AdminCatalog>

What to do next

Synchronize the catalog with its external source. Any catalog with an external subscription includes a link of the form:

<Link
   rel="sync"
   href="https://vcloud.example.com/api/catalog/id/action/sync"/>

As a catalog owner or administrator, you can POST a request to the rel="sync" URL to synchronize the catalog with its external source. See Synchronize a Catalog or Catalog Item.