Information for: DEVELOPERS   PARTNERS

Acquia Content Hub and CDF

This page applies to Acquia Content Hub 1.x. For Acquia Content Hub 2.x CDF information, see Common Data Format.

Acquia Content Hub uses the Common Data Format (CDF) for communication data between the Acquia Content Hub storage service and the end-user client layer comprising all the applications connected to the hub. Acquia Content Hub uses the JSON format to serialize CDF. Every piece of data is typed to ease its indexing for search.

Entity structure

The most important piece of the common data structure is the array of entities it refers to. Each entry is an unrestricted entity, allowing the transmission of heterogeneous collections in a single file.

The following is an example of the entities object:

{
   "entities": [
      {
            "uuid": "00000000-0000-0000-0000-000000000000",
            "type": "product",
            "created": "2013-04-15T18:56:54-04:00",
            "modified": "2014-02-24T16:13:47-05:00
            "origin": "16074522-f318-4a69-52f5-bb6d740e5a41",
            "attributes": {
               "title": {
                  "type": "string",
                  "value": {
                        "en": "A",
                        "hu": "B",
                        "und": "C"
                  }
               },
            },
            "assets": [
               {
                  "url": "http://mysite.com/sites/default/files/foo.png",
                  "replace-token": "[acquia-logo]"
               },
               {
                  "url": "http://mysite.com/sites/default/files/bar.png",
                  "replace-token": "[acquia-thumb]"
               }
            ]
      }
   ]
}

The elements of an entity are:

  • uuid: Each entity is identified by a required UUID. Each client application should map its internal storage to the UUID to enable data synchronization over time.
  • type: An arbitrary string which may be used by the client side to determine the entity type and trigger appropriate behavior. Examples include articles and products.
  • created: The created date in ISO 8601 standard format.
  • modified: The modified date in ISO 8601 standard format.
  • origin: The UUID of the client application which originally created and owns the entity. This can be useful on the client side to know if a client can to perform actions such as editing an entity.
  • attributes: Localizable collections of values keyed by the attribute name. Each attribute is typed so for storage in Acquia Content Hub and indexed for search purposes. See Attributes.
  • assets: A list of resources referenced in the attributes of the entity in the form of tokens. url points to the Asset. Token strings will be replaced in every attribute that has an occurrence in their value.

Attributes

Attributes can be single pieces of information, or can be passed as nested attributes. Nested attributes follow the Elasticsearch methodology for mapping.

  • type: Any primitive data type, such as integer, string, keyword, boolean, number, or reference. If the value is an array, the type should be wrapped (for example: array).
  • value: An associative array, always keyed by language. Unlocalized
    data must contain the und key, which is the standard for undefined language data.

Accessing an entity’s CDF

Acquia Content Hub uses custom paths to both access an entity’s CDF and prevent conflicts with the default system path.

To access an entity’s CDF, in your browser’s address bar enter a URL like the following:

[site]/acquia-contenthub-cdf/[entity type]/[entity id]?_format=acquia_contenthub_cdf

where:

  • [site] is your website’s domain name
  • [entity type] is the entity type
  • [entity id] is the entity’s ID number

For example, the following URL example enables access to a paragraph entity’s CDF:

[site]/acquia-contenthub-cdf/paragraph/1?_format=acquia_contenthub_cdf

Modifying entities and the CDF with hooks

Acquia Content Hub provides hooks for modifying your website’s entities and CDF. Use them to improve syndication, and change view modes in your website’s CDF to support custom rendering processes:

  • Allow modules to update the Drupal entity after conversion from CDF
    • Drupal 8: hook_acquia_contenthub_drupal_from_cdf_alter
    • Drupal 7: hook_content_hub_connector_drupal_from_cdf_alter
  • Allow modules to update the CDF before it’s sent to Acquia Content Hub
    • Drupal 8: hook_acquia_contenthub_cdf_from_drupal_alter
    • Drupal 7: hook_content_hub_connector_cdf_from_drupal_alter
  • Allow modules to update the CDF before converting to Drupal entity
    • Drupal 8: acquia_contenthub_cdf_from_hub_alter
    • Drupal 7: hook_content_hub_connector_cdf_from_hub_alter
  • Allow modules to update the Drupal entity before its normalization to CDF
    • Drupal 8: acquia_contenthub_drupal_to_cdf_alter
    • Drupal 7: hook_content_hub_connector_drupal_to_cdf_alter

Recommendations

Acquia recommends the following items be consistent between non-Drupal websites and Acquia Content Hub:

  • When building a connector to publish to Acquia Content Hub, Acquia recommends you rename the other system’s attributes to match what Drupal expects. This is more important for attributes built into Drupal, such as Title. Renaming helps ensure consistent naming across all systems, which is important for token usage.
  • Express dates in the ISO 8601 format-for example, 2016-02-09T23:04:20-05:00. In PHP, use date('c') instead of date('Y-m-d H:i:s'). Using date('Y-m-d H:i:s') returns 2016-02-09 23:04:20, which is incorrect.