ImageNow Message Agent

(1)

ImageNow Message Agent

Installation and Setup Guide

ImageNow Version: 6.7.x

(2)

(3)

Message Agent Over view

ImageNow Message Agent is a service that provides a window into ImageNow functionality. Message Agent exports a rich set of functions as web services enabling third-party application developers to embed ImageNow functionality, such as document management and workflow, directly into their applications. Developers can use toolkits, with standard development tools for Java, C++, or a .NET managed language to embed this functionality.

Documentation

The documentation provided with Message Agent includes online help, XML documentation, and code samples. For a high-level summary of the steps to follow in writing your own application using Message Agent, refer to the Message Agent Getting Started Guide. This document is available on the Product Documentation tab of the Customer Portal at www.perceptivesoftware.com.

Help files are located in the \inserver6\help directory. To view help, navigate to \inserver6\help, and then double-click Start_MessageAgent_Help.htm. You can also use the Perceptive Software website at

www.perceptivesoftware.com. This website always contains the most current version of the online help. The \inserver6\MessageAgent\xmldocs directory provides XML documentation, generated from XML and XSD files in Message Agent. Each web service has its own subdirectory. For example, to review the schema for imagenow_document.xsd, double-click imagenow_document.html in

\inserver6\MessageAgent\xmldocs\DOCUMENT_SERVICE.

Installation Files

The following files install with Message Agent. If you accept the default directory; files are located in \inserver6\ directories as shown below. Otherwise, files are in the directory you chose during installation.

Web Service Definition Language (WSDL) files

WSDL Description

imagenow_access.wsdl This file defines the basic authentication and authorization operations for accessing ImageNow using Message Agent.

imagenow_document.wsdl This file defines the basic document management operations for use with Message Agent.

imagenow_folder.wsdl This file defines the folder operations for use with Message Agent. imagenow_form.wsdl This file defines the form management operations for use with Message

Agent.

imagenow_license.wsdl This file defines the basic licensing operations for use with Message Agent. imagenow_services.wsdl This file consolidates the individual WSDL files into a single file to simplify the

(6)

XML schema definition (XSD) files

XSD Description

imagenow_access.xsd This file describes the access data types for imagenow_access.wsdl using XML schema structures.

imagenow_commonTypes.xsd This file describes the data types common to more than one of the WSDL files.

imagenow_document.xsd This file describes the document data types for imagenow_document.wsdl using XML schema structures.

imagenow_folder.xsd This file describes the folder data types for imagenow_folder.wsdl using XML schema structures.

imagenow_form.xsd This file describes the form data types for imagenow_form.wsdl using XML schema structures.

imagenow_license.xsd This file describes the licenses needed to interact with ImageNow for the imagenow_license.wsdl using XML schema structures.

imagenow_task.xsd This file describes the task data types for imagenow_task.wsdl using XML schema structures.

image_workflow.xsd This file describes the workflow data types for imagenow_workflow.wsdl using XML schema structures.

Licensing

Message Agent requires a licensed instance of ImageNow Server. It also requires a Message Agent Server license, and at least one Message Agent Transaction Pack license. Depending on how many web service operations you use determines how many Message Agent Transaction Packs you will need. License options include 200 transactions per hour for all operations with no concurrent user limit. Optional overdraft support is available with the MA Transaction Pack license. Note that the following operations are not counted in the transaction total:

ACCESS_SESSION_BEGIN_USING_PASSWORD ACCESS_SESSION_END

DOCUMENT_STORE DOCUMENT_STORE_SWA

Note If you plan to conduct full-text keyword queries using the DOCUMENT_SEARCH_QUERY

(7)

System Requirements

Message Agent is designed to be installed on a computer running a 32-bit Windows environment. If you plan to install Message Agent on the same server where your ImageNow Server is installed, that server must be a 32-bit Windows operating system. If your ImageNow Server is a 64-bit Windows operating system, you must install this product remotely on a 32-bit Windows operating system. You can install multiple instances of the Message Agent service.

Message Agent communicates over the network with ImageNow and third-party software using Hypertext Transfer Protocol (HTTP). The architecture supports synchronous and asynchronous communication patterns by using standard XML-SOAP message formats. Message Agent is multi-threaded, allowing the server to execute multiple client requests. For secure client-to-server communication, Message Agent supports Secure Socket Layer (SSL).

Message Agent requires a licensed instance of ImageNow Server. It also requires the Message Agent Server license, and optionally the Message Agent Transaction Pack license.

The Message Agent version you are using must be the same version as ImageNow Server. Also, note that Message Agent is not backwards-compatible with earlier versions of ImageNow.

Message Agent follows the same minimum system requirements as ImageNow Server. For product technical specifications and system requirements, refer to Product Technical Specifications for your product version. This document is available on the Product Documentation tab of the Customer Portal at

www.perceptivesoftware.com.

Install Message Agent

This document assumes you are installing ImageNow Message Agent for the first time or that you have no earlier versions running on your computer. You can update Message Agent using the procedures described in this guide, run the same steps as if you are installing a new version. The installation wizard detects the update and installs the product accordingly. Refer to ImageNow Readme for information about enhancements, and changes that might apply to this agent. This document can be found on the Perceptive Software website at www.perceptivesoftware.com. On the website, click Customer Portal, enter your user name and password, and then select the Product Documentation tab.

You can install Message Agent on the ImageNow Server computer running Windows or UNIX.

Install Message Agent on Windows

The following procedures include instructions to download, and install the Message Agent on Windows. You can install Message Agent directly on the local computer using the installation wizard, shown below as “attended.” You can also install Message Agent on Windows silently with “unattended” installations by following the instructions in the “Install Message Agent unattended” section. For UNIX environments, use the instructions in the “Install Message Agent on UNIX” section of this guide.

Download the Message Agent files for Windows

1. Go to the Perceptive Software website at www.perceptivesoftware.com, click Customer Portal, enter your user name and password, and then click Downloads.

(8)

3. Save the file to a temporary directory on your computer. 4. Unzip the installer if applicable.

Install Message Agent on Windows attended

Use the following procedures to run the Message Agent installation wizard. You must provide the server name, port number, and initial instance name of the service.

Run the installation wizard

1. Double-click the .exe file you downloaded.

2. In the Welcome to the Installation Wizard for ImageNow Message Agent page, click Next. 3. On the License Agreement page, review the terms in the License Agreement, scroll to the end of

the agreement, click I accept the terms in the license agreement, and then click Next. 4. In the Configuration Information page, complete the following sub steps:

1. Type or verify the Server Name and Port Number of the ImageNow Server computer. 2. In the Initial instance name field, accept the default label or supply a different description for

the initial instance of the Message Agent service.

Note You can enter a maximum of 40 characters. Do not include the following characters: \ / : * ? " < > |.

5. In the Destination Folder page, accept the default directory or click Browse to select an alternate directory, and then click Next.

6. In the Ready to Install the Program page, click Install.

7. Optional. If the Show the Windows Installer log check box appears, you can select the check box to view the log file.

8. When the installation finishes, in the Installation Wizard Completed page, click Finish.

9. If this is the first time you installed Message Agent or if you installed Message Agent in a different directory than the previous installation, on the ImageNow Message Agent Installer Information dialog box, click Yes to restart your computer.

10. If you installed ImageNow Message Agent on the same server as the ImageNow Server to which it connects, you can optionally create a dependency on the ImageNow Server 6.7.x service. To accomplish this, perform the following sub steps:

1. Back up your current Windows registry settings. 2. Run regedit.exe to open your registry.

3. In the Registry Editor, navigate to

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\services\ImageNow Message Agent 6.7 <instance name>.

(9)

5. Right-click on the new DependOnService key to modify it, and supply the instance name of the initial instance of the service:

ImageNow Server 6.7 <instance name>

Note Use the same instance name that you specified in the Configuration Information page during installation.

6. Click OK, close the registry editor, and then restart your computer for the changes to take effect.

Install Message Agent on Windows unattended

Installing Message Agent silently is an automatic way to run an installation. If you follow the procedures below, you do not install Message Agent using a standard InstallShield Wizard. Using this silent

installation method, you can do a custom installation or use a combination of default and customized settings. Note that using an unattended installation skips the license agreement portion of the installation.

Run the unattended installation using argument values

1. Set up your script variables and argument values to customize the unattended installation. If you do not use arguments, the installation uses the default values for the missing arguments. If you use environment variables to set the arguments, be sure to set all of your environment variables.

Variables Arguments Description Default Example

LOGFILE /L*V If you use this

argument, setup does not create directories so the path for the log file generation must be a valid, existing path. Use escaped

quotation marks when setting this argument.

If the command line argument is removed, it defaults to the %TEMP% directory in a file named MessageAgentInst all.log. Environment Variable: set LOGFILE=C:\logs\messa ge_agent-install.txt Command line: /L*V \”C:\logs\message_agen t-install.txt\”

INSTALLDIR_VAL INSTALLDIR The default, and recommended, installation directory is [drive:]\inserver6. Use escaped

quotation marks when setting this argument.

[drive:]\inserver6 Environment Variable: set INSTALLDIR_VAL= C:\inserver6 Command line: INSTALLDIR=\”C:\inserv er6\” PORTNUMBER_VA

L PORTNUMBER The port for ImageNow Server. 6000 Environment Variable: set PORTNUMBER_ VAL =7000

Command line: PORTNUMBER=7000 SERVERNAME_VA

(10)

Variables Arguments Description Default Example

Command line:

SERVERNAME=127.0.0. 1

INSTANCE_NAME

_VAL INSTANCE_NAME Name of the primary instance Primary Script Variable: set INSTANCE_NAME_VAL= Primary Command line: INSTANCE_NAME=Prim ary

2. Open a window that accepts command prompts, and type the following command: MessageAgentSetup.exe /s /V“/qb <argument list>”

Note You can create a batch file or script containing this command for use with your deployment software.

The following example shows the syntax using defined environment variables:

MessaqeAgentSetup.exe /s /V"/qb /L*V \"%LOGFILE%\" INSTALLDIR=\"%INSTALLDIR_VAL%\" PORTNUMBER=\"%PORTNUMBER_VAL%\" SERVERNAME=\"%SERVERNAME_VAL%\"

INSTANCE_NAME=\"%INSTANCE_NAME_VAL%\"

The following example shows the syntax using command line variables and arguments: MessageAgentSetup.exe /s /V”/qb /L*V \"C:\logs\message_agent-install.txt\" INSTALLDIR=\”C:\inserver6\” PORTNUMBER=7000 SERVERNAME=127.0.0.1

INSTANCE_NAME=Primary

Install Message Agent on UNIX

Message Agent builds are available for AIX, Linux, and Oracle Solaris. There might be slight differences in these steps based on your environment.

Download the Message Agent files for UNIX

1. Go to the Perceptive Software website at www.perceptivesoftware.com, click Customer Portal, enter your user name and password, and then click Downloads.

2. In the Downloads page, download the following file to a temporary directory on your computer: • The UNIX product installer

Install Message Agent files on a UNIX server

1. Access a command prompt with root permissions.

2. Make a directory on your UNIX server titled inserver6 where you would like to install the product. 3. Copy the ImageNow_MessageAgent_6.7.0_<build>_for_<platform>.tar.gz file to the new

directory, and then type the following command:

(11)

4. To extract files and sub-directories for Message Agent, type the following command: tar –xvf ImageNow_MessageAgent_6.7.0_<build>_for_<platform>.tar

5. To verify the Message Agent installation status, refer to the “Verify Message Agent status on a UNIX server” section of this guide.

Verify Message Agent installation

You can verify whether the Message Agent is correctly installed by checking your services. If Message Agent is running as a service, it is installed correctly. Use one of the following methods to verify that Message Agent is running. Use the method that works best for you, depending on your platform and operating system.

Verify Message Agent status at the Windows command prompt

1. Open a window that accepts command prompts.

2. Navigate to the directory that contains the inserverMA.exe file by entering the following command: cd \inserver6\bin

3. Enter the following command:

inserverMA –status (<instance name> optional)

4. If Message Agent is running, the Service Up message appears. If Message Agent is not running, the Service Down message appears.

Note If you need to start the Message Agent service, enter inserverMA –start.

Verify Message Agent status using Windows Computer Management

1. On your Windows Desktop, right-click the My Computer icon, and then click Manage. 2. In the Computer Management dialog box, in the left pane, click Services and Applications. 3. Click Services.

4. In the right pane, locate the service titled ImageNow Message Agent 6.7 <instance name>. To the right of this item, the Status column displays Started or Stopped.

Note If you need to stop or restart the Message Agent service, right-click on the service name, then select Stop or Restart.

Verify Message Agent status on a UNIX server

1. Navigate to the /inserver6/bin directory, and then execute the following command: ./inserverMA –status <instance name>

2. To start or stop the Message Agent service execute the following command:

./inserverMA –start <instance name> or ./inserverMA –stop <instance name>

Verify Message Agent status using an internet browser

(12)

default port is 6070. For more information on changing the port setting, refer to “Server port settings” section of this guide.

2. Wait for the web page to load. If Message Agent is running, the web service endpoints published by Message Agent appear as shown in the following figure:

Configure Message Agent

There are several areas of configuration within Message Agent: command line options, inserverMA.ini settings, HTTP and HTTPS server port settings, and SSL protocol configuration.

Command line options

You can use the command line options to obtain information about the Message Agent instance. For example, you can display the name, description, company, version, and status of your instance.

Additionally, you can use a command line prompt to install and uninstall the Message Agent service, and start and stop the service. To view a complete list of command line options, use the following steps: 1. Open a window that accepts command prompts.

2. Navigate to the \inserver6\bin directory and enter the following command: inserverMA –help

(13)

Customize inserverMA.ini settings

You can use the settings in the inserverMA.ini file to customize how Message Agent works. In most cases, you need to modify only the IP address and port for the ImageNow Server. Message Agent communicates with the ImageNow Server using these settings.

The settings you can change include the SOAP server retries, audit user refresh, logging setting to determine the verboseness level and remote settings such as socket login and default timeout values. For a complete list of inserverMA.ini parameters, refer to “Appendix: inserverMA.ini options” section of this guide.

1. Launch a text editor, and then open this file: \inserver6\etc\inserverMA.ini

2. In the [General] section, change the settings as needed.

• To change the value for the number of retries that occur after the application server or SOAP server does not start, for number.of.soap.start.retry, provide a number from 1 to 5, where 5 is the default value.

• To change the number of minutes for the interval between audit user refreshes, change the audit.user.refresh.interval setting, where 10 is the default value.

3. In the [Remote] section, change the settings as needed.

• To change the IP address and IP port value for the ImageNow Server that Message Agent is to connect with, modify the server.ip.address and server.ip.port settings. Message Agent is initially configured to work with an ImageNow Server on the same computer <localhost> listening on port 6000.

• To change the values for time intervals and time outs, modify the socket.login.timeout and socket.default.timeout settings.

• Do not change the remoted=TRUE setting. 4. Save and close the inserverMA file.

5. Restart the inserverMA service for the changes to take effect.

Server port settings

You can change the HTTP and HTTPS server ports if you want to use a port other than the default port.

Change the HTTP server port

The default HTTP server port for Message Agent is 6070. 1. Launch a text editor, and then open this file:

\inserver6\MessageAgent\server\conf\http-server.xml

2. Change the value for hts:port="6070" to the new value you want to use. 3. Save and close the http-server.xml file.

(14)

Change the HTTPS server port

The default HTTPS server port for Message Agent is 6075. 1. Launch a text editor, and then open this file:

\inserver6\MessageAgent\server\conf\openssl-server.xml 2. Change the value for hts:port="6075" to the new value you want to use. 3. Save and close the openssl-server.xml file.

4. Restart the inserverMA service for the changes to take effect.

SSL Protocol

Use these procedures to enable encrypting information used by Message Agent with SSL on Windows 32, and Linux environments.

Enable SSL

1. Launch a text editor, and then open this file:

\inserver6\MessageAgent\server\conf\security-core.xml 2. Uncomment the openssl line as follows:

<wasp:import ref="openssl-core.xml"/> 3. Save and close the security-core.xml file. 4. Open this file:

\inserver6\MessageAgent\server\config.xml 5. Uncomment the following line as follows:

<wasp:import ref='conf/openssl-server.xml'/> 6. Comment the following line as follows:

Note Commenting this line out means that Message Agent will no longer support non-SSL messages over plain HTTP.

7. Save and close the config.xml file.

8. On the server computer, restart the Message Agent inserverMA service for the updated configurations to take effect.

Disable SSL

\inserver6\MessageAgent\server\conf\security-core.xml 2. Comment the openssl line as follows:

(15)

4. Open this file:

\inserver6\MessageAgent\server\config.xml 5. Comment out this line as follows:

6. Uncomment the following line as follows:

<wasp:import ref='conf/http-server.xml'/> 7. Save and close the config.xml file.

Generate a Self-Signed Digital Certificate for SSL testing

The test certificate you generate using the following steps is intended for testing purposes only. For production use, use the procedures included to generate a Certificate Signing Request (CSR) for a valid Certificate Signing Authority.

2. Navigate to the \inserver6\MessageAgent\server\bin directory, and type the following command to execute the program to generate a self-signed certificate:

generateOpenSSLServerCert.bat

3. If successful, the server certificate appears within the \inserver6\MessageAgent\server\openssl\certs directory.

4. Import the generated certificate from \inserver6\MessageAgent\server\openssl\certs directory into your business application to initialize SSL communications.

Generate a Certificate Signing Request (CSR) for a Certificate Authority

This procedure generates a CSR for use by a Certificate Signing Authority, such as VeriTest, to generate a valid production-level SSL certificate.

2. Navigate to the \inserver6\MessageAgent\server\bin, and type the following command to execute the program to begin the CSR generation process:

generateCertificateRequest.bat

3. The utility requests several data points in order to properly create the RSA private key and certificate request. Provide answers to each of these questions, including the private key password, company name, department, and Message Agent URL.

Upon completion, the utility provides notification of success or failure of the CSR generation. If successful, the following files appear within the \inserver6\MessageAgent\server\openssl directory. Note that <DOMAIN_NAME> is the domain name provided in one of the requested data points during the previous step.

(16)

4. Save the KEY file to a secure location for future reference. Make note of the password provided in the previous steps, as the password is required to decrypt this private key if required in the future. 5. After the SSL certificate is generated and received from the Certificate Authority, update the

ssl:certificateFile=, ssl:privateKeyFile=, and ssl:privateKeyPaswordFile= settings in the

configuration file (openssl-server.xml) so that they reference the certificate file. Refer to “Enable SSL” section of this guide.

Configure WS-Security

The initial security layer for authentication of web service requests is Web Services Security (WSS). You need to enable this security layer in addition to configuring user privileges within ImageNow.

The WSS: SOAP Message Security specification describes how a web service consumer can supply a UsernameToken as a means of identifying the requestor by “username”, and optionally using a password to authenticate that identity to the webservice producer. The <wsse:UsernameToken> element is a way of providing a username within the WSS: SOAP Message Security document. In the request, the header of the digest is as follows:

<SOAP-ENV:Header> <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" SOAP-ENV:mustUnderstand="1"> <wsse:UsernameToken><wsse:Username>test1</wsse:Username> <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordDigest">G93OORMY7BQiQy5ZUX4MqYUxvag=</wsse:Password> <wsse:Nonce>Rt6FK8d15ET9oth+Zdomzg==</wsse:Nonce> <wsu:Created>2012-04-16T16:17:53Z</wsu:Created></wsse:UsernameToken></wsse:Security></SOAP-ENV:Header> For PLAINTEXT the header is as follows:

<SOAP-ENV:Header> <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" SOAP-ENV:mustUnderstand="1"> <wsse:UsernameToken><wsse:Username>test1</wsse:Username> <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">ImageNow!</wsse:Password> <wsse:Nonce>iFhDppMYMWYKcYL7Ia2oPg==</wsse:Nonce> <wsu:Created>2012-04-16T16:19:51Z</wsu:Created></wsse:UsernameToken></wsse:Security></SOAP-ENV:Header> Note WS-Security using PasswordDigest will not work unless SSL is enabled. To enable SSL, refer to the “Managing WS-Security” section of this guide.

(17)

Managing WS-Security

Use these procedures to enable or disable the WS-Security UsernameToken functionality on a service endpoint basis in Windows 32, and Linux environments.

Enable WS-Security

\inserver6\MessageAgent\server\conf\security-core.xml 2. Uncomment this line as follows:

<wasp:import ref="wssecurity.xml"/> 3. Save and close the security-core.xml file.

4. Navigate to the \inserver6\MessageAgent\server directory. Open the configuration file for the service endpoint that you want to enable:

• access_endpoints.xml • document_endpoints.xml • folder_endpoints.xml • form_endpoints.xml • task_endpoints.xml • workflow_endpoints.xml

5. Uncomment the WSSecurityInterceptor entry found in the .xml as follows: <trans:interceptor>WSSecurityInterceptor</trans:interceptor> <wasp:securityProviderPreferences xmlns="urn:WSSecurity"xmlns:wss="urn:WSSecurity"wasp:name="WSSecurity"> <receptionPolicy> <usernameTokenPolicy wss:acceptWithoutNonceAndCreated="false"/> </receptionPolicy> </wasp:securityProviderPreferences> 6. Save and close the .xml file.

7. On the server computer, restart the Message Agent inserverMA service for the updated configuration to take effect.

Disable WS-Security

\inserver6\MessageAgent\server\conf\security-core.xml 2. Comment this line as follows:

(18)

4. Navigate to the \inserver6\MessageAgent\server directory. Open the configuration file for the service endpoint that you want to enable:

• access_endpoints.xml • document_endpoints.xml • folder_endpoints.xml • forms_endpoints.xml • task_endpoints.xml • workflow_endpoints.xml

5. Comment the WS-Security entry found in the .xml as follows:

6. Save and close the .xml file.

Note If the line in the security-core.xml file is commented out, none of the endpoint configuration files take effect. With the line active, you can disable some of the endpoints on an as-needed basis by changing each individual .xml file as shown in “Enable WS-Security” section of this guide.

Managing username tokens

Add username tokens to UserStore

2. Navigate to \inserver6\MessageAgent\server\bin, and execute the following command, replacing <USERNAME> and <PASSWORD> with a valid login name and password.

userstoretool --file ..\userstore\userstore.xml –a <USERNAME> -p USER_PASSWORD –v <PASSWORD>

3. Verify that the command line returns no errors.

Verify users in the UserStore

(19)

Remove a user from the UserStore

2. Navigate to \inserver6\MessageAgent\server\bin, and execute the following command, replacing <USERNAME> with a valid login name you intend to remove from the UserStore.

userstoretool --file ..\userstore\userstore.xml --rem <USERNAME> 3. Verify that the command line returns no errors.

Test Message Agent

Message Agent functionality can be tested by using a third-party utility like soapUI. SoapUI is a free, open source desktop application for testing web services over HTTP. For more information on soapUI, reference http://www.soapui.org.

You can send a request using the ACCESS_SESSION_BEGIN_USING_PASSWORD operation and retrieve a session string id from soapUI. Receiving a session string id indicates a successful test of Message Agent. To perform the test, use the following steps:

1. Download, and install soapUI according to the manufacturer instructions. 2. Start soapUI, and then on the File menu, click New soapUI Project.

3. In the New soapUI Project dialog box, enter a Project Name, and then click Browse. 4. Navigate to the directory where the WSDL files are installed. By default, the location is

\inserver6\MessageAgent\server.

5. Select the imagenow_services.wsdl file, click Open, and then click OK.

6. In the left Navigator pane, expand ACCESS_SESSION_BEGIN_USING_PASSWORD, and then double click Request 1.

7. In the right pane, in the Request tab, fill out the needed parameters:

• Replace the question mark with a internationalization or a browser location value in the LOCALE parameter:

<ser1:LOCALE>?</ser1:LOCALE>

• Replace the question mark with your user name in the INOW_USER_NAME parameter: <ser1:INOW_USER_NAME>?</ser1:INOW_USER_NAME>

• Replace the question mark with your password in the PASSWORD parameter: <ser1:PASSWORD>?</ser1:PASSWORD>

• Replace the question mark with the type of user in the APP_CONTEXT parameter: <ser1:APP_CONTEXT>?</ser1:APP_CONTEXT>

Note The APP_CONTEXT parameter identifies the type of user as follows: bridge user = 1, audit user = 11, and individual users as any number other than 1 or 11.

(20)

8. To submit your request, in the Request 1 dialog box, click the Submit request to specified endpoint URL button.

Note The Message Agent service must be running for the test to complete.

9. In the Response tab, copy the session id value, and paste it into the next call you will run in your business application. The following is an example of a session string containing a session id value, <s1:SESSION_STRING><301YV3N_)))1E49X1000004></s1:SESSION_STRING>. The actual session id is a unique value specific to your environment.

Log Files

Once you test Message Agent to ensure a session id is successfully returned, you can utilize the content of various log files generated from Message Agent. Additionally, Interceptor Logging may be a useful tool to troubleshoot issues with SOAP requests and responses.

Message Agent Logging

A variety of log files and logging levels can assist you with troubleshooting issues with using Message Agent. You can use these log files while coding Message Agent operations into your own application and when interpreting issues encountered when running and using Message Agent.

Configure a log file

1. Launch a text editor, and then open this file: \inserver6\etc\inserverMA.ini

2. In the [Logging] section, change the settings as needed.

• To change the verbosity level for DEBUG logging, change the debug.level.file setting to a number from 0 to 2, where 0 is no debugging, 1 is main logic logging, and 2 is database information logging.

• To change the verbosity level for SOCKET logging, change the socket.level.file setting to a number from 0 to 3, where 0 is no logging, 1 is summary mode, 2 is all socket transactions, and 3 is every socket transaction (including SERV_SYNC).

3. Optional. You can set DEBUG and SOCKET logging for individual users. Uncomment this line as follows, and place the user name at the beginning of the line:

<<user_name2>>.debug.level.file=0 <<user_name2>>.socket.level.file=0 4. Save and close the inserverMA.ini file.

5. On the server computer, restart the Message Agent inserverMA service for the update configuration to take effect.

Notes

• You add one line per user name, and you may list as many users as you require. For example: jsmith.debug.level.file=2

wjones.debug.level.file=2

(21)

• inserverMA_<instance name>_<date>.log is created by Message Agent. The inserverMA.ini file controls this log.

• message.agent_<instance name>_<date>.log is created by ImageNow for each Message Agent connecting. The inserver.ini file controls this log.

• User logs are created by ImageNow Server for each user that logs through a web service: Message Agent, ImageNow Client, or WebNow.

Warning Setting the verbosity level to 3 results in large log files. Leaving the verbosity level at 3 for an extended period of time can create massive log files that occupy significant disk space.

Interceptor Logging

You can enable Interceptor Logging for all Message Agent web services using the corresponding endpoint on a per-endpoint basis. The logging files produced by the Interceptor are useful for troubleshooting issues with SOAP requests and responses.

Warning Leaving this setting enabled for extended periods of time can slow performance and generate a large amount of log files.

Enable Interceptor logging

\inserver6\MessageAgent\server\config.xml 2. Uncomment this line as follows:

<wasp:import ref='inserverMAInterceptor.xml'/> 3. Save and close the config.xml file.

4. In the same directory, open the inserverMAInterceptor.xml file. 5. Uncomment this line as follows:

<intr:interceptor xmlns:intr="urn:InterceptorRepository"

xmlns:logint="urn:LoggingInterceptor" intr:class="WASP_LoggingInterceptor" intr:name="LoggingInterceptor" logint:logDir="c:\inserver6\log"/>

6. Optional. You can modify the <logDir> value to change the location of the output log files the Interceptor generates. The default directory is ”c:\inserver6\log”.

7. Save and close the inserverMAInterceptor.xml file.

8. Open the endpoint-specific file or files that correspond with the operations you want to log all SOAP/XML request and response messages. The list of endpoints are shown below:

• access_endpoints.xml • document_endpoints.xml • folder_endpoints.xml • form_endpoints.xml • task_endpoints.xml • workflow_endpoints.xml

(22)

<trans:interceptor>LoggingInterceptor</trans:interceptor> 10. Save and close the endpoint-specific file.

11. On the server computer, restart the Message Agent inserverMA service for the updated configuration to take effect.

Note All requests that you submit to any previously enabled endpoints have their SOAP request and response logged in separate text files. These files are named debugXXXIn.txt and debugXXXOut.txt (where XXX represents the sequence number of the request and response). The files reside in the logDir directory <path>, as specified in the inserverMAInterceptor.xml file.

Disable Interceptor logging

1. Launch a text editor, and then open the endpoint-specific file or files that correspond with the operations for which you want to stop logging all SOAP/XML request and response messages. 2. In each file that you open, comment out the following line and then save, and close the

endpoint-specific file as follows:

3. On the server computer, restart the Message Agent inserverMA service for the updated

configuration to take effect.

Troubleshoot Message Agent

This section provides answers to some of the common questions, and scenarios that may occur when using Message Agent.

Question Answer

Message Agent isn't running. How do I start Message Agent?

Depending on your platform and operating system, you can start Message Agent in several ways. Refer to the "Verify Message Agent installation" section of this guide.

The Message Agent service appears to be down or not responding to my requests, what should I check?

Make sure that Message Agent is running. You can do this by following the steps in the "Verify Message Agent installation" section of this guide.

Furthermore, ImageNow Server must be running and responding to requests. You must be able to access ImageNow Server from the location where Message Agent is installed and running. Make sure it is running and that you can log in using a client of ImageNow such as ImageNow Client or WebNow before using Message Agent. Why isn't Message Agent creating my

client proxy code stubs?

(23)

Question Answer

Why aren't Message Agent web services showing up when I specify a URL or path to add them to my development tool?

Make sure that you are specifying the correct URL or path when you reference the Message Agent services. Note the default server name and port are shown in the following examples.

Access Service Endpoint

http://localhost:6070/imagenow/services/1.0/access_service/WSDL Document Service Endpoint

http://localhost:6070/imagenow/services/1.0/document_service/WSDL Form Service Endpoint

http://localhost:6070/imagenow/services/1.0/form_service/WSDL Folder Service Endpoint

http://localhost:6070/imagenow/services/1.0/folder_service/WSDL Task Service Endpoint

http://localhost:6070/imagenow/services/1.0/task_service/WSDL Workflow Service Endpoint

http://localhost:6070/imagenow/services/1.0/workflow_service/WSDL You can also access the WSDL files directly in the

\inserver6\MessageAgent\wsdl directory on the server computer. One or more elements or data types are

missing from the client proxy code stubs I generated. Where are they?

Message Agent follows the web services standards recommended in the WS-I Basic Profile, and you must add each of the services (Access, Document, Form, Folder, Task and Workflow) to your development kit to make them available to your development tool and to generate the complete set of classes or objects your tool requires. Some web service toolkits may not support certain complex data types without additional coding. For more information, refer to the documentation that came with your toolkit.

Why is the request I am sending through

Message Agent failing? When you send requests to Message Agent, it responds with either success or failure. You know the operation succeeded if your client application receives an object response. Failure is indicated when Message Agent sends an error fault to your client application. For a complete list of error codes, operation IDs, and error messages you may encounter when using Message Agent, refer to the Message Agent Getting Started Guide. This document is available on the Perceptive Software website at www.perceptivesoftware.com. On the website, click Customer Portal, enter your user name and password, and then select the Product Documentation tab.

Is there a limit to the file sizes used by

(24)

Question Answer

How do I view Message Agent log files to

help resolve errors? The \inserver6\log directory contains all logs for Message Agent for each day. For more information on log settings, refer to the "Log Files" section of this guide. There are three log files for Message Agent. • inserverMA_<instance name>_<date>.log is created by

Message Agent. The inserverMA.ini file controls this log. • message.agent_<instance name>_<date>.log is created by

ImageNow for each Message Agent that is connected. The inserver.ini file controls this log.

• User logs are created by ImageNow Server for each user that logs through a web service: Message Agent, ImageNow Client, or WebNow.

How can I spy on the SOAP/XML messages?

Many development companies provide tools for sniffing or spying on SOAP request and response messages between your client

application and Message Agent.

(25)

Appendix A: inser verMA.ini settings

The following table provides definitions and sample data for the settings in the inserverMA.ini configuration file. This table displays the settings in the order the groups appear in the INI file. Each group has a description of each setting and its options. Use this table as a reference when customizing Message Agent.

Group Setting Options Description

General number.of.soap.start.retry Any positive integer.

Specifies the number of attempts Message Agent makes to start the application server or SOAP server before it fails the Message Agent server. The default is 5. audit.user.refresh interval Any positive integer.

Specifies the interval in minutes Message Agent performs an audit user refresh. The default is 10.

remove.old.server 0 The default to 0 (or FALSE).

Remote remoted TRUE The default is TRUE.

server.ip.address Any valid IP address or a semicolon delimited string of valid IP addresses.

Specifies the IP address of ImageNow Server. You can supply multiple IP addresses with a semicolon delimited string. For example:

123.12.123.10;234.23.234.2;345.34.345.3. The default is 127.0.0.1.

server.ip.port Any valid

port. Specifies the Message Agent port number. The default is 6000.

socket.login.timeout Any positive integer.

Specifies how many seconds Message Agent waits for successful login before terminating the connection.

The default is 60. socket.default.timeout Any

positive integer.

Specifies how many seconds Message Agent waits for APIs.

(26)

Logging refresh.mode 0

1 2

Specifies how often ImageNow Server re-reads log, debug, and audit settings. 0 = never

1 = At every heartbeat 2 = At every server call The default is 0.

debug.level.file 0 - 3 Specifies the level Message Agent uses to log errors for troubleshooting.

Typically, you want to set minimal logging unless you are debugging an issue. If you increase the logging, make sure that you set the logging level back down after you finish debugging. Failure to do so can greatly affect performance and hard disk space.

0 = Logging is off.

1 through 3 = Logging is on. The higher the number, the more verbose logging. For example, 1 offers minimal logging, whereas 3 offers the most information.

The default is 0.

Tip You can specify unique values for specific users by placing the user name at the beginning of the string. For example, to set logging to 2 for user jsmith, create a string that states: jsmith.debug.level.file = 2. Logging (continued) socket.level.file 0 1 2 3

Specifies how Message Agent logs socket communication.

0 = Message Agent does not log communication.

1 = Message Agent logs only function names. 2 = Message Agent logs all socket

transactions.

3 = Message Agent logs all socket transactions including SERV_SYNC. The default is 0.

(27)

Output output.downscale.color.mode 0 1 2

Specifies the color mode Message Agent uses for output.

0 = Message Agent uses the value in the DOC_OUTPUT_FORMAT element that is set when you call an operation. All documents are saved as either a compressed TIFF file or a compressed PDF file without forcing downscale.

1 = Black and white halftone. All documents are saved as G4 compression.

2 = Black and white diffuse. All documents are saved as G4 compression.

The default is 0. output.diffuse.black level.threshold Any integer between 0 and 255.

Specifies the threshold at which a given color is determined to be black or white.

The default is 128.

(28)

Index

audit.user.refresh.interval... 13, 25

complex data types ... 23

debug.level.file ... 26 debugging ... 20 documentation help ... 5 XML schema ... 5 endpoints web service... 12 HTTP server port ... 13 HTTPS server port ... 14 inserverMA.ini ... 25

installing Message Agent on UNIX ... 10 on Windows ... 7 interceptor ... 21 license product ... 7 transaction pack ... 7 licensing ... 6 transaction pack ... 6 log files ... 20 logging levels ... 20 number.of.soap.start.retry ... 13, 25 output ... 27 level.threshold ... 27 output.diffuse.black ... 27 output.downscale.color.mode ... 27 refresh.mode ... 26 remoted ... 13, 25 server port settings ... 13

server.ip.address ... 13, 25 server.ip.port ... 13, 25 socket.default.timeout ... 13, 25 socket.level.file ... 26 socket.login.timeout ... 13, 25 SSL ... 14, 15 digital certificate ... 15 disable ... 14 enable ... 14 system requirements ... 7 troubleshooting ... 21 URL ... 23 verify installation ... 11 internet browser ... 11 UNIX ... 11 Windows ... 11

web service endpoints ... 12

WSDL files ... 5

WS-I Basic Profile ... 23

WS-security ... 17

disable ... 17

enable ... 17

userstore ... 18

ImageNow Message Agent