Support and Documentation

Implementation requirements

To import content from third-party repositories, you must supply the following implementations:

ExternalItem implementation

An ExternalItem implementation represents an object referenced in a third-party repository. Extending ExternalItem, the implementation provides a bridge between data retrieved from the repository and an internal Brightspot object to which the data will be converted. An external item is identified with a unique ID, and you must implement ExternalItem#getExternalItemId to return a unique ID of an external item.

The following example shows an ExternalItem implementation that represents an image in the external Getty repository. Its setters and getters support creation of GettyImage objects with third-party data and conversion to internal Brightspot objects. Also included are methods that enable Brightspot to display Getty images in the search panel and in content edit forms.

public class GettyImage extends ExternalItem {

   private String title;

   private String gettyId;

   @ToolUi.NoteHtml("<span data-dynamic-html='${content.getUrlPreviewHtml()}'></span>")
   private String url;

   private String caption;

   public String getTitle() { return title; }
   public void setTitle(String title) { this.title = title; }

   public String getGettyId() { return gettyId; }
   public void setGettyId(String gettyId) { this.gettyId = gettyId; }

   public String getUrl() { return url; }
   public void setUrl(String url) { this.url = url; }

   public String getCaption() { return caption; }
   public void setCaption(String caption) { this.caption = caption; }

   public String getExternalItemId() { return getGettyId(); }

   public StorageItem getPreviewFile() {
      return Optional.ofNullable(getUrl())
             .map(url -> {
                 StorageItem file = new UrlStorageItem();
                 return file;

   public String getUrlPreviewHtml() {
      String url = getUrl();

      if (url == null) {
         return "<span></span>";

      StringWriter stringWriter = new StringWriter();
      HtmlWriter htmlWriter = new HtmlWriter(stringWriter);

      try {
                 "src", url,
                 "style", htmlWriter.cssString(
                         "width", "auto",
                         "height", "500px",
                         "border", "solid 1px #cdcdcd",
                         "padding", "3px"));

      } catch (Exception error) {
         // Ignore.

      return stringWriter.toString();


In the previous snippet—

  • Line 1 is the @Recordable.PreviewField annotation that tells Brightspot to call the internal getPreviewFile method (line 34), which returns a Getty image for display in the search panel results.

  • Line 2 is the @Recordable.SourceDatabaseClass annotation that tells Brightspot which database provider class to use to retrieve Getty images. The specified database provider creates an instance of the HttpEndpointDatabase implementation, which integrates with the Getty third-party service. For more information, see SourceDatabaseProvider implementation.

  • Lines 5–15 specify the GettyImage fields. The fields will be populated with data retrieved from the Getty repository.

    • The @ToolUi.DefaultSearchResult annotation tells Brightspot to show the ID of the retrieved Getty image in the search results.

    • The @Recordable.DisplayName annotation tells Brightspot to use "Image" as the label for the url field in the content edit form for the GettyImage type.

    • The @ToolUi.NoteHtml annotation uses a Java Expression Language (EL) statement that tells Brightspot to call the internal getUrlPreviewHtml method (line 44). The annotation results in construction of an HTML <img> tag that references the image in the Getty repository, enabling the image to be displayed in the GettyImage content edit form.

  • Lines 30 is the required getExternalItemId implementation, which returns a unique ID for a Getty image.

  • Lines 34–42 use a Getty image URL to return the image that's displayed in the search panel results.

  • Lines 44–68 return an HTML <img> tag for Brightspot to display the image in the GettyImage content edit form.

ExternalItemConverter implementation

An ExternalItem implementation and associated database provider retrieve data from a third-party repository and make it visible in Brightspot as an ExternalItem type. For an external item to be completely imported into Brightspot, it must be converted to an internal Brightspot type. An external item converter must implement the ExternalItemConverter#convert method. The following example shows an ExternalItemConverter implementation that converts the external GettyImage type to an internal Brightspot Image type.

public class GettyImageToImageConverter implements ExternalItemConverter<GettyImage> {

   private static final Logger LOGGER = LoggerFactory.getLogger(GettyImageToImageConverter.class);

   public Collection<?> convert(GettyImage gettyImage) {
      Image image = new Image();

      String url = gettyImage.getUrl();
      if (url == null) {
         return Collections.singletonList(image);
      url = url.substring(0, url.lastIndexOf("?"));

      try {
         StorageItem file = StorageItem.Static.create();
         file.setPath(new RandomUuidStorageItemPathGenerator().createPath(url));

         ByteArrayOutputStream outputStream = new ByteArrayOutputStream();
         ImageIO.write( URL(url).openStream()), "jpg", outputStream);

         file.setData(new ByteArrayInputStream(outputStream.toByteArray()));;

      } catch (IOException error) {
         LOGGER.error("Unable to save Getty Image file!", error);

      return Collections.singletonList(image);

In the previous snippet—

  • Lines 7–9 copy field data from a GettyImage object passed to the method into a new instance of Image.

  • Lines 11–15 get the URL that points to the Getty image.

  • Lines 17–31 retrieve the Getty image from the external repository and save it as a StorageItem object in the Brightspot repository.

  • Line 33 returns the image as an internal Brightspot type.