ImageNow Message Agent

Transcription

1 ImageNow Message Agent Installation and Setup Guide ImageNow Version: 6.7.x Written by: Product Documentation, R&D Date: November 2013

2 2012 Perceptive Software. All rights reserved CaptureNow, ImageNow, Interact, and WebNow are trademarks of Lexmark International Technology SA, registered in the U.S. and other countries. Perceptive Software is a stand-alone business unit within Lexmark International Technology SA. All other brands and product names mentioned in this document are trademarks or registered trademarks of their respective owners. No part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, electronic, mechanical, photocopying, recording, or any other media embodiments now known or hereafter to become known, without the prior written permission of Perceptive Software.

3 Table of Contents Message Agent Overview... 5 Documentation... 5 Installation Files... 5 Web Service Definition Language (WSDL) files... 5 XML schema definition (XSD) files... 6 Licensing... 6 System Requirements... 7 Install Message Agent... 7 Install Message Agent on Windows... 7 Download the Message Agent files for Windows... 7 Install Message Agent on Windows attended... 8 Install Message Agent on Windows unattended... 9 Install Message Agent on UNIX Download the Message Agent files for UNIX Install Message Agent files on a UNIX server Verify Message Agent installation Verify Message Agent status at the Windows command prompt Verify Message Agent status using Windows Computer Management Verify Message Agent status on a UNIX server Verify Message Agent status using an internet browser Configure Message Agent Command line options Customize inserverma.ini settings Server port settings Change the HTTP server port Change the HTTPS server port SSL Protocol Enable SSL Disable SSL Configure WS-Security Managing WS-Security Enable WS-Security Disable WS-Security ImageNow Message Agent Installation and Setup Guide Page 3 of 28

4 Managing username tokens Add username tokens to UserStore Verify users in the UserStore Remove a user from the UserStore Test Message Agent Log Files Message Agent Logging Configure a log file Interceptor Logging Enable Interceptor logging Disable Interceptor logging Troubleshoot Message Agent Appendix A: inserverma.ini settings Index ImageNow Message Agent Installation and Setup Guide Page 4 of 28

5 Message Agent Overview 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 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 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 imagenow_access.wsdl imagenow_document.wsdl imagenow_folder.wsdl imagenow_form.wsdl imagenow_license.wsdl imagenow_services.wsdl imagenow_task.wsdl imagenow_workflow.wsdl Description This file defines the basic authentication and authorization operations for accessing ImageNow using Message Agent. This file defines the basic document management operations for use with Message Agent. This file defines the folder operations for use with Message Agent. This file defines the form management operations for use with Message Agent. This file defines the basic licensing operations for use with Message Agent. This file consolidates the individual WSDL files into a single file to simplify the process of creating client stubs for all the services at the same time. This file defines the task operations for use with Message Agent. This file defines the workflow operations for use with Message Agent. ImageNow Message Agent Installation and Setup Guide Page 5 of 28

6 XML schema definition (XSD) files XSD imagenow_access.xsd imagenow_commontypes.xsd imagenow_document.xsd imagenow_folder.xsd imagenow_form.xsd imagenow_license.xsd imagenow_task.xsd image_workflow.xsd Description This file describes the access data types for imagenow_access.wsdl using XML schema structures. This file describes the data types common to more than one of the WSDL files. This file describes the document data types for imagenow_document.wsdl using XML schema structures. This file describes the folder data types for imagenow_folder.wsdl using XML schema structures. This file describes the form data types for imagenow_form.wsdl using XML schema structures. This file describes the licenses needed to interact with ImageNow for the imagenow_license.wsdl using XML schema structures. This file describes the task data types for imagenow_task.wsdl using XML schema structures. 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 operations return object DOCUMENT_OBJECT, a valid ImageNow Content Server license is required. Using this operation for full-text keyword searches, ImageNow Content Server collects text data and creates searchable indexes based on the content of each document page. ImageNow Message Agent Installation and Setup Guide Page 6 of 28

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 multithreaded, 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 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 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 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 Windows product installer ImageNow Message Agent Installation and Setup Guide Page 7 of 28

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>. 4. In the Registry Editor, right-click in the right pane of the registry editor, click New, click Multi- String Value, and then name the key DependOnService. ImageNow Message Agent Installation and Setup Guide Page 8 of 28

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. INSTALLDIR_VAL INSTALLDIR The default, and recommended, installation directory is [drive:]\inserver6. 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. [drive:]\inserver6 Environment Variable: set LOGFILE=C:\logs\messa ge_agent-install.txt Command line: /L*V \ C:\logs\message_agen t-install.txt\ Environment Variable: set INSTALLDIR_VAL= C:\inserver6 Command line: INSTALLDIR=\ C:\inserv er6\ PORTNUMBER_VA L PORTNUMBER The port for ImageNow Server Environment Variable: set PORTNUMBER_ VAL =7000 Command line: PORTNUMBER=7000 SERVERNAME_VA L SERVERNAME The location of ImageNow Server Environment Variable: set SERVERNAME_ VAL = localhost ImageNow Message Agent Installation and Setup Guide Page 9 of 28

10 Variables Arguments Description Default Example Command line: SERVERNAME= INSTANCE_NAME _VAL INSTANCE_NA ME 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= 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 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: gzip d ImageNow_MessageAgent_6.7.0_<build>_for_<platform>.tar.gz ImageNow Message Agent Installation and Setup Guide Page 10 of 28

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 1. In a web browser Address box, enter If Message Agent is installed on the same computer as ImageNow Server, you can use localhost for the servername. The ImageNow Message Agent Installation and Setup Guide Page 11 of 28

12 default port is 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 3. The command line options for use with the inserverma service appear. Use the commands you need. ImageNow Message Agent Installation and Setup Guide Page 12 of 28

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 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 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. 4. Restart the inserverma service for the changes to take effect. ImageNow Message Agent Installation and Setup Guide Page 13 of 28

14 Change the HTTPS server port The default HTTPS server port for Message Agent is 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: <!--<wasp:import ref='conf/http-server.xml'/>--> 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 1. Launch a text editor, and then open this file: \inserver6\messageagent\server\conf\security-core.xml 2. Comment the openssl line as follows: <!--<wasp:import ref="openssl-core.xml"/>--> 3. Save and close the security-core.xml file. ImageNow Message Agent Installation and Setup Guide Page 14 of 28

15 4. Open this file: \inserver6\messageagent\server\config.xml 5. Comment out this line as follows: <!--<wasp:import ref='conf/openssl-server.xml'/>--> 6. Uncomment the following line as follows: <wasp:import ref='conf/http-server.xml'/> 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. 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. 1. Open a window that accepts command prompts. 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. 1. Open a window that accepts command prompts. 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. <DOMAIN_NAME>.csr <DOMAIN_NAME>.key ImageNow Message Agent Installation and Setup Guide Page 15 of 28

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=" xmlns:wsu=" wss-wssecurity-utility-1.0.xsd" SOAP-ENV:mustUnderstand="1"> <wsse:usernametoken><wsse:username>test1</wsse:username> <wsse:password Type=" <wsse:nonce>rt6fk8d15et9oth+zdomzg==</wsse:nonce> <wsu:created> T16: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=" xmlns:wsu=" wss-wssecurity-utility-1.0.xsd" SOAP-ENV:mustUnderstand="1"> <wsse:usernametoken><wsse:username>test1</wsse:username> <wsse:password Type=" <wsse:nonce>ifhdppmymwykcyl7ia2opg==</wsse:nonce> <wsu:created> T16: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. For more information on the WS-Security specifications, refer to the following web page: Important These procedures are supported only on Windows 32-bit, and Linux environments when running ImageNow Message Agent version 6.5 or higher. ImageNow Message Agent Installation and Setup Guide Page 16 of 28

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 1. Launch a text editor, and then open this file: \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 1. Launch a text editor, and then open this file: \inserver6\messageagent\server\conf\security-core.xml 2. Comment this line as follows: <!--<wasp:import ref="wssecurity.xml"/>--> 3. Save, and then close the security-core.xml file. ImageNow Message Agent Installation and Setup Guide Page 17 of 28

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: <!--<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 configurations to take effect. 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 1. Open a window that accepts command prompts. 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 1. Open a window that accepts command prompts. 2. Navigate to the \inserver6\messageagent\server\bin, and execute the following command: userstoretool --file..\userstore\userstore.xml --list ImageNow Message Agent Installation and Setup Guide Page 18 of 28

19 Remove a user from the UserStore 1. Open a window that accepts command prompts. 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 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 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. The remaining parameter settings are optional. ImageNow Message Agent Installation and Setup Guide Page 19 of 28

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_)))1e49x ></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 Message Agent saves log files in the \inserver6\log directory. Reference the following log files when debugging issues: ImageNow Message Agent Installation and Setup Guide Page 20 of 28

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 1. Launch a text editor, and then open this file: \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 9. In each endpoint file where you want to enable interceptor logging, uncomment this line as follows: ImageNow Message Agent Installation and Setup Guide Page 21 of 28

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 endpointspecific file as follows: <!--<trans:interceptor>logginginterceptor</trans:interceptor>--> 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 Message Agent isn't running. How do I start Message Agent? Answer 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? Why isn't Message Agent creating my client proxy code stubs? 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. Remember that Message Agent doesn't create the client proxy code stubs. You create client proxy code stubs using your development tool. Follow the directions in your development tool to generate client proxy code stubs using Message Agent WSDL files. ImageNow Message Agent Installation and Setup Guide Page 22 of 28

23 Question Why aren't Message Agent web services showing up when I specify a URL or path to add them to my development tool? One or more elements or data types are missing from the client proxy code stubs I generated. Where are they? Why is the request I am sending through Message Agent failing? Is there a limit to the file sizes used by Message Agent? Answer 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 Document Service Endpoint Form Service Endpoint Folder Service Endpoint Task Service Endpoint Workflow Service Endpoint You can also access the WSDL files directly in the \inserver6\messageagent\wsdl directory on the server computer. 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. 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 On the website, click Customer Portal, enter your user name and password, and then select the Product Documentation tab. Message Agent does not have a file size limit on the return however on a request, the file size limit is dependent on the available memory in your environment. ImageNow Message Agent Installation and Setup Guide Page 23 of 28

24 Question How do I view Message Agent log files to help resolve errors? How can I spy on the SOAP/XML messages? Answer 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. Many development companies provide tools for sniffing or spying on SOAP request and response messages between your client application and Message Agent. Additionally, you can use the Message Agent Interceptor to spy on requests submitted to any of the previously enabled endpoints that log their SOAP requests and responses in separate text files. For more information, refer to the "Interceptor logging section of this guide. ImageNow Message Agent Installation and Setup Guide Page 24 of 28

25 Appendix A: inserverma.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 server.ip.port socket.login.timeout socket.default.timeout Any valid IP address or a semicolon delimited string of valid IP addresses. Any valid port. Any positive integer. Any positive integer. Specifies the IP address of ImageNow Server. You can supply multiple IP addresses with a semicolon delimited string. For example: ; ; The default is Specifies the Message Agent port number. The default is Specifies how many seconds Message Agent waits for successful login before terminating the connection. The default is 60. Specifies how many seconds Message Agent waits for APIs. The default is 60. ImageNow Message Agent Installation and Setup Guide Page 25 of 28

26 Group Setting Options Description Logging refresh.mode Specifies how often ImageNow Server rereads 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 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. 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 3 for user jsmith, create a string that states: jsmith.socket.level.file = 3. ImageNow Message Agent Installation and Setup Guide Page 26 of 28

27 Group Setting Options Description Output output.downscale.color.mode 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. Note This parameter must equal 2 if output.downscale.color.mode is set to 2. ImageNow Message Agent Installation and Setup Guide Page 27 of 28