NPrinting On-Demand: Architecture and Configuration

    Architecture


    NPrinting On-Demand is a Windows service which exposes a set of APIs through two configurable endpoints:

    • WS endpoint: it is a web-service interface that uses a standard SOAP protocol over HTTP or HTTPS.

    • HTTP endpoint: it is a web-service interface that uses a RESTful protocol over HTTP or HTTPS.

     

    Exposed APIs are similar but work with two different protocols.

    Each endpoint can be configured independently (see the following section below).

    Each endpoint can be enabled or disabled.

    Each endpoint can run in SSL mode or node (see section below).

    The required Endpoint type depends on the deployment scenario. Read the “NPrinting Server settings requirements” section of the scenario of interest to define the required endpoint.

     

    WS endpoint is required for:

    • Custom Objects

    • Workbench integration

    • Custom integration with third party software

     

    HTTP endpoint is required for:

    • Ajax extensions


    How to configure On-Demand service endpoints


    To modify default endpoint settings:

    1. Open the resource explorer
    2. Type %appdata%\NPrinting\ODS into the address bar
    3. Open the ods.config file using a text editor
    4. Change the key values as you prefer in your environment.
    5. WsEnabled and HttpEnabled enable or disable the WS and HTTP endpoints respectively.
    6. WsHostname and HttpHostname are the DNS hostnames of  the WS and HTTP interfaces respectively as they appear to clients. If you enable SSL, these names must be the same as indicated in the SSL certificate.
    7. WsPort and HttpPort are the TCP ports used for the WS and HTTP interfaces respectively. If both endpoints are enabled these ports must be different.
    8. WsEnableSSL and HttpEnableSSL enable or disable the SSL protocol in the respective interface. See section below for further detail about SSL configuration.
    9. Save the file
    10. Check that your firewall settings are compliant with the new settings (see section “Firewall settings” above)
    11. Restart the service
    12. Check if configuration has been applied correctly by opening the log file %appdata%\NPrinting\ODS\internal.log using a text editor

    Ports reservation
    Ports reservation is
    done automatically at service startup in NPrinting 14.0.0.12 or higher releases. In this case skip this section.

    In some installations you must reserve TCP ports listening for On-Demand service process.
    Open a command prompt as administrator:

     

    If SSL is disabled type:
    netsh http add urlacl url=http://+:9000/ user=DOMAIN\user
    netsh http add urlacl url=http://+:9001/ user=DOMAIN\user
    (replace 9000 and 9001 with your TCP ports and DOMAIN\user with user you use to launch NPrinting service)

     

    If SSL is enabled type:
    netsh http add urlacl url=https://+:9000/ user=DOMAIN\user
    netsh http add urlacl url=https://+:9001/ user=DOMAIN\user
    (replace 9000 and 9001 with your TCP ports and DOMAIN\user with user you use to launch NPrinting service)

    If a port is reserved by other process and you are sure you can use it in On-Demand remove the reservation before enabling it typing
    netsh http delete urlacl url=http://+:9000/
    (replace 9000 with target TCP port and http with https if SSL is enabled)

    See here for further details:
    http://msdn.microsoft.com/en-us/library/ms733768(v=vs.110).aspx

     

     

    Firewall settings

    Definitions

    • {WsHostname} is the DNS name of the web service endpoint. When the service starts for the first time, it is set to the hostname of NPrinting On-Demand Service machine by default.

    • {WsPort} is the TCP port of the web service endpoint. When the service starts for the first time, it is set to 9000 by default.

    • {HttpHostname} is the DNS name of the HTTP service endpoint. When the service starts for the first time, it is set to the hostname of NPrinting On-Demand Service machine by default.

    • {HttpPort} is the TCP port of the HTTP service endpoint. When the service starts for the first time, it is set to 9001 by default.

     

    It is a good practice to enable only the required endpoint for your installation for security reasons.

    For example: if you plan to use only full Ajax extensions then the HTTP endpoint must be enabled and the WS endpoint should be disabled.

    Settings

     

    Check that your firewall settings are compliant with the new settings

    1. if HTTP endpoint is enabled HTTP protocol on address {HttpHostname}:{HttpPort} must be reachable by end user machines

    2. if WS endpoint is enabled HTTP/SOAP protocol on {WsHostname}:{WsPort} must be reachable by end user machines


    Enable SSL

     

     

    SSL can be enabled selectively per-endpoint: for example you can enable SSL for HTTP endpoint and disable SSL for WS endpoint.

     

    A valid certificate signed by a valid CA (public or domain) must be bound to the https://yourhostdnsname:ajaxport/ address you plan to use for the endpoint.

    Contact your system administrator to do this.

     

    Useful tutorials are these:

     

    It can be useful in a development environment to configure SSL using a local-machine signed certificate.

    Follow this tutorial to do so: http://www.codeproject.com/Articles/24027/SSL-with-Self-hosted-WCF-Service

     

    Once a valid SSL certificate is bound to the SSL address url you must enable the NPrinting Server to use it. To do this:

    1. stop the NPrinting Server

    2. edit the “%appdata%\NPrinting\ODS\ods.config” file with a text editor

    3. set the “HttpEnableSSL” and/or “WsEnableSSL” properties values to “true”

    4. save the file

    5. restart the NPrinting Server


      Check if configuration has been applied correctly by opening the log file %appdata%\NPrinting\ODS\internal.log using a text editor.


    Sample ODS config file with SSL enabled (backup the config file before making any changes to it):


    <?xml version="1.0" encoding="utf-8" ?>

    <configuration>

        <appSettings>

     

            <!-- Web services endpoint settings -->

     

            <add key="WsEnabled" value="true" />

            <add key="WsHostname" value="www.yourURLhere.com" />

            <add key="WsPort" value="9000" />

            <add key="WsEnableSSL" value="true" />

          

            <!-- HTTP endpoint settings -->

     

            <add key="HttpEnabled" value="true" />

            <add key="HttpHostname" value="www.yourURLhere.com" />

            <add key="HttpPort" value="9001" />

            <add key="HttpEnableSSL" value="true" />

     

        </appSettings>

    </configuration>


    Important: When SSL is enabled, the HTTP channel is disabled and the HTTPS channel is enabled. So all Extensions and/or Custom Objects must be configured with the UseSSL flag set to true. Conversely, if SSL is disabled, all extensions must be configured with the UseSSL flag set to false.


    Important: If QlikView Access Point is configure with SSL, On-Demand service must be configured in SSL too, else NPrinting On-Demand extensions show an "NPrinting service is unreachable" error. This is a restriction due to browser's Same Origin Policy mechanism.


    Logging


    NPrinting On-Demand service records two types of log information: internal log and auditing log.

    Log files can be found in the %appdata%\NPrinting\ODS folder.

     

    auditing.log registers all client calls to the service and all server responses to the client. 1 log per-day and 30-days retention policy is enforced.

     

    internal.log file contains internal logging details such as startup and shutdown events, setting and error details. Before contacting support, it is good practice to take a look at internal.log to gather more information about the issue.

     

    Common errors that occur in the NPrinting engine are mapped with the following codes:

     

    0xA7FF0000

    Unexpected error occured during On-Demand request processing

    0xA7FF0001

    Unsupported settings specified in On-Demand request

    0xA7FF0002

    On-Demand license not activated

    0xA7FF0003

    Specified NPrinting file in On-Demand request not found

    0xA7FF0004

    Specified report in On-Demand request not found

    0xA7FF0005

    Specified task in On-Demand request not found

    0xA7FF0006

    Specified filter in On-Demand request not found

    0xA7FF0007

    Specified recipient in On-Demand request not found

    0xA7FF0008

    Specified connection in On-Demand request not found or incompatible

    0xA7FF0009

    Unexpected error occured during On-Demand request generation

    0xA7FF000A

    Unexpected error occured during On-Demand request execution

    0xA7FF000B

    Unsupported format specified in On-Demand request