Exact Financials

How to setup Web Service Adapter for Excel add-in (Version 7.20 and higher)

Conventions

The following conventions will be used:

• <server> server on which the Web Services Adapter and web service are created
• <tomcat> directory in which Apache Tomcat was installed
• <appserver> name of AppServer in OpenEdge Explorer
• <wsa> Web Services Adapter name
• <wsm> name of *.wsm file used for deploying web services; can be found in installation folder
• <progress> directory with corresponding Progress OpenEdge version installed - the version used for the deployment of web services should be at least 10.2B
• <port> default listening port for Apache Tomcat is 8080

Apache Tomcat

Install Apache Tomcat in order to run web services deployed using OpenEdge Explorer. The version of Apache Tomcat that can be used depends on the minimum Java version supported by Apache Tomcat and the Java version used by Progress OpenEdge - see document 23.687.104 for details. When using Progress OpenEdge 10.2B, Tomcat 6.0 should be used.

Copy the directory \wsa located in < progress >\servlets into the directory <tomcat>\webapps.

Update the file <tomcat>\conf\tomcat-users.xml. Add two <role> tags with values PSCAdmin and PSCOper and update the admin tag:

<tomcat-users>
  <role rolename="PSCAdmin" />
  <role rolename="PSCOper" />
  <user username="admin" password="admin" roles="manager,PSCAdmin,PSCOper" />
</tomcat-users>

Web Services Adapter

Run the CD installation of Exact Financials again to create the Web Services Adapter. If the Web Services Adapter is not created by the installation wizard you can create it manually.

Create the web service adapter:

• Open Progress Explorer > Web Services Adapter folder and select the default web service wsa1. Delete it. and re-create it as <wsa>:
  • Name: <wsa>
  • URL: http://<server>:<port>/wsa/<wsa>.
• On the Security tab:
  • Enable WSA Administration Authentication; No user authentication.
  • Disable Require WSA Administration Authentication.
  • Enable Web services.
  • Save changes.

Edit the web.xml file located in the <tomcat>\webapps\wsa directory (or <tomcat>\webapps\wsa\WEB-INF):

<servlet>
  <servlet-name>wsa_servlet</servlet-name>
  <display-name>Web Services Adapter servlet - wsa</display-name>
  <init-param>
    <param-name>instanceName</param-name>
    <param-value>wsa</param-value>
  </init-param>
</servlet>
<servlet-mapping>
  <servlet-name>wsa_servlet</servlet-name>
  <url-pattern>/wsa /*</url-pattern>
</servlet-mapping>

 After the Web Services Adapter has been created, ensure the following lines in the <tomcat>\conf\web.xml file are commented out:

<!--
  <security-constraint>
    <web-resource-collection>
       <web-resource-name>wsaexact Admin</web-resource-name>
       <url-pattern>/wsaexact/admin/*</url-pattern>
       <http-method>POST</http-method>
    </web-resource-collection>
    <auth-constraint>
       <role-name>PSCAdmin</role-name>
       <role-name>PSCOper</role-name>
    </auth-constraint>
    <user-data-constraint>
       <transport-guarantee>NONE</transport-guarantee>
    </user-data-constraint>
  </security-constraint>
-->

Restart Tomcat.

Open http://<server>:<port>/wsa/<wsa> in an internet browser. If the Web Services Adapter was setup correctly the following response will be shown:

WSA Web Services

         Status:wsa:OK:111

A state-free AppServer is needed to run the Web Services. You can use the existing AppServer or create a new AppServer:

Create a new state-free AppServer:

• Name: <appserver>.
• In AppServer properties/Broker/General tab check if port number is set to unused one and operation mode is state-free.
• Note: with a state-free appserver, it is not possible to specify Connect parameter on the Agent/Advanced features tab. But all other options should be the same as a ‘normal’ appserver.

Deploying web service

Copy <wsm> file to the <server> and update it (if you ran the installer of Exact Financials again, this part is handled by the installer):

• Locate the tag <Service> and replace <appserver>. NOTE: The name is case-sensitive so type it exactly as it appears in the Progress Explorer.
• Locate the tag <SoapEndpointURL> and replace its value with the URL of the web service: http://<server>:<port>/wsa/<wsa>.
• Save file.

Verify the wsa instance by checking the status in OpenEdge Explorer (right-click on the WSA instance / status).

Deploy and enable the web service (to update an existing one you need first to disable it).

There are two methods for deploying a web service: OpenEdge Explorer and WSAMAN utility. 

Method 1 - OpenEdge Explorer

• In OpenEdge Explorer select your <wsa> in web services folder and select Deploy.
• Select <wsm> file and deploy with default values.
• After deployment is finished enable the web service.

Method 2 - WSAMAN utility

Use following commands:

• Deploy: <progress>\bin\wsaman.bat -name <wsa> -wsm <wsm> –deploy.
• Enable: <progress>\bin\wsaman.bat -name <wsa> -appname <appserver> –enable.
• Disable: <progress>\bin\wsaman.bat -name <wsa> -appname <appserver> –disable.
• Update: <progress>\bin\wsaman.bat -name <wsa> -wsm <wsm> –update.

exceladdin.wsdl file is generated during deploying web service and is located in <tomcat>\webapps\<wsa> directory. Update it:

• Locate the tag <soap:address> and update location: http://<server>:<port>/wsa/<wsa>.
• Save file.

Check status of wsa. It should contain follow values:

• WSA Administration: Enabled
• Web Services: Enabled
• WSDL Retrieval: Enabled

Now the wsdl reference can be used to connect to the web service from Excel. 

Notes:

• Log files of Tomcat can be found in <tomcat>\logs directory. 
• In case multiple Progress OpenEdge versions are installed user –port parameter when deploying/updating web services from WSAMAN.
• If the web service was deployed successfully and has status Enabled, but you still cannot connect to the web service from the Excel Add-In, check appServicePort (in Status properties of <wsa> in OpenEdge Explorer).
• If you want to add second instance of the Web Services Adapter, see Progress Knowledge Base solution ID P91699.

References to Written Documentation: OpenEdge Application Server: Administration, "Deploying and Managing Progress 4GL Web Services"