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):
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.
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.
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.
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.
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.