Hippo Content Export / Import

Introduction

The Built-in REST Services provides a generic content exporting, importing and monitoring functionalities with flexible options based on the accumulated experiences and best practices.

The following URI endpoints are provided (assuming the base path of the Repository JAX-RS Service in CMS web application is /cms/ws):

• POST /cms/ws/exim/export
• POST /cms/ws/exim/import
• GET /cms/ws/exim/ps
• GET /cms/ws/exim/ps/<PID>
• GET /cms/ws/exim/ps/<PID>/logs

Both endpoints consumes multipart/form-data requests.

The endpoint for content exporting (/cms/ws/exim/export) produces a application/octet-stream response containing a content package ZIP file.

The endpoint for content importing (/cms/ws/exim/import) reads a ZIP file contained in the multipart/form-data request body, process the content package ZIP file and produces a multipart/mixed response body that contains the execution log file and the execution summary in JSON format.

The endpoint for content process status (/cms/ws/exim/ps) prints the status information of all the Content Export/Import execution processes.

The endpoint for content process status (/cms/ws/exim/ps/<PID>) prints the status information of the specified Content Export/Import process.

The endpoint for content process status (/cms/ws/exim/ps/<PID>/logs) prints the log file generated by the specified Content Export/Import process.

Find more information below.

Configuration

After you install the Built-in REST Services module following the Installation page, you need to Configure REST endpoint authorization for the services.

The authorization for the Built-in REST Services is set to the hippo:rest permission. Therefore, you need to configure a domain rule for the context-exim addon module with the permission (i.e. hipposys:role: restuser) for specific group(s) or user(s) like the following example:

    /hippo:configuration/hippo:domains/content-exim:
      jcr:primaryType: hipposys:domain
      /rest:
        jcr:primaryType: hipposys:authrole
        hipposys:groups: [admin]
        hipposys:role: restuser
      /module-domain:
        jcr:primaryType: hipposys:domainrule
        /module:
          jcr:primaryType: hipposys:facetrule
          hipposys:equals: true
          hipposys:facet: jcr:path
          hipposys:filter: false
          hipposys:type: Reference
          hipposys:value: /hippo:configuration/hippo:modules/content-exim
          

You can simply copy the above configuration to your environment through CMS Console in most cases where you simply allow this Built-in REST Services only to 'admin' group users.

Content Exporting REST Service

The signature of the content importing JAX-RS Service looks like the following:

    @Path("/exim/export")
    @Consumes(MediaType.MULTIPART_FORM_DATA)
    @Produces(MediaType.APPLICATION_OCTET_STREAM)
    @POST
    public Response exportContentToZip(@Multipart(value = "batchSize", required = false) String batchSizeParam,
            @Multipart(value = "throttle", required = false) String throttleParam,
            @Multipart(value = "dataUrlSizeThreshold", required = false) String dataUrlSizeThresholdParam,
            @Multipart(value = "docbasePropNames", required = false) String docbasePropNamesParam,
            @Multipart(value = "documentTags", required = false) String documentTagsParam,
            @Multipart(value = "binaryTags", required = false) String binaryTagsParam,
            @Multipart(value = "paramsJson", required = false) String paramsJsonParam,
            @Multipart(value = "params", required = false) Attachment paramsAttachment) {
        // SNIP
    }
          

This service tries to parse an ExecutionParams from params file attachment if provided. If params file attachment is not found, then it tries to parse one from paramsJson form parameter instead. If neither is found, then it will produce an empty ZIP file with error messages.

Other optional form parameters such as batchSize, throttle, dataUrlSizeThreshold, etc. can be used to override the parsed ExecutionParams object afterward if provided.

Content Importing REST Service

The signature of the content importing JAX-RS Service looks like the following:

    @Path("/exim/import")
    @Consumes(MediaType.MULTIPART_FORM_DATA)
    @Produces("multipart/mixed")
    @POST
    public Response importContentFromZip(@Multipart(value = "batchSize", required = false) String batchSizeParam,
            @Multipart(value = "throttle", required = false) String throttleParam,
            @Multipart(value = "publishOnImport", required = false) String publishOnImportParam,
            @Multipart(value = "dataUrlSizeThreshold", required = false) String dataUrlSizeThresholdParam,
            @Multipart(value = "docbasePropNames", required = false) String docbasePropNamesParam,
            @Multipart(value = "documentTags", required = false) String documentTagsParam,
            @Multipart(value = "binaryTags", required = false) String binaryTagsParam,
            @Multipart(value = "paramsJson", required = false) String paramsJsonParam,
            @Multipart(value = "params", required = false) Attachment paramsAttachment,
            @Multipart(value = "package", required = true) Attachment packageAttachment)
        // SNIP
    }
          

This service requires package file attachment which is used as the source to import content from. The attachment must be a ZIP file in the same format used in content exporting process.

This service tries to parse an ExecutionParams from params file attachment if provided. If params file attachment is not found, then it tries to parse one from paramsJson form parameter instead. If neither is found, then it will use the default parameters instead.

Other optional form parameters such as batchSize, throttle, publishOnImport, etc. can be used to override the parsed ExecutionParams object afterward if provided.

The response output contains both the execution log file data and summary JSON data if successful.

Process Status Monitoring REST Service

The signatures of the process monitoring JAX-RS Service look like the following:

    @Path("/exim/ps")
    @Produces(MediaType.TEXT_PLAIN)
    @GET
    public String getAllProcessInfos() {
        // SNIP
    }

    @Path("/exim/ps/{id}")
    @Produces("multipart/mixed")
    @GET
    public List<Attachment> getProcessInfo(@PathParam("id") long processId) {
        // SNIP
    }

    @Path("/exim/ps/{id}/logs")
    @Produces(MediaType.TEXT_PLAIN)
    @GET
    public String getLogsOfProcess(@PathParam("id") long processId) {
        // SNIP
    }
          

The id path parameters should be found in the /exim/ps result.