Fork me on GitHub

ExecutionParams as Common Parameter Used in REST Services

JSON Schema for ExecutionParams

In both content exporting and importing endpoints, a JSON file or content may be used as input parameter, and it may contain all the available parameters to instruct how to execute the process in more detail.

The parameter is abstracted in ExecutionParams object described below in JSON Schema format. 

{
  "$schema": "http://www.onehippo.org/bloomreach-forge/content-exim/schema#",

  "definitions": {
    "ExecutionParams": {
      "type": "object",
      "properties": {
        "batchSize": {
          "description": "The batch size in content export or import process, equivalent to the batch size parameter in the Groovy Updater.",
          "type": "integer"
        },
        "throttle": {
          "description": "The throttle in content export or import process, equivalent to the throttle parameter in the Groovy Updater.",
          "type": "integer"
        },
        "publishOnImport": {
          "description": "Document publishing option on content importing process. It can be 'none', 'all' or 'live'. 'none' by default. It doesn't publish an imported/updated document automatically with 'none'. It publishes an imported/updated document automatically with 'all'. It publishes an imported/updated document automatically with 'live' only when the source content was a 'live' content.",
          "type": "string"
        },
        "dataUrlSizeThreshold": {
          "description": "The maximum byte size threshold to use either data: URL or file: URL for binary resource data.",
          "type": "integer"
        },
        "binaries": {
          "description": "Binary content JCR queries or node paths to export or import.",
          "type": "#/definitions/QueriesAndPaths"
        },
        "documents": {
          "description": "Document content JCR queries or node paths to export or import.",
          "type": "#/definitions/QueriesAndPaths"
        },
        "docbasePropNames": {
          "description": "Property names to convert docbase string property (not standard hippo:docbase) values to node paths or UUIDs.",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "documentTags": {
          "description": "Extra document tagging properites (name and value(s), separated by '=' and comma for values) to add in either exporting or importing process. e.g, myhippoproject:tags=a,b,c",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "binaryTags": {
          "description": "Extra document tagging properites (name and value(s), separated by '=' and comma for values) to add in either exporting or importing process. e.g, myhippoproject:tags=a,b,c",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "galleryFolderPrimaryType": {
          "description": "Gallery folder primary node type. 'hippogallery:stdImageGallery' by default.",
          "type": "integer"
        },
        "galleryFolderFolderTypes": {
          "description": "Gallery folder's 'folder-types' property. ['new-image-folder'] by default.",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "galleryFolderGalleryTypes": {
          "description": "Gallery folder's 'gallery-types' property. ['hippogallery:imageset'] by default.",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "assetFolderPrimaryType": {
          "description": "Asset folder primary node type. 'hippogallery:stdAssetGallery' by default.",
          "type": "integer"
        },
        "assetFolderFolderTypes": {
          "description": "Asset folder's 'folder-types' property. ['new-file-folder'] by default.",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "assetFolderGalleryTypes": {
          "description": "Asset folder's 'gallery-types' property. ['hippogallery:exampleAssetSet'] by default.",
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "required": [ ]
    },
    "QueriesAndPaths": {
      "type": "object",
      "properties": {
        "queries": {
          "description": "JCR Query statements in either XPATH or SQL to execute queries in content exporting process.",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "paths": {
          "description": "JCR Node paths used in content exporting process. It is valid only when a path represents either a handle or a variant node.",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "includes": {
          "description": "ANT Path Style patterns to include. e.g, '/content/a/b/*', '/content/a/b/**/c', etc.",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "excludes": {
          "description": "Ant Path Style patterns to exclude, taking precedence over includes. e.g, '/content/a/b/*', '/content/a/b/**/c', etc.",
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "required": [ ]
    }
}

Simple Examples

In content importing process, you don't have to provide an ExecutionParams object (in either paramsJson form parameter or params file attachment) because it takes resonable default values and process the package ZIP file attachment.

However, in content exporting process, you should provide information about what (which binary or document content) to export at least. Therefore, one minimal ExecutionParams example for /cms/ws/export endpoint would look like this: 

{
  documents: {
    queries: [
      '/jcr:root/content/documents//element(*,hippo:document)'
    ]
  }
}

With the ExecutionParams input, the content export process will try to query the documents based on the given JCR queries and packages everything, including binary content referred by the documents as well, to a ZIP file which is sent over in HTTP response body to the client in the end.

You can also specify binary content queries separately as well: 

{
  binaries: {
    queries: [
      '/jcr:root/content//element(*,hippo:document)[@jcr:primaryType=\'hippogallery:imageset\' or @jcr:primaryType=\'hippogallery:exampleAssetSet\']'
    ]
  },
  documents: {
    queries: [
      '/jcr:root/content/documents//element(*,hippo:document)'
    ]
  }
}

You can specify multiple query statements for both binaries and documents. Also, you can specify paths JSON array in binaries or documents property to list binary or document node paths more specifically instead of using JCR queries. 

{
  documents: {
    queries: [
      '/jcr:root/content/documents/myhippoproject/news//element(*,hippo:document)',
      '/jcr:root/content/documents/myhippoproject/events//element(*,hippo:document)'
    ],
    paths: [
      '/content/documents/myhippoproject/content/about',
      '/content/documents/myhippoproject/content/contact',
    ]
  }
}
The items in paths are valid only when each points to a handle node or variant node of a document of a binary. Otherwise (e.g, a folder), it will be just ignored. If you want to use a folder, then use queries in JCR query statement format instead.
If both queries and paths are set, the built-in REST Services will merge all the nodes into a set, not to have duplicate content nodes to process internally.

You can also specify other optional parameters such as batchSize, threshold, dataUrlSizeThreshold, etc. 

{
  batchSize: 200,
  threshold: 10,
  dataUrlSizeThreshold: 262144,
  documents: {
    queries: [
      '/jcr:root/content/documents//element(*,hippo:document)'
    ]
  }
}

Filtering Examples

In both content exporting and importing processes, you can also specify ANT-style path patterns to exclude or include content nodes.

excludes takes the precedance over includes. When includes is not specified or an empty array, every content path will be included unless the path is excluded by excludes. 

{
  binaries: {
    // ...
    includes : [ '/content/gallery/myhippoproject/**' ],
    excludes : [ '/content/gallery/myhippoproject/samples/**' ]
  },
  documents: {
    // ...
    includes : [ '/content/documents/myhippoproject/**' ],
    excludes : [ '/content/documents/myhippoproject/news/**' ]
  }
}

In the above example, all the binary content found in the queries and paths (omitted in the examples) will be checked with the excludes and includes. If the path of a binary content item is not in excludes patterns, and if the path is in includes patterns or includes is empty, then the binary content item will be exported or imported.

In the same way, all the document content found in the queries and paths (omitted in the examples) will be checked and excluded or included in exporting or importing processes.