VMware vCloud Director enables organizations to create catalogs that acquire their content from a subscription to an external source. The external source can be an externally published catalog hosted on another instance of vCloud Director or a Web site that hosts a VCSP endpoint.

Configuration parameters for vCloud Director catalogs that have external subscriptions include a VCSP endpoint URL and, if the endpoint requires authentication, a user name and password. Users periodically synchronize to update catalog contents from the subscribed endpoint. You can request synchronization for an entire catalog, or for individual catalog items. The process is similar in both cases.

The endpoint is a passive partner in this process. Its only responsibilities are to keep the version numbers up to date in the endpoint descriptor and endpoint index files, and to return the HTTP status codes and other responses expected by the VCSP client.

A VCSP endpoint URL must have a scheme of HTTP or HTTPS and a path that terminates in the name of the endpoint descriptor. A VCSP endpoint whose contents are stored on a host named vcsp.example.com in a directory named /vcsp on the host and whose descriptor file is named descriptor.json would have the following endpoint URL:

http://vcsp.example.com/vcsp/descriptor.json

The endpoint descriptor is a file whose contents define the catalog available at the endpoint. The contents, which must be expressed in JavaScript Object Notation (media type application/json) as defined by RFC4627, define a JSON object, and must specify values for the following key names.

"maintenanceMessage" : "This catalog is currently in maintenance mode"

The following example shows a typical endpoint descriptor.

{
  "vcspVersion" : "1",
  "version" : "10",
  "id" : "urn:uuid:ccdd2c56-e54e-4883-bc0a-619baaca92a6",
  "name" : "published",
  "created" : "2012-09-14T22:17:50.807Z",
  "itemType" : "vcsp.CatalogItem",
  "itemsHref" : "items",
  "capabilities" : {
    "transferIn" : [ "httpGet" ],
    "transferOut" : [ "httpGet" ],
    "generateIds" : true
  }
   "metadata" : [ {
    "type" : "STRING",
    "domain" : "GENERAL",
    "key" : "key1",
    "value" : "value1",
    "visibility" : "READWRITE"
  }, {
    "type" : "STRING",
    "domain" : "SYSTEM",
    "key" : "key2",
    "value" : "value2",
    "visibility" : "READONLY"
  } ]
}

The endpoint index is a file whose contents define the set of items available in the catalog. The contents, which must be expressed in JavaScript Object Notation (media type application/json) as defined by RFC4627, define a JSON object, and must specify values for the following key names.

The following example shows a typical endpoint index.

{
  "itemType" : "vcsp.CatalogItem",
  "items" : [ {
    "version" : "1",
    "id" : "urn:uuid:6dfa4596-a7c5-4d62-9a84-c559968baa26",
    "name" : "vapp-demo",
    "created" : "2012-09-17T17:59:15.161Z",
    "type" : "vcsp.ovf",
    "files" : [ {
      "etag" : "37"
      "name" : "descriptor.ovf",
      "hrefs" : [ "/vcsp/item/6dfa4596-a7c5-4d62-9a84-c559968baa26/file/descriptor.ovf" ]
    }, {
      "name" : "descriptor.mf",
      "hrefs" : [ "/vcsp/item/6dfa4596-a7c5-4d62-9a84-c559968baa26/file/descriptor.mf" ]
    }, {
      "etag" : "37"
      "name" : "vm-d5349476-aae2-4b65-bc9a-28effdc213fb-disk-0.vmdk",
      "hrefs" : [ "/vcsp/item/6dfa4596-a7c5-4d62-9a84-c559968baa26/file/vm-d5349476-aae2-4b65-bc9a-28effdc213fb-disk-0.vmdk" ]
    } ],
    "properties" : {
    },
    "selfHref" : "/vcsp/item/6dfa4596-a7c5-4d62-9a84-c559968baa26/item.json"
  }, {
    "version" : "2",
    "id" : "urn:uuid:b63c9bbe-3614-4153-82fd-d5f4916a1327",
    "name" : "template1",
    "created" : "2012-09-14T22:18:12.858Z",
    "description" : "Added with VMware OVFTool.",
    "type" : "vcsp.ovf",
    "files" : [ {
      "name" : "descriptor.ovf",
      "hrefs" : [ "/vcsp/item/b63c9bbe-3614-4153-82fd-d5f4916a1327/file/descriptor.ovf" ]
    }, {
      "name" : "descriptor.mf",
      "hrefs" : [ "/vcsp/item/b63c9bbe-3614-4153-82fd-d5f4916a1327/file/descriptor.mf" ]
    }, {
      "name" : "vm-3fe8a95b-ccd1-4816-b4ed-d631f3e2bbf3-disk-0.vmdk",
      "hrefs" : [ "/vcsp/item/b63c9bbe-3614-4153-82fd-d5f4916a1327/file/vm-3fe8a95b-ccd1-4816-b4ed-d631f3e2bbf3-disk-0.vmdk" ]
    } ],
    "properties" : {
    },
    "selfHref" : "/vcsp/item/b63c9bbe-3614-4153-82fd-d5f4916a1327/item.json"
  } ],
     "metadata" : [] 
     "vms" : [ {
      "name" : "vm1",
      "metadata" : [ ]
     
    }, {
      "name" : "vm2",
      "metadata" : []
    } ]
  }, {
  "version" : "10"
}

The endpoint descriptor and endpoint index allow you to include object metadata that is used to create vCloud Director object metadata when endpoint contents are synchronized by a subscribed catalog. For more information about the design and operation of vCloud Director object metadata, see Working With Object Metadata.

Every item listed in the endpoint index must include an item descriptor file in the directory that holds all the item's files. The contents, which must be expressed in JavaScript Object Notation (media type application/json) as defined by RFC4627, define a JSON object, and must specify values for the following key names.

The following example shows a typical item descriptor for an OVF package.

{
  "version" : "1",
  "id" : "urn:uuid:b63c9bbe-3614-4153-82fd-d5f4916a1327",
  "name" : "template1",
  "created" : "2012-09-14T22:18:12.858Z",
  "description" : "Added with VMware Ovf Tool.",
  "type" : "vcsp.ovf",
  "files" : [ {
    "name" : "descriptor.ovf",
    "size" : 9985,
    "hrefs" : [ "descriptor.ovf" ]
  }, {
    "name" : "vm-3fe8a95b-ccd1-4816-b4ed-d631f3e2bbf3-disk-0.vmdk",
    "size" : 833536,
    "hrefs" : [ "vm-3fe8a95b-ccd1-4816-b4ed-d631f3e2bbf3-disk-0.vmdk" ]
  } ],
  }  "properties" : {
  }
}

VCSP clients retrieve catalog files, including the descriptor and the endpoint index, with GET requests. The endpoint must return one of the following responses:

The client continues to make GET requests until it receives either a 200 response or a 503 response with a nonempty message.

For example, an in-progress operation could return the following response.

{
  "status" : "",
  "progress" : 10
}

An operation that has encountered an error could return the following response.

{
  "status" : "failed",
  "message" : "File Generation failed"
}

An endpoint can require authentication. VCSP clients always present the user name vcsp when logging in. The endpoint can specify any password for this user, but must accept the user name vcsp. The user name and password are encoded as specified for Basic HTTP authentication.

Version numbers appear in the endpoint descriptor and endpoint index as version values, which are integer values that increment monotonically. It is the responsibility of the endpoint to increment the appropriate version value whenever any of the following changes occur.