› Integration with third-party software › RightFax fax server - REST WebAPI

RightFax fax server - REST WebAPI

In addition to configuring the connection to the RightFax fax server in KC Plug-In, install/enable the RightFax WebAPI interface on the RightFax server to use with Kofax Import Connector.

Work with your fax server administrator to complete the tasks described in the following sections.

RightFax client installation is not necessary on the Message Connector computer.

Prerequisites

RightFax server version 16.4 or higher to support the REST Web API for the clients.

The support for the traditional COM API is discontinued from the RightFax server version 16.6 onwards.

Configure RightFax server

Install/enable the RightFax WebAPI interface explicitly on the RightFax server.

Allow the Http verbs GET,POST, PUT and DELETE on the IIS on RightFax server. You may disallow especially PUT and DELETE on the IIS due to some historical reasons, for example, by the Microsoft's UrlScan utility.

  1. On the RightFax fax server, start the Enterprise Fax Manager tool.
  2. Create (or reserve) a user/extension for use with Kofax Import Connector.
  3. Close the tool.
  4. Optional. Verify the connection through REST WebAPI to the RightFax server with the OpenText’s FaxUtil Web client, which uses the same API as the Message Connector. Therefore, if you cannot access the RightFax server mailbox, the Rightfax Connector will also not work. To verify the connection, do the following:
    1. Execute the following URL in a browser of a computer where Message Connector is installed: http://<RightFaxServer>/rightfax.

      Where <RightFaxServer> is the IP address or hostname of the RightFax server.

    2. Click the FaxUtil Web button and login with any RightFax user. Verify if you can access the mailbox.

      If you still cannot access RightFax server with FaxUtil Web, contact using the above steps, contact your Rightfax server administrator.

Configure RightFax connector in KC Plug-In

The following configurations are specific for the RightFax Rest WebAPI fax server type. For complete fax server settings, refer to the KC Plug-In online help.

  1. Open the Fax server import settings window.
  2. On the Type list, select RightFax Rest WebAPI.
  3. In the Host field, specify the fax server URL in the http[s]://<RightFaxServer>/rightfax/api format.

    where <RightFaxServer> is the IP address or hostname of the RightFax server.

  4. Under Operation Mode, select whether to poll fax server using single or multiple Message Connectors. See the next section.

Single and multi-instance modes

When configuring the RightFax server in KC Plug-In, you can select to poll the RightFax server using one or multiple instances of Message Connectors.

Single instance mode

Use this mode to poll the fax server with only one Message Connector. Selecting this option and running multiple connections in parallel may import the same fax multiple times in Kofax Capture.

The following is the process of importing a message:

  1. When a new fax is detected in the fax server inbox, it is immediately imported into the Message Connector storage. The comment field of the message in the RightFax server inbox displays the following status:

    [<UniqueId>]KCFax:fetched at <Date and Time>,awaitConfirm for 600s

    Where:

    <UniqueId>: The unique ID of Message Connector which is polling the fax server.

    <Date and Time>: The UTC date and time when the message arrived in ISO 8601 format.

  2. Once the message is imported into Kofax Capture, the comment field of the message in the RightFax server inbox is updated with the following status:

    [<UniqueId>]KCFax:deleted at <Date and Time>

  3. The message is deleted immediately.

Multi instance mode

Use this mode to allow multiple Message Connector connections to a single fax server. This mode avoids duplicate imports but introduces a small delay in importing faxes (Default: 60 seconds).

When a new fax arrives in the fax server inbox, instead of importing this message immediately, all Message Connector instances attempt to reserve the message. But the message is reserved for only one instance of Message Connector and only that instance can fetch the message.

The following is the process of importing a message:

  1. When a new fax is detected in the fax server inbox, this message is reserved for a specific instance of Message Connector. Before importing, this message waits in the inbox for 60 seconds (ReservationTimeout).

    The comment field of the message in the RightFax server inbox displays the following status:

    [<UniqueId>]KCFax:reserved at <Date and Time>,awaitFetch for 60s

    Where:

    <UniqueId>: The unique ID of Message Connector which is polling the fax server.

    <Date and Time>: The UTC date and time when the message arrived in ISO 8601 format.

  2. Once 60 seconds (ReservationTimeout) expires, the message is immediately imported into Message Connector storage. The comment field of the message in the RightFax server inbox displays the following status:

    [<UniqueId>]KCFax:fetched at <Date and Time>,awaitConfirm for 600s

  3. When the message is imported into Kofax Capture, the comment field of the message in the RightFax server inbox is updated with the following status:

    [<UniqueId>]KCFax:deleted at <Date and Time>

  4. The message is deleted immediately.

If a message reserved for a specific Message Connector is not polled due to reasons, such as, the specific Message Connector instance not working, the following process is used:

  1. The message remains in the reserve state for ProcessingTimeout (Default: 3600 seconds).

  2. Once ProcessingTimeout expires, the message enters and remains in expiry pending state define by ExpiryTimeout (Default: 300 seconds).

  3. Once ExpiryTimeout expires, the message can be reserved by any running instance of Message Connector and is treated as a new message.

    To compensate ReservationTimeout (60 second) for every message, each Message Connector instance can reserve up to 100 messages (MaxReservedTotal) and keep polling the messages for which ReservationTimeout expires.

By default, all configuration values are defined for optimum performance. If required, change the values of these parameters in the Create_Config.xslt file.

Parameter name Default value Description
ReservationTimeout 60 seconds The time for which the message remains in a reserved state.
ProcessingTimeout 3600 seconds The time limit for processing a message once the reserve timer is expired.
MaxReservedTotal 100 Maximum number of messages a single instance of Message Connector can reserve.
ExpiryTimeout 300 seconds The time limit to wait after ProcessingTimeout. Once this expires, the message is handled as a new message.

Forward faxes from multiple mailboxes to a single queue user

In KC Plug-In, you can only configure a single user for accessing RightFax. You can access multiple mailboxes using an administrator user. If you do not want to use an administrator user for security reasons, you can set up fax forwarding to a dedicated user, and use the credentials of this user in KC Plug-In. Each fax user must configure fax forwarding using RightFax FaxUtil.

  1. Start RightFax FaxUtil from the Windows Start menu and log in.
  2. On the Tools menu, click Options.
  3. On the Receiving tab, select Forward Received Faxes to Users.
  4. Select the dedicated user as the recipient of the forwarded faxes.
  5. Confirm the changes and close FaxUtil.

Keep messages on RightFax server

By default, Kofax Import Connector deletes imported messages from the fax server. You can configure Message Connector to keep the messages on the fax server for later processing. Do the following in Message Connector Configuration:

  1. Set Keep messages on RightFax Server of the Fax Server tab to "[8] Yes".
  2. Start Message Connector configuration. Verify the value in the Fax Server tab.
  3. Click Save, then click Exit.

Imported messages are no longer deleted from the RightFax server, instead, the text "KCFax:marked to delete" is added to the comment field.

Poll order

Following improvements are implemented in the RightFax Connector to avoid situations where some faxes may stay much longer in the inbox than others.

RightFax connector - Web API RightFax connector - COM API

Fetches the oldest fax from the inbox first.

Fetches the newest fax first causing the older faxes to remain in the inbox for longer times.

Polls multiple inboxes in a round-robin manner.

Starts the poll cycle with the first user in the list and only serves the others if the first user's inbox is empty.

Security and authentication

  • Rightfax supports only basic authentication for the REST WebAPI. Refer to the API help at:

    http://rightfaxsdk.cloudapp.net/RightFaxSdk/ApiHelp/default.htm

  • For security purposes, in the production environments, an SSL certificate is installed on the IIS server and the RightFax server, and the RightFax and the RightFax connector would use the HTTPS type of connection.

  • In test environments, there may be only a self-signed SSL certificate installed on the server, and the RightFax connector may not be able to connect through HTTPS connection as it may not trust the certificate. To ignore certificate errors in test environments, do the following:

    1. Open Create_Config.xslt in a text editor. Default path

      C:\Program Files (x86)\Kofax\KIC-ED\MC\xcd

    2. Set the value of <IgnoreCertificateError> element to true as shown below. 

      <TncRFax2>
	  ...
	  <Test>
	    <IgnoreCertificateError>true</IgnoreCertificateError>
	  </Test>
	  ...
	</TncRFax2>

    3. Save and close the file.

    4. Run configure.bat.

Troubleshoot REST WebAPI connection issues

To troubleshoot REST WebAPI connection issues, use the Fiddler tool. Refer to the following link:

https://www.telerik.com/download/fiddler.

The Fiddler tool cannot log the WebAPI communication of Windows services, therefore enable this tool in the Message Connector's configuration.

  1. Open Create_Config.xslt in a text editor. Default path:

    C:\Program Files (x86)\Kofax\KIC-ED\MC\xcd

  2. Search for the following code snippet. 

    ... 
       <Proxy>
         <!-- set enabled to true only to log the webAPI traffic with fiddler  -->
         <Enabled>true</Enabled>
         <Url>http://localhost:8888</Url>
         <BypassOnLocal>true</BypassOnLocal>
       </Proxy>
       ...

  3. Change the value of <Enabled> element from false to true.
  4. Save and close the file.
  5. Run configure.bat.
  6. Save the Message Connector Configuration and restart the Message Connector service.
  7. Start Fiddler and enable the logging of traffic to the IP address of the RightFaxServer.

    In Fiddler enabled mode, Fiddler must be running for the Message Connector to work.

    Alternatively, stop the Message Connector service, and start it in the command line mode by executing the run.bat file. When running in the command line mode, Message Connector is automatically traceable by Fiddler.

    Once Fiddler running and tracing the communication between Message Connector and Rightfax server, run the functions with issues and then save the session data collected in Fiddler for further analysis.