EngageOne Server v4.4.10 Interactive/ActiveX Editor
-
Upload
others
-
View
1
-
Download
0
Embed Size (px)
Citation preview
EngageOne Server v4.4.10 Interactive/ActiveX Editor Integration
GuideTable of Contents
2 - Interactive Editor integration
What remains unchanged 6
What has changed 7
1 - Overview This document provides detailed information on
integrating the EngageOne Compose Interactive and ActiveX editors
into your core business systems and provides in-depth information
for developers responsible and other technical staff.
In this section
Overview
EngageOne® Compose editor types
In previous versions of EngageOne® Compose (prior to 4.4.8)
Cross-browser and ActiveX editing was only available to edit
communications. The ActiveX editor was available for use with
Windows Internet Explorer only.
From EngageOne® Compose 4.4.8 the following editing options are
available:
• EngageOne® Compose Interactive Editor — a WYSIWYG editor
available in Windows in each of the supported browsers
• EngageOne® Compose ActiveX Editor – a WYSIWYG editor available
only in Windows using only Internet Explorer
• Cross-browser editor — a non-WYSIWYG editor available for every
operating system and for every web browser
Note that the EngageOne Compose Interactive Editor can be used with
the following web browsers:
• Microsoft Internet Explorer • Microsoft Edge • Mozilla Firefox •
Google Chrome
EngageOne Interactive Editor - Desktop App and ActiveX
The EngageOne Interactive Editor is supported on the following 64
Bit Operating Systems only:
• Windows 8.1 - With current Windows updates • Windows 10 - With
current Windows updates
Note: The Interactive Editor Desktop App will not install on the
out of support Windows 7 Operating System.
EngageOne® Compose EngageOne® Server Interactive/ActiveX Editor
Integration Guide 4
2 - Interactive Editor integration The EngageOne® Compose
Interactive Editor is a desktop program that is installed on your
computer. This editor provides all of the features of the embedded
ActiveX editor but with the flexibility of browser choice provided
by the Cross-Browser option.
In this section
What remains unchanged 6 What has changed 7 Considerations 8
Interactive Editor integration
What remains unchanged
• The EngageOne® Compose Interactive Editor is still launched in
Windows, however you can use it with a range of supported web
browsers.
• The existing API remains unchanged with regard to data. You can
therefore use the Interactive Editor wihout having to modify your
existing API calls that were previously made to the ActiveX
editor.
EngageOne® Compose EngageOne® Server Interactive/ActiveX Editor
Integration Guide 6
Interactive Editor integration
What has changed
The Interactive Editor is a standalone Windows application and
unlike its ActiveX counterpart, it is not run in a browser; this
application runs in a separate window.
A TypeScript library is available to allow integration with the
stand-alone editor, this can be compiled into JavaScript if
required. For example, if you are using Require.js in your
application then you can compile it into JavaScript AMD modules. If
you prefer to use SystemJS, you just need to change a single
configuration parameter and compile it to SystemJS compatible
modules.
Communication between the editor and the web page is made through
an additional relay service, this avoids any SSL restrictions.
Refer to Relay Service on page 11 for further details.
To launch Interactive Editor, you need to redirect the web page to
the correct URL. You can compose it manually or, alternatively, use
a simple function from the integration library to obtain the URL.
As discussed in later in this guide, the code is
asynchronous.
EngageOne® Compose EngageOne® Server Interactive/ActiveX Editor
Integration Guide 7
Considerations
The JavaScript code for the ActiveX editor is single threaded. Each
command is therefore only executed if all previous commands have
been processed.
The number of independent paths through a program's source code is
increased where if statements are used, but still the code is
linear.
EngageOne® Compose EngageOne® Server Interactive/ActiveX Editor
Integration Guide 8
Interactive Editor integration
In contrast to the ActiveX version, the Interactive editor's code
is not linear and can be executed by different JavaScript event
loop passes.
For example, the code from the image above is executed in three
different event loop passes; its actions are the same as the first
image in this section.
In summary:
• The left section of the code flow above is executed each time the
onStatusChange event is emitted. • The middle section of the code
is executed in the same way as the ActiveX Editor, but the code
indicated by the ellipsis character is not executed when the
template is loaded. Instead, the JavaScript engine will send a
request to the Interactive Editor to load the template. The code
will continue execution without waiting.
• The right section of the code is executed asynchronously when the
template is loaded to the Editor.
EngageOne® Compose EngageOne® Server Interactive/ActiveX Editor
Integration Guide 9
Interactive Editor integration
The image that follows illustrates sample integration code, this
will be explained in the sections that follow.
EngageOne® Compose EngageOne® Server Interactive/ActiveX Editor
Integration Guide 10
Interactive Editor integration
Relay Service
The web browser and Interactive Editor are not able to communicate
directly, when a web page is opened using the HTTPS protocol the
web browser locks any communication not protected by the SSL
protocol.
A relay service protected by SSL is provided and is installed on
the server. This obviates the need to have a valid SSL certificate
and its private key on the user's machine.
The webSocketAddress parameter provides the URL to the Relay
Service.
The sessionID parameter provides a unique identifier used by the
Relay Service to pair the connection with the integration library
instance and currently active Interactive Editor application.
Both the integration library instance and the Interactive Editor
application must use the same sessionId value. For this reason it
is included in the URL generated by our JavaScript library to
launch the Interactive Editor application.
EngageOne® Compose EngageOne® Server Interactive/ActiveX Editor
Integration Guide 11
Interactive Editor integration
Cookies
The ActiveX Editor is embedded in the web page. any service
requests are sent via the connection provided by web browser. This
connection already contains cookies from the website; for example,
authorisation, load balancer sticky session and other
cookies.
Since the Interactive Editor is a Windows stand-alone application,
it does not have access to the website and is therefore not able to
provide these cookies when downloading a template or resources such
as fonts. To cater for this, cookies are delivered to the
application by the URL used to launch the Interactive Editor.
EngageOne® Compose EngageOne® Server Interactive/ActiveX Editor
Integration Guide 12
Interactive Editor integration
Keep session alive
In the case of a regular website, to sustain the current session,
each HTTP request informs server about user’s activity. From a
JavaScript perspective, when a user performs an action, for
example, clicks a button, the web page is aware of users’ activity
and can perform an action to keep the session alive.
However, when a user edits template using the Interactive Editor,
the website is not aware of this activity and the session may
expire. To prevent this, the Interactive Editor sends a message to
the website informing that the user is active and session should
stay alive.
The keepAlive parameter indicates how many seconds to send a user
activity message.
EngageOne® Compose EngageOne® Server Interactive/ActiveX Editor
Integration Guide 13
Interactive Editor integration
Miscellaneous editor parameters
It is possible to pass several additional parameters to the
Interactive Editor that can affect the header of the Interactive
Editor window. Note that this will depend on the configuration of
the Interactive Editor on user’s computer.
EngageOne® Compose EngageOne® Server Interactive/ActiveX Editor
Integration Guide 14
Interactive Editor integration
Load and Save
The image below presents sample code for loading and saving
template.
Note that these actions return an event. Your code can subscribe to
the event to perform an action after the requested task is finished
by the Interactive Editor.
It is important to note that the action for the onLoad or the
onSaved events are performed asynchronously and the code is not
blocked while waiting for the action to be finished.
EngageOne® Compose EngageOne® Server Interactive/ActiveX Editor
Integration Guide 15
Interactive Editor integration
Keep Alive event
You can also perform an action for Keep Alive event as shown
below.
Refer to Keep session alive on page 13 for detailed information
about this functionality.
EngageOne® Compose EngageOne® Server Interactive/ActiveX Editor
Integration Guide 16
Interactive Editor integration
Error Handling
To handle errors, you must subscribe to the onError event. Please
note that actions can depend on the error flags, as shown
below:
There are two categories of errors: persistent and
miscellaneous.
A persistent error remains until it is revoked. For example, if the
Interactive Editor is not able to connect to Relay Service then it
reports error. The error is valid until a connection is
established. Such errors have the isRevocable flat set.
If you receive such error event and connection is established again
then you will receive another event with the revoke flag set. It
means that the error does not exists anymore.
You should identify the error by the error code. It is sent as
parameter in every onError event.
If neither the isRevocable or the revoke flag is set for an error
then it is miscellaneous error. In this scenario, you may wish to
show this error for a few seconds, and then hide the message.
EngageOne® Compose EngageOne® Server Interactive/ActiveX Editor
Integration Guide 17
3 - ActiveX Editor integration This chapter explains how to
complete key server integration tasks and contains sample code for
implementation in Java (under the Axis2 framework realized via
EngageOne Web Services).
In this section
ActiveX Editor integration
Integration with workflow
This section describes the most basic use-case for server
integration. The diagram below illustrates the steps you need to
follow.
User Authentication
All web services accept an authentication context which is used by
the service to authenticate the user. The authentication context
takes either a user name token or a session token for
authentication. For the initial invocation of any of the web
services, the user name token should be used to pass in the user
id, password, and domain of the user authenticating. This service
response will provide in the authentication a session token for the
authenticated user.
The session token should then be used in subsequent service
invocations.
Retrieving available domains
EngageOne organizes system data access by a community. Communities
are set up in the EngageOne Administration application, where all
valid system users are assigned to a community for authentication
purposes.
You can retrieve all communities names available to the server via
the DomainService , searchDomains method. Note that the
DomainService is the only service that does not require
authentication.
EngageOne® Compose EngageOne® Server Interactive/ActiveX Editor
Integration Guide 19
ActiveX Editor integration
First you must create an instance of the client stub for the
DomainService. All Web Service invocations require instantiation of
the client stub and this code structure also applies to subsequent
code samples shown in this section.
To create an instance of the stub, you need to know the Web Service
endpoint. Typically, an EngageOne Web Service endpoint is in the
following format:
http://<engageone-server-host>:<server-port>/EngageOneWS/<web-service-name>
where
• <engageone-server-host> is the host name where EngageOne
server is deployed
• <server-port> is the port where the EngageOne Server Web
Services is accessible
• <web-service-name> is the EngageOne Web Service you need to
invoke.
Java sample Once the stub object is instantiated you can call
searchDomains to obtain a list of available domains. The service
returns a list of Domain objects, which hold community name values.
You may use those values for invoking the subsequent services. Note
that the domain is a required field for user authentication.
Example:
EngageOne® Compose EngageOne® Server Interactive/ActiveX Editor
Integration Guide 20
ActiveX Editor integration
Invalidating a Session
It is important that you disconnect your user session to the
EngageOne server using the token you received from an earlier
authentication. Otherwise, your session will be continually active
(unless timed-out) and you will unnecessarily use up a session seat
from your product license user count.
Java sample To invalidate your session in the server you use the
SecurityService. To do this, create an instance of the client stub
for the SecurityService, then invoke the invalidateSession method
where you need to pass the token you want to invalidate.
Example:
ActiveX Editor integration
Session timeout
Session timeout determines how long an unused session can stay
valid in the server and is implemented on all EngageOne server
services. For details on how to set a timeout value see the
EngageOne Administration Guide.
You must be able to detect session time out on the server and
appropriately handle this exception depending on your
implementation.
Java sample Session timeout cases can be detected as a fault with
error code -6. In the example below the retrieveTemplateList
service is used, which shows how to handle the fault signifying
that the token you used to invoke the service has already had its
session timed out.
Example:
List<Template> templates =
response.getTemplates().getTemplate(); } catch (TemplateFault
fault) { if (fault.getFaultMessage().getCode() == -6) {
// Handle session timeout here }
ActiveX Editor integration
Retrieving templates
To retrieve the templates in the document repository via EngageOne
Web Services you use the TemplateService.
Java sample First, you need to create an instance of the client
stub for TemplateService and then invoke the searchTemplates
method:
Example:
ActiveX Editor integration
Creating a document
Once a template has been selected you must retrieve the individual
template files from the EngageOne server.
Retrieving template files
To retrieve the files associated with a template, use the
TemplateService searchTemplates method again this time passing as
input to the service the template identifier. The template can be
identified either by name or by a unique integer identifier which
is returned from the search for the template list above. Keep in
mind that template name is not unique however and searching by name
could potentially return multiple templates at different levels of
the folder hierarchy. In any event, in this second invocation of
searchTemplates, set the search filter to DETAIL and the files
associated with the template will be returned.
Each template file returned will have a type associated with it,
along with other information, that indicates which type of file it
is (i.e., HIP, Publication, XForm, etc).
Editing a document
To retrieve edit your document:
1. Load it in the EngageOne Interactive Editor. The Interactive
Editor takes the form of an ActiveX COM control, which is packaged
in a CAB file.
2. Embed the control. 3. Pass the parameters required to load the
document.Following is a list of files and other
parameters required to load a document into the Interactive
Editor:
Following is a list of files and other parameters required to load
a document into the Interactive Editor:
Properties XML file –the manifest describing a document instance.
Contains a list of further file dependencies of the document.
(.XML)
Note: This file should not be confused with the template master
file.
Publication file – the binary rules file for editing this document.
(.PUBX)
Hip file – the compiled binary rules file for composing this
document (.HIP) file
Instance XML file – data file for this document instance
(.XML)
Instance schema file – the schema for the Instance xml file.
(.XSD)
XForm file – this file is used by the editor to describe the
interactive prompts to the user. (.XFORM)
EngageOne® Compose EngageOne® Server Interactive/ActiveX Editor
Integration Guide 24
ActiveX Editor integration
Server URL string – this string describes the server location and
file retrieval method to use when downloading additional dependent
files from the server, for example,
http://www.ocmserver_xyz/EngageOneWS/openfile_by_token?token=f00e8a2fa227a03585c70
aac1b0c5084&".
Speller ID – this is the file ID, which the editor downloads to
obtain the list of speller dictionaries available.
Retrieving editor dependencies
To retrieve these dependencies you access the EngageOne server via
EngageOne Web Services. Each resource stored on the EngageOne
server has its own unique resource ID.
Files
At this stage you have streams for all the files required by the
Interactive Editor. Place your file retrieval code in an HTTP
request handler and pass the path to the request handler through to
the Interactive Editor. The editor would then make a series of HTTP
GET requests to your handler, at which point you can pass the file
stream through the output response stream.
Server URL string
The Server URL is the server location and file retrieval method use
to download additional files. This allows the Interactive Editor to
combine the resource ID of any file it requires with the Server URL
to request the physical file.
This is constructed using the server location, file retrieval
method and Web Service token as follows:
http://<SERVER>:<PORT>/EngageOneWS/openfile_by_token?token=#{token}&
The openfile_by_token is the file retrieval method presented by the
EngageOne server.
It takes one parameter:
token – this is your Web Service token, which is passed in as a
parameter. It would have been collected when connecting to the
DomainService.
Speller Manifest
The Interactive Editor requires access to a speller manifest which
contains a list of the different languages installed in the
EngageOne system. The DictionaryService is used to retrieve the
speller manifest which includes both the identifier of the manifest
in the system and the manifest file contents.
EngageOne® Compose EngageOne® Server Interactive/ActiveX Editor
Integration Guide 25
ActiveX Editor integration
Java sample The following examples show you how you make a request
to the DictionaryService to retrieve the speller manifest:
Example:
ActiveX Editor integration
Integrating the ActiveX editor in a custom application
The ActiveX editor is embedded in EngageOne Compose and available
on the installation media to be hosted by a custom application. The
web application that will host the EngageOne Interactive ActiveX
editor is responsible for handling certain items that would
normally be managed by the EngageOne Interactive web
application.
There are two entry point methods to the editor for making resource
requests to your custom application: XML message and URL. The XML
message method should be used as the primary method due to
performance advantages. When upgrading from EngageOne 3.x or
earlier, the URL method is still supported, however the URL method
does not provide the performance advantages of the XML
method.
Providing an XML message for the editor to request resources
The ActiveX Editor exposes an entry point function called
ExecuteMessage() that is an interface between the ActiveX Editor
and your custom application. An XML string is passed to this
function as a parameter that provides data such as the message name
(Load or Save), the URL to your custom application, and various
parameters that define the SRIDs of the files that the ActiveX
requires. Based on the parameters in the XML, the editor determines
which files need to be downloaded from your custom application.
Load and Save parameters are details in the tables that follow the
examples.
The following sections provide examples of the XML structure and
the schema.
XML structure - load
<?xml version="1.0" encoding="utf-8" ?> <MessageInfo
version = "1" name = "Load">
<ParameterGroup> <Parameter name ="BaseURL" value =
"http://servername:8080/EngageOneCorrespondent/
EditorDownloadServlet;jsessionid=A2305388D2EEAA177?" />
<Parameter name ="PropertiesID" value ="101" /> <Parameter
name ="AnswerID" value ="102" /> <Parameter name ="SchemaID"
value ="103" /> <Parameter name ="XFormID" value ="104" />
<Parameter name ="PubxID" value ="105" /> <Parameter name
="ReviewMode" value ="1" /> <Parameter name ="SpellMode"
value ="0" /> <Parameter name ="SpellerID" value ="107" />
<Parameter name ="SpellDisableClose" value ="0" />
<Parameter name ="Compress" value ="1" /> <Parameter
name
="ServerUrl" value = "
http://servername:8080/EngageOneCorrespondent/
Parameters Description Supported Values
String URL from which base template files (properties, answer etc.)
will be retrieved.
BaseURL
String URL from which additional template files (images, keymaps
etc.) will be retrieved.
If omitted BaseURL is used.
ServerURL
Integer Resource ID for Answer file AnswerID
Integer Resource ID for data Schema file SchemaID
Integer Resource ID for XForm file XFormID
Integer Resource ID for pubx file PubxID
0, 1 1 – Review mode (only preview) the editor doesn’t show any
prompts
0 – Normal mode (for editing)
ReviewMode
0 – Allow save without spell check
SpellMode
Integer Speller resource ID SpellerID
0, 1 1 – prevents closing until all spelling errors are
corrected
SpellDisableCheck
ActiveX Editor integration
Parameters Description Supported Values
1 Must be set to 1 for ActiveX control version earlier than
6.6.8.
Starting from version 6.6.8 it can be omitted.
Compress
<?xml version="1.0" encoding="utf-8" ?> <MessageInfo
version ="1" name ="Save">
<ParameterGroup> <Parameter name ="BaseURL" value =
"
http://servername:8080/EngageOneCorrespondent/
EditorDownloadServlet;jsessionid=A2305388D2EEAA177?" />
<Parameter name ="HipID" value ="106" /> <Parameter name
="AnswerID" value ="102" /> <Parameter name ="PubxID" value
="105" /> <Parameter name ="Compress" value ="1" />
</ParameterGroup> </MessageInfo>
Shema definition
<xs:complexType> <xs:sequence> <xs:element
name="ParameterGroup"> <xs:complexType>
<xs:sequence> <xs:element maxOccurs="unbounded"
name="Parameter"> <xs:complexType> <xs:attribute
name="name" type="xs:string" use="required"/>
<xs:attribute name="value" type="xs:string" use="required"
/>
</xs:complexType> </xs:element>
</xs:sequence>
EngageOne® Compose EngageOne® Server Interactive/ActiveX Editor
Integration Guide 29
</xs:complexType> </xs:element>
ActiveX Editor integration
Parameters Description Supported Values
BaseURL URL from which base template files String (properties,
answer etc.) will be retrieved.
ServerURL URL from which additional template String files (images,
keymaps etc.) will be retrieved. If omitted BaseURL is used.
PropertiesID Resource ID for properties XML file Integer
AnswerID Resource ID for Answer file Integer
SchemaID Resource ID for data Schema file Integer
XFormID Resource ID for XForm file Integer
PubxID Resource ID for pubx file Integer
ReviewMode 0, 1 1 – Review mode (only preview) the editor doesn’t
show any prompts
0 – Normal mode (for editing)
SpellMode 0, 1 1 – Automatically spell check on save
0 – Allow save without spell check
SpellerID Speller resource ID Integer
SpellDisableCheck 1 – prevents closing until all spelling 0, 1
errors are corrected
Compress Must be set for 1 for ActiveX control 1 version earlier
than 6.6.8, from 6.6.8 can be omitted.
EngageOne® Compose EngageOne® Server Interactive/ActiveX Editor
Integration Guide 31
ActiveX Editor integration
XML structure (Save)
<?xml version="1.0" encoding="utf-8" ?> <MessageInfo
version="1" name="Save"> <ParameterGroup> <Parameter
name="BaseURL"
value="http://servername:8080/EngageOneCorrespondent/
EditorDownloadServlet;jsessionid=A2305388D2EEAA177?" />
<Parameter name="HipID" value="106" /> <Parameter
name="AnswerID" value="102" /> <Parameter name="PubxID"
value="105" /> <Parameter name="Compress" value="1"
/>
</ParameterGroup> </MessageInfo>
ActiveX Editor integration
Parameters Description Supported Values
BaseURL URL on which PUT command will be String invoked to put
edited template files.
ServerURL URL from which additional template String files (images,
keymaps etc.) will be retrieved. If omitted BaseURL is used.
HipID Resource ID for HIP file Integer
AnswerID Resource ID for Answer file Integer
PubxID Resource ID for pubx file Integer
Compress Must be set for 1 for ActiveX control 1 version earlier
than 6.6.8, from 6.6.8 can be omitted. Server should be able to
handle compressed files.
EngageOne® Compose EngageOne® Server Interactive/ActiveX Editor
Integration Guide 33
ActiveX Editor integration
XML Schema Definition
<xs:complexType> <xs:sequence> <xs:element
name="ParameterGroup"> <xs:complexType>
<xs:sequence> <xs:element maxOccurs="unbounded"
name="Parameter"> <xs:complexType> <xs:attribute
name="name" type="xs:string"
use="required"/> <xs:attribute name="value"
type="xs:string"
use="required" /> </xs:complexType>
</xs:complexType> </xs:element>
</xs:schema>
ActiveX Editor integration
Loading the editor
The first consideration is the JavaScript required to load the
editor and identify the input files.
JavaScript example using XML message entry point
var sObject = '<object
classid="clsid:E62608CD-5C5E-4088-BFAE-B9D6D1D84CB3"
id= eoEditor height=100% width=100%/>'; nResult =
eoEditor.ExecuteMessage(loadXmlString);
Sending and receiving template resources
When ExecuteMessage with laod XML is invoked editor send GET
request to endpoint provided in Base URL with resource IDd as
parameters e.g.:
http://myapp.domain.com/editor?
/pubx=2386&properties=2391&answer=2388&schema=2389&xform=2387&compressed=true
As the result expects response with zip file. This file should flat
zip file containing all requested template resources and name of
each is its ID. So in the case of the example above, the zip file
should contain 5 files with names: 2386 for PubX file, 2391 for
Properties file, 2388 for Answer file, 2389 for Schema file and
2387 for XForm file.
When ExecuteMessage with save XML is invoked, the editor sends a
PUT request with ZIP file to endpoint provided in Base URL with
resource ID's as parameters e.g.:
http://myapp.domain.com/editor?hip=2406&pubx=2386&answer=2388&compressed=true
If the template does not contain any editable text then the URL and
zip file only contain the answer file, e.g.:
http://myapp.domain.com/editor?
answer=2388&compressed=true
The Zip file format is the same as for load commad, a flat file
with resource ID as filename.
Providing a URL for the editor to request resources
The editor needs to request additional resources to load a document
such as images, active content, and keyed images. One of the input
parameters when loading the editor is a server URL which the editor
invokes when it requires a resource located on the server. This URL
should be provided by the hosting web application. For example, a
Java servlet could be used. When the editor requires a resource, it
will invoke the URL using HTTP GET passing along with the request a
number of parameters. Assume the URL provided by the hosting
application is http://myapp.domain.com/editor. The parameters used
by the editor will be of one of two forms:
http://myapp.domain.com/editor?srid=1234
http://myapp.domain.com/editor?keymap=Keymap1&key=23
ActiveX Editor integration
The servlet is responsible for retrieving either an editor resource
or a key map depending on which form of the URL is invoked. In the
first example, the sevlet should invoke the
EditorService.retrieveResources() Web Service operation to retrieve
the resource specified by the srid parameter.
In the second example, the KeymapService.searchKeymaps() Web
Service operation should be invoked to retrieve the keyed image
contained in the key map named Keymap1 with a key of 23.
In either case, additional parameters can be provided as part of
the server URL. For example, the server URL passed to
LoadContents() or load XML could be:
http://myapp.domain.com/editor?session_id=45378292&srid=>
In this manner, the editor could pass along session information or
anything else required by the custom application when requesting
resources.
Saving document instances
Finally, the third function required by a hosting application is to
respond to HTTP PUT requests on the provided server URL once the
SaveContents() or ExecuteMessage with save XML method on the editor
is invoked. This allows the hosting application to save the updated
document instance files, including the publication HIP, the editor
PUBX, and the answer XML. These three files will be modified by the
editor and need to be saved as a document instance.
WorkItemService.createWorkItem() Web Service operation could be
used to create a new work item for the document with the three
files attached to the work item. Alternatively, the document could
be delivered to a delivery option immediately without having to
first create a work item. The DeliveryService.deliverDocument() Web
Service operation could be invoked to accomplish this.
It is recommended that after the save contents method is invoked,
that you check that the HIP, PUBX, and XML files that the ActiveX
Editor produces exist before you call any custom application. If
these files do not exist, return an applicable error.
Retrieving delivery options
The DeliveryManagementService is used to retrieve all the delivery
options that are assigned to a template. This tool presents the
logged user with a list of valid delivery options that are
available for document delivery.
JAVA SAMPLE
http://myapp.domain.com/editor?session_id=45378292&srid
ActiveX Editor integration
SearchDeliveryOptions.Templates.Template(); IntegerIdOrName id =
new IntegerIdOrName(); id.setId(templateId); template.setIdent(id);
templates.setTemplate(template); request.setTemplates(templates);
SearchDeliveryOptionsResponse response =
dmService.searchDeliveryOptions(request);
List<DeliveryOption> options =
response.getDeliveryOptions().getDeliveryOption();
An array of DeliveryOption objects is returned that contain
information about the retrieved delivery options of the specified
template.
To deliver the document you require the ID of the selected Delivery
Option. For example:
int selectedDeliveryOptionID = options.get(0).getId()
ActiveX Editor integration
Integrating the ActiveX editor in a custom application (URL
method)
This chapter describes the depreciated API and should not be used
in new implementations. Refer to Integrating the ActiveX editor in
a custom application on page 27 for details on the recommended
integration method.
Loading the document
A JavaScript function executes the loading, which is called on page
load. This invokes the LoadContents method in the EngageOne
Interactive Editor, passing the paths to the required files.
Some of the paths are URLs, which the editor uses to load the
document. These files are not saved back. Other files passed as
local file paths and are for the PUBX, HIP and Answer files. The
editor saves back to these files, which are then stored with your
document.
You can pass in the location of request handlers (for instance,
using JSP), which would handle the HTTP GET and PUT request sent by
the editor, allowing you to handle the file streams according to
your requirements.
To load the document
Specify the following script in the HEAD of your HTML page.
<script> // invokes the ActiveX LoadContents() method
function editorLoadContent(){
ipe.LoadContents('http://<server>:
<port>/EngageOneAdmin/openfile_by_token?token=<token>&srid=123',
'file:///C:/Documents%20and%20Settings/user/Local%20Settings/Temp/tmp15F.tmp',
'file:///C:/Documents%20and%20Settings/user/Local%20Settings/Temp/tmp160.tmp',
'file:///C:/Documents%20and%20Settings/user/Local%20Settings/Temp/tmp161.tmp',
'http://<server>:<port>/EngageOneAdmin/openfile_by_token?token=<token>&srid=120',
'http://<server>:<port>/EngageOneAdmin/openfile_by_token?token=<token>&srid=118',
'0', '0',
'http://<server>:<port>/EngageOneAdmin/openfile_by_token?token=<token>&',
'');
} // attach the js function to load the document content upon page
load window.attachEvent("onload", editorLoadContent);
</script>
Be aware that your HTML/JavaScript will need to be dynamically
generated to integrate the resource IDs for the template files.
This is because you will not know until run-time which resource IDs
will need to be passed into the Editor's LoadContents method. There
are several server-side scripting languages which you can use to
achieve this.
EngageOne® Compose EngageOne® Server Interactive/ActiveX Editor
Integration Guide 38
ActiveX Editor integration
Note that the URLs passed into the LoadContents interface must be
an absolute path regardless of the protocol used to access the
resource. When the Interactive Editor is deployed in a clustered
environment, the absolute path must always point to the load
balancer address.
To save the document
Once the document has been edited by the user it must be
saved.
From your application page, invoke the SaveContents() method of the
ActiveX object via JavaScript. Typically, you will set this
JavaScript function as an event handler of your UI component (e.g.
HTML input button).
<script> function editorSaveContent() { ipe.SaveContents(); }
</script>
When the Interactive Editor's SaveContents method is called it will
make a series of HTTP
PUT requests to the URLs specified when calling LoadContents. The
updated Instance file, Publication file and Production HIP file can
then be written back to their original location, so ensure that
there is write access to these locations.
Depending on how you loaded the Interactive Editor you will have
either passed in the paths to HTTP request handlers, or the
physical UNC file paths.
Request Handlers – create a PUT request handler that will handle
the HTTP PUT requests sent by the editor. The request includes the
file stream from the editor, which must be streamed to disk for
delivering the document later.
UNC file paths – the editor writes back the saved files to the
location it received them from, replacing the original files.
Once templates have been edited and the versions of the document
file are saved you must select a delivery option before you can
send your document to the EngageOne server for delivery.
EngageOne® Compose EngageOne® Server Interactive/ActiveX Editor
Integration Guide 39
ActiveX Editor integration
Document delivery
After you have completed your document and selected the delivery
option, the document can be delivered.
Delivering the document using resource files
The DeliveryService delivers documents using its resource files.
First you must create the DeliveryService stub instance and then
invoke the deliverDocument method.
The DeliverDocument class requires several key pieces of
information in order to successfully deliver a document:
• Template ID — of the document's original template • Delivery
Option ID — of the delivery option you want to deliver to •
Property file — the Property file loaded into memory • Answer File
— the document's Answer file loaded into memory • HIP file — the
document's HIP file loaded into memory
In the sample below, it is assumed that you have your completed
document resource files stored to the local disk, so you can stream
them into the memory and pass through to delivery.
In the sample below, it is assumed that you have your completed
document resource files stored to the local disk, so you can stream
them into the memory and pass through to delivery.
// JAVA SAMPLE DeliveryServiceStub deliveryService = new
DeliveryServiceStub(URL_BASE + "DeliveryService");
DeliverDocument request = new DeliverDocument();
DeliverDocument.Template template = new DeliverDocument.Template();
DeliverDocument.DeliveryOption option = new
DeliverDocument.DeliveryOption(); // Set template ID and delivery
option ID IntegerIdOrName tid = new IntegerIdOrName();
tid.setId(templateId); template.setIdent(tid); IntegerIdOrName oid
= new IntegerIdOrName(); oid.setId(optionId); option.setIdent(oid);
// Add the files template.setFiles(new
DeliverDocument.Template.Files());
DeliverDocument.Template.Files.File answer = new
DeliverDocument.Template.Files.File();
answer.setType(TemplateFileType.ANSWER); answer.setData(new
DataHandler(new FileDataSource(LOCAL_ANSFILE_PATH)));
template.getFiles().getFile().add(answer);
DeliverDocument.Template.Files.File prop = new
DeliverDocument.Template.Files.File();
EngageOne® Compose EngageOne® Server Interactive/ActiveX Editor
Integration Guide 40
ActiveX Editor integration
Retrieving local print documents
The DeliveryService retrieves the resulting document file when a
delivery item has been successfully composed. This service may only
be applied on use cases where the selected delivery option
comprises one or more delivery channels that have channel types set
to Print and have channel modes set to Immediate. Additionally, the
device of the delivery channel must have the necessary resources to
compose the document.
After successfully invoking the deliverDocument method, you extract
the local print document on the response object. A successfully
invoked service method does not throw an exception and returns a
non-null response object.
The code fragment below shows how to retrieve the composed document
files from the response object. This leaves you with the delivered
document in memory, which can be streamed to disk and viewed in the
appropriate reader.
// JAVA SAMPLE DeliverDocumentResponse response =
delivery.deliverDocument(deliverDocument); // Output the composed
file List<DeliveryItem> deliveryItem =
response.getDeliveryRequest().getDeliveryItems().getDeliveryItem();
for (DeliveryItem item : deliveryItem) {
com.pb.engageone.ws.model.ComposedDocument document =
Notices
Copyright
Copyright ©2020 Pitney Bowes, Inc. All rights reserved.
This publication and the software described in it is supplied under
license and may only be used or copied in accordance with the terms
of such license. The information in this publication is provided
for information only, is subject to change without notice, and
should not be construed as a commitment by Pitney Bowes, Inc.
(PBS). To the fullest extent permitted by applicable laws PBS
excludes all warranties, representations and undertakings (express
or implied) in relation to this publication and assumes no
liability or responsibility for any errors or inaccuracies that may
appear in this publication and shall not be liable for loss or
damage of any kind arising from its use.
Except as permitted by such license, reproduction of any part of
this publication by mechanical, electronic, recording means or
otherwise, including fax transmission, without the express
permission of PBS is prohibited to the fullest extent permitted by
applicable laws.
Nothing in this notice shall limit or exclude PBS liability in
respect of fraud or for death or personal injury arising from its
negligence. Statutory rights of the user, if any, are
unaffected.
*TALO Hyphenators and Spellers are used. Developed by TALO B.V.,
Bussum, Netherlands Copyright © 1998 *TALO B.V., Bussum, NL *TALO
is a registered trademark ®
Encryption algorithms licensed from Unisys Corp. under U.S. Patent
No. 4,558,302 and foreign counterparts.
Security algorithms Copyright © 1991-1992 RSA Data Security
Inc
Copyright © DL Technology Ltd 1992-2010
Barcode fonts Copyright © 1997 Terrapin Solutions Ltd. with NRB
Systems Ltd.
This product includes software developed by the Apache Software
Foundation (http://www.apache.org/).
Artifex and the Ghostscript logo are registered trademarks and the
Artifex logo and Ghostscript are trademarks of Artifex Software,
Inc.
This product contains the Regex++ library Copyright © 1998-2000 Dr.
John Maddock
PostScript is a trademark of Adobe Systems Incorporated.
PCL is a trademark of Hewlett Packard Company.
Copyright (c) 2000 - 2015 The Legion of the Bouncy Castle Inc.
(http://www.bouncycastle.org)
ICU License - ICU 1.8.1 and later Copyright (c) 1995-2006
International Business Machines Corporation and others All rights
reserved.
Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use, copy,
modify, merge, publish, distribute, and/or sell copies of the
Software, and to permit persons to whom the Software is furnished
to do so, provided that the above copyright notice(s) and this
permission notice appear in all copies of the Software and that
both the above copyright notice(s) and this permission notice
appear in supporting documentation.
EngageOne® Compose EngageOne® Server Interactive/ActiveX Editor
Integration Guide 43
This product contains Sycamore, version number 0.3.9, which is
licensed under the MIT license. The license can be downloaded from
https://github.com/ryexley/sycamore/blob/master/dist/requester.js.
The source code for this software is available from
https://github.com/ryexley/sycamore.
This product contains Underscore, version number 1.5.2, which is
licensed under the MIT license. The license can be downloaded from
https://github.com/jashkenas/underscore/blob/master/LICENSE. The
source code for this software is available from
http://underscorejs.org/.
This product contains Flowable, version number 6.4.1, which is
licensed under the Apache license. The license can be downloaded
from
https://github.com/flowable/flowable-engine/blob/master/LICENSE.
The source code for this software is available from
https://github.com/flowable/flowable-engine.
This product contains Bootstrap, version number 3.3.6, which is
licensed under the MIT license. The license can be downloaded from
http://getbootstrap.com/getting-started/#license-faqs. The source
code for this software is available from
http://getbootstrap.com/getting-started/#download..
This product contains Commons-Configuration, version number 1.10,
which is licensed under the Apache license. The license can be
downloaded from http://www.apache.org/licenses/. The source code
for this software is available from
http://commons.apache.org/proper/commons-configuration/.
This product contains jQuery, version number 1.10.2, which is
licensed under the MIT license. The license can be downloaded from
https://jquery.org/license/. The source code for this software is
available from http://jquery.com/download/.
This product contains Json2/JSON-js 2015-05-03. The source code for
this software is available from
https://github.com/douglascrockford/JSON-js.
This product contains Kendo UI Core, version number 2014.1.318,
which is licensed under the Apache2 license. The license can be
downloaded from https://github.com/telerik/kendo-ui-core. The
source code for this software is available from
http://www.telerik.com/download/kendo-ui-core.
This product contains Knockout-AMD-Helpers, version number 0.7.4,
which is licensed under the MIT license. The license can be
downloaded from
https://github.com/rniemeyer/knockout-amd-helpers/blob/master/LICENSE.
The source code for this software is available from
https://github.com/rniemeyer/knockout-amd-helpers.
This product contains Knockout, version number 3.4.0, which is
licensed under the MIT license. The license can be downloaded
from
EngageOne® Compose EngageOne® Server Interactive/ActiveX Editor
Integration Guide 44
This product contains Knockout-DelegatedEvents, version number
0.5.0, which is licensed under the MIT license. The license can be
downloaded from
https://github.com/rniemeyer/knockout-delegatedEvents#license. The
source code for this software is available from
https://github.com/rniemeyer/knockout-delegatedEvents.
This product contains Knockout-Kendo, version number 0.8.1, which
is licensed under the Apache2 license. The license can be
downloaded from
http://rniemeyer.github.io/knockout-kendo/index.html. The source
code for this software is available from
http://rniemeyer.github.io/knockout-kendo/.
This product contains LDAP Synchornization Connector, version
number 2.1.0, which is licensed under the BSD license. The license
can be downloaded from
http://tools.lsc-project.org/projects/lsc/repository/entry/lsc/trunk/LICENSE.txt.
The source code for this software is available from
http://lsc-project.org/wiki/download.
This product contains Moment.js, version 2.12.0, which is licensed
under the MIT license. The license can be downloaded from
https://github.com/moment/moment/blob/develop/LICENSE. The source
code for this software is available from
http://momentjs.com/.
This product contains Quartz-Scheduler, version number 2.3.1, which
is licensed under the Apache license. The license can be downloaded
from http://quartz-scheduler.org/. The source code for this
software is available from http://quartz-scheduler.org.
This product contains RequireJS Text, version number 2.0.14, which
is licensed under the BSD and MIT licenses. The license can be
downloaded from
https://github.com/requirejs/text/blob/master/LICENSE. The source
code for this software is available from
https://github.com/requirejs/text.
This product contains Solr-Solrj, version number 4.10.2, which is
licensed under the Apache License. The license can be downloaded
from
https://maven-repository.com/artifact/org.apache.solr/solr-solrj/4.10.2/pom.
The source code for this software is available from
http://wiki.apache.org/solr/Solrj.
This product contains RequireJS, version number 2.2.0, which is
licensed under the BSD and MIT licenses. The license can be
downloaded from
https://github.com/jrburke/requirejs/blob/master/LICENSE. The
source code for this software is available from
http://requirejs.org/docs/download.html.
This product contains Apache ActiveMQ, version number 5.15.9 ,
which is licensed under the Apache license, version number 2.0. The
license can be downloaded from http://www.apache.org/licenses/.The
source code for this software is available from
http://activemq.apache.org
This product contains Apache NMS version 1.7.2, which is licensed
under the Apache license, version number 2.0. The license can be
downloaded from http://www.apache.org/licenses/.The source code for
this software is available from:
http://activemq.apache.org/nms
EngageOne® Compose EngageOne® Server Interactive/ActiveX Editor
Integration Guide 45
This product contains OWASP Encoder, version number 1.2.2, which is
licensed under the BSD license. The license can be downloaded from
https://opensource.org/licenses/BSD-3-Clause. The source code for
this software is available from
https://www.owasp.org/index.php/OWASP_Java_Encoder_Project.
This product contains Narayan, version number 5.2.13.Final, which
is licensed under the LGPL license, version number 2.1. The license
can be downloaded from
http://www.gnu.org/licenses/old-licenses/lgpl-2.1.txt. The source
code for this software is available from http://narayana.io/.
This product contains Logback, version number 1.2.3, which is
licensed under the EPL and LGPL licenses, version numbers 1.0 and
2.1. The license can be downloaded from
http://logback.qos.ch/license.html. The source code for this
software is available from http://logback.qos.ch/.
This product contains JBoss Weld, version number 3.1.0.Final, which
is licensed under the Apache license, version number 2.0. The
license can be downloaded from
http://www.apache.org/licenses/LICENSE-2.0.The source code for this
software is available from http://weld.cdi-spec.org.
This product contains IronJacamar, version number 1.3.2.Final,
which is licensed under the LGPL license, version number 2.1. The
license can be downloaded from
http://www.gnu.org/licenses/old-licenses/lgpl-2.1.txt. The source
code for this software is available from
http://www.ironjacamar.org/.
This product contains Hibernate, version number 5.4.2.Final, which
is licensed under the Apache and LGPL license, version numbers 2.0
and 2.1. The license can be downloaded from
http://hibernate.org/community/license/. The source code for this
software is available from http://hibernate.org/orm/.
This product contains Apache Tomcat, version number 9.0.19, which
is licensed under the Apache license, version number 2.0. The
license can be downloaded from
http://www.apache.org/licenses/LICENSE-2.0. The source code for
this software is available from http://tomcat.apache.org/.
This product contains Apache Procrun, version number 1.1.0, which
is licensed under the Apache license, version number 2.0. The
license can be downloaded from http://www.apache.org/licenses/.The
source code for this software is available from
http://commons.apache.org/proper/commons-daemon/procrun.html.
This product contains URLRewriterFilter, version number 4.0.4,
which is licensed under the BSD 2-Clause license. The license can
be downloaded from
http://cdn.rawgit.com/paultuckey/urlrewritefilter/master/src/doc/manual/4.0/introduction.html#license.The
source code for this software is available from
http://www.tuckey.org/urlrewrite/.
EngageOne® Compose EngageOne® Server Interactive/ActiveX Editor
Integration Guide 46
This product contains FasterXML Jackson, version number 2.9.8,
which is licensed under the Apache license, version number 2.0. The
license can be downloaded from http://www.apache.org/licenses/. The
source code for this software is available from
https://github.com/FasterXML/jackson.
This product contains Log4net. The license for log4net can be
downloaded from https://www.apache.org/licenses/LICENSE-2.0. The
source code for this software is available from
https://logging.apache.org/log4net/download_log4net.cgi .
Use the following support links:
User assistance
Full documentation for EngageOne Server , Designer , Generate ,
Content Author can be found on
EngageOne® Compose Support Ask a question
Reach out to your peers and subject matter experts on the Knowledge
community
EngageOne® Knowledge Communities
USA
www.pitneybowes.com
Providing an XML message for the editor to request resources
XML structure - load
Providing a URL for the editor to request resources
Saving document instances
Retrieving delivery options
Integrating the ActiveX editor in a custom application (URL
method)
Loading the document
Retrieving local print documents