1.13.15. Integration with other systems

Instead of using the web GUI, a publication export may need to be triggered by another system. Docmenta has an internal Java API that allows you to start such actions programmatically.
Currently, the internal API is not documented and may still be subject of change. However, following JSP example demonstrates, how the internal API can be used to provide a HTTP interface to external systems. The JSP page below can be used to start a publication export:
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
50 
51 
52 
53 
54 
55 
56 
57 
58 
59 
60 
61 
62 
63 
64 
65 
66 
67 
68 
69 
70 
71 
72 
73 
74 
75 
<%@page contentType="text/html" pageEncoding="UTF-8"
import="org.docma.coreapi.*,org.docma.app.*,org.docma.webapp.*"
%><!DOCTYPE html>
<html>
<%
// Parameters for starting a publication export
String productId = request.getParameter("product");
String version = request.getParameter("version");
String language_code = request.getParameter("translation");
String publicationConfigId = request.getParameter("pubconf");
String outputConfigId = request.getParameter("outconf");
String filename = request.getParameter("filename");
if ((filename != null) && filename.trim().equals("")) {
filename = null; // use default filename
}
// The parameter pubId contains the id of the exported publication
String publicationId = request.getParameter("pubId");
String exportStatus = "";
// Get Docmenta web application instance
// Note: application is an implicit JSP object (ServletContext)
DocmaWebApplication webapp =
DocmaWebApplication.getInstance(application);
 
// Login to start export or to retrieve export status
DocmaSession docmaSess = webapp.connect("admin", "password");
try {
DocVersionId versionId = docmaSess.createVersionId(version);
docmaSess.openDocStore(productId, versionId);
if ((language_code != null) && !language_code.equals("")) {
docmaSess.enterTranslationMode(language_code);
}
if (publicationId == null) {
// Start Export
publicationId = docmaSess.createPublication(
publicationConfigId, outputConfigId, filename);
docmaSess.exportPublicationAsync(publicationId);
// To block until export is finished use synchronous call:
// docmaSess.exportPublication(publicationId)
}
 
// Show export status
DocmaPublication pub = docmaSess.getPublication(publicationId);
if (pub.isExportFinished()) {
exportStatus = "Finished (" +
pub.getErrorCount() + " Errors, " +
pub.getWarningCount() + " Warnings)";
} else {
exportStatus = "Running";
}
} finally {
docmaSess.closeSession(); // Always close the session!
}
%>
<head>
<meta http-equiv="Content-Type"
content="text/html; charset=UTF-8" />
<meta http-equiv="expires" content="0" />
<meta http-equiv="cache-control" content="no-cache" />
<meta http-equiv="pragma" content="no-cache" />
<title>Docmenta Publication Export</title>
</head>
<body>
Status: <%= exportStatus %>
<form method="get">
<input type="hidden" name="product" value="<%= productId %>" >
<input type="hidden" name="version" value="<%= version %>" >
<input type="hidden" name="translation" value=
"<%= (language_code == null) ? "" : language_code %>" >
<input type="hidden" name="pubId" value="<%= publicationId %>" >
<input type="submit" value="Refresh Status" >
</form>
</body>
</html>

Listing 1.13.1. startexport.jsp

For the example to work, you need to place the JSP file in the webapps/docmenta directory (where docmenta is your Docmenta web-application directory). Assuming that the JSP file is named startexport.jsp, and the web-server is running on port 8080 on your local host, you can start the export by entering following URL in your browser:
 http://localhost:8080/docmenta/startexport.jsp?product=my_product
  &version=Latest&pubconf=my_publication&outconf=html
The meaning of the URL parameters is given in the following table:
Request ParameterDescription
product The product ID
version The version ID, e.g "1.0"
pubconf The publication configuration ID, e.g. "my_publication"
outconf The output configuration ID ("html", "pdf", ...)
filename Optionally, the output filename can be supplied (if missing, a default name is used)
translation
The language code of the translation language (only for export of translations)
After the export has been started, a "Refresh Status" button is shown. By clicking the "Refresh Status" buttton, the export status is updated. When export is finished, the number of errors and warnings is shown. The internal API can also be used to retrieve the exported publication as a binary stream.
Note that the username and password are hard coded in the JSP script. You need to replace these values by the corresponding values of your installation.
Be aware, that when you install a new Docmenta version, all custom files that you have copied to the webapps directory are lost. For example, if you have copied the startexport.jsp file to your Docmenta webapps directory, then after upgrade of Docmenta to a newer version, the startexport.jsp file no longer exists in the Docmenta webapps directory.
To avoid this, you need to create a custom plug-in and install your JSP files as part of a Docmenta plug-in. See Section 1.13.16, “Creating a plug-in” on how to create a plug-in package.