M-PS Web services 8.0 EN

Sommaire

1 Presentation / Objectives
2 Requirements
3 Related Documentation
4 Introduction to Web Services
5 Creating a Client
6 Installing the Web Services
7 Source Example
8 Enabling Anonymous Connections
9 List of Existing Functions

Presentation / Objectives

This document describes the configuration and use of Mapping web services.

Requirements

Knowledge of a development environment for web services. - Microsoft Visual Studio - Server J2EE

Introduction to Web Services

The web services enable you to run Mapping commands in your own application (javascript, c# or java) so you no longer need to use the Mapping web UI. The web services enable you to perform the following basic actions available in the spooler: •actions on a spooled file release hold transfer delete view content display log file display information

•actions on an output queue start stop display log file display information In addition to the actions above, the web service handles spooled file sending, previewing and remapping. The upload (send spooled file), preview (preview spooled file) and run (remap spooled file) methods offer two ways of sending a spooled file or view the result of the spooled file that was generated or sent. For larger files, a URL version can be used for each method which saves the spooled file to the disk and transfers the URL so the client or server application may read the spooled file indirectly. In the stream method, spooled file content is sent directly through the network. An exception is raised if the volume of data included in the spooled file is too large. However, it is recommended to use the stream version as it is a lot faster.

Creating a Client

The Web Services Description Language (wsdl) is a XML based language providing a web service description model. The wsdl specifies: Supported operations (method names) Detailed data type information (number and type of method input and output parameters) The protocol used: SOAP The URL of the service to be used On the client side, a stub and interfaces representing the objects to be processed are generated automatically when importing the wsdl. The wsdl can be accessed by adding ?wsdl at the end of the address where the web service is found. For example: http://localhost:8080/MapSoapServer/MapSoapServer?wsdl

Installing the Web Services

Follow these steps to install the Web services: Check that the mapsoapserver file is in the cgi folder of the web server. Test the connection locally: http://localhos:t:8002/cgi-bin/mapsoapserver.exe Then, remotely: http://localhost:8002/cgi-bin/mapsoapserver.exe?wsdl List of variables that need to be checked and configured in Mapping.conf: SOAP_PATH_TEMP: temporary folder used by the SOAP server SOAP_PATH_LOG: folder used to store the log only if folder SOAP_DEBUG=on or if an error occurs SOAP_LOCATION: web service remote access URL SOAP_LOCAL_URL: local folder corresponding to SOAP_DOCUMENT_URL enabling the SOAP client to retrieve larger files SOAP_DOCUMENT_URL: remote access URL to the document produced by the SOAP server SOAP_HOST_PROXY: proxy used to access the files specified by the SOAP client SOAP_PORT_PROXY: proxy port SOAP_DEBUG: SOAP debug mode

SOAP

[SOAP_PATH_TEMP] C:\Program Files\MappingWindows\Temp\HTTPServer [SOAP_PATH_LOG] C:\Program Files\MappingWindows\Temp\HTTPServer [SOAP_LOCATION] http://localhost:8002/cgi-bin/mapsoapserver.exe [SOAP_LOCAL_URL] C:\Program Files\MappingWindows\MapHTTPServer\shareFolder [SOAP_DOCUMENT_URL] http://localhost:8002/shareFolder [SOAP_HOST_PROXY] 0 [SOAP_PORT_PROXY] 0 [SOAP_DEBUG] On

Source Example

Microsoft Visual Studio : C#

To test the Mapping web services under VS, create a new project.

Select project type, for example a console application.

Add a web reference

As web reference address, choose http://localhost:8002/cgi-bin/mapsoapserver.exe?wsdl and give it a name e.g. MappingSuitePrintService

Anwser security questions according to web server configuration.

Enter the source code you wish to test. using System; using ConsoleApplication.MappingSuitePrintService; namespace ConsoleApplication { /// <summary> /// Summary description for Class1. /// </summary> class Class1 { /// <summary> /// The main entry point for the application. /// </summary> [STAThread] static void Main(string[] args) { MapSoapServerService MappingSoapServer = new MapSoapServerService(); stopQueue resultStop=MappingSoapServer.mapStopQueue("PRT01"); } } }

Java

Creating the stub C:\jboss-4.2.1.GA\bin> wsconsume.bat –k –p clientmapsoapsever.jboss.ejb http://127.0.0.1:8002/cgi-bin/mapsoapserver.exe?wsdl

-o "C:\workspace\ClientMapSoapServer\src"

Java source file package clientmapsoapserver.ConsoleApplication.sw; public class ConsoleApplication { public static void main(String[] args) { clientmapsoapsever.jboss.ejb.MapSoapServerService service = new clientmapsoapsever.jboss.ejb.MapSoapServerService(); clientmapsoapsever.jboss.ejb.MapSoapServer MappingSoapServer = service.getMapSoapServerPort(); MappingSoapServer.mapStopQueue("PRT01"); } }

Javascript

<html> <body> <script type="text/javascript"> var http_request = false; function makeRequest(url) { var xhr_object = null; if ( window.XMLHttpRequest ) xhr_object = new XMLHttpRequest(); else if(window.ActiveXObject) { try { xhr_object = new ActiveXObject("Msxml2.XMLHTTP"); } catch(e) { try { xhr_object = new ActiveXObject("Microsoft.XMLHTTP"); } catch(e) { xhr_object = null; } } }

if (!xhr_object) { alert('Cannot create XMLHTTP instance'); return false; } xhr_object.open('GET', url, false); xhr_object.send(parameter); return xhr_object.responseXML; } function stopQueue(qname) { currentresults=""; parameter="http://127.0.0.1:8002/cgi-bin/mapsoapserver.exe/mapStopQueue?qname="+qname; var xmldoc=makeRequest(parameter); var root=xmldoc.getElementsByTagName('stopQueue').item(0); var results=root.getElementsByTagName('infos').item(0); if (results.textContent) { currentresults=results.textContent; } else if (results.text) { currentresults=results.text; } alert(currentresults);

stopQueue("MAPPING"); </script> </body> </html>

Enabling Anonymous Connections

Editing the Apache configuration file. To enable anonymous connections to another URL or port, all you need to is define a new AccessFileName.

	 #BEGIN_MAPPING_1.00.30_12-6-2007

LoadModule ldap_module modules/mod_ldap.so
LoadModule authnz_ldap_module modules/mod_authnz_ldap.so

Listen 8002 NameVirtualHost *:8002 <VirtualHost *:8002> AccessFileName .htaccess ServerName SERVEURSAP DocumentRoot "C:/Program Files/MappingWindows/MapHTTPServer" <Directory "C:/Program Files/MappingWindows/MapHTTPServer/cgi-bin"> AllowOverride All Order allow,deny Allow from all Options None </Directory>

ScriptAlias /cgi-bin/ "C:/Program Files/MappingWindows/MapHTTPServer/cgi-bin/" <Directory "C:/Program Files/MappingWindows/MapHTTPServer"> AllowOverride All Order allow,deny Allow from all Options None </Directory> </VirtualHost>

END_MAPPING_1.00.30_12-6-2007

<Directory "C:\Program Files\Apache Software Foundation\Apache2.2\htdocs\MapWebFiles"> AllowOverride all Order deny,allow </Directory>

AccessFileName .config ScriptAlias /MapHTTPServer "C:/Program Files/MappingWindows/MapHTTPServer/" <Directory "C:/Program Files/MappingWindows/MapHTTPServer"> AllowOverride All Order allow,deny Allow from all Options None </Directory> ScriptAlias /MapHTTPServer/cgi-bin "C:/Program Files/MappingWindows/MapHTTPServer/cgi-bin/" <Directory "C:/Program Files/MappingWindows/MapHTTPServer/cgi-bin">

AllowOverride All Order allow,deny Allow from all Options None </Directory>

List of Existing Functions

To learn about existing functions, you can use: • the WSDL: http://127.0.0.1:8002/cgi-bin/mapsoapserver.exe?wsdl • if you can access the localhost system, see here for an overview of HTML functions: http://127.0.0.1:8002/cgi-bin/mapsoapserver.exe

	Note

On UNIX/Linux, delete .exe All functions are described in the HTML function overview page. The WSDL describes the expected input and output parameters. key and value are specific parameters that are combined together to let you define an unlimited set of values so they can be used in the rules engine. For example, for insert spooled file commands, they become user data of the spooled files produced. For rules engine commands, they become rules engine parameters. 9.1. Listing Functions mapListSplf : List user spool files Sample GET http://localhost:8002/cgi-bin/mapsoapserver.exe/mapListSplf?login=mapadmin&ownerName=*&site=*&qname=*&splf=*&state=*

mapListSplfWithDate : List user spool files by date Sample GET http://localhost:8002/cgi-bin/mapsoapserver.exe/mapListSplfWithDate?login=mapadmin&ownerName=*&site=*&qname=*&splf=*&state=*&fromDay=21&fromMonth=1&fromYear=2006&toDay=21&toMonth=1&toYear=2006

mapListPrinter : List available printers Sample GET http://localhost:8002/cgi-bin/mapsoapserver.exe/mapListPrinter?login=mapadmin&ownerName=*&site=*&qname=*&type=*&state=*

mapListPrinterTransfer : List all printers available for transfer Sample GET http://localhost:8002/cgi-bin/mapsoapserver.exe/mapListPrinterTransfer?login=mapadmin

Functions on Individual Spooled Files

mapRestartPrinting : Restart a print job at a given page Sample GET http://localhost:8002/cgi-bin/mapsoapserver.exe/mapRestartPrinting?jobNum=000000000030072&startPage=1&stopPage=1&user=mapadmin&qname=PRT01&title=My Title&orignalQname=PRT01

		mapMoveSplf : Move a spool file to another queue

Sample GET http://localhost:8002/cgi-bin/mapsoapserver.exe/mapMoveSplf?jobNum=000000000030072&qname=PRT01&oldqname=PRT02 mapDelSplf : Delete a spool file Sample GET http://localhost:8002/cgi-bin/mapsoapserver.exe/mapDelSplf?jobNum=000000000030072&qname=PRT01 mapReleaseSplf : Release a spool file Sample GET http://localhost:8002/cgi-bin/mapsoapserver.exe/mapReleaseSplf?jobNum=000000000030072&qname=PRT01 mapHoldSplf : Hold a spool file Sample GET http://localhost:8002/cgi-bin/mapsoapserver.exe/mapHoldSplf?jobNum=000000000030072&qname=PRT01 mapInfoSplf : Display spool file information Sample GET http://localhost:8002/cgi-bin/mapsoapserver.exe/mapInfoSplf?jobNum=000000000030072&qname=PRT01&user=mapadmin

mapChangeSplfUser : Change spool file User Sample GET http://localhost:8002/cgi-bin/mapsoapserver.exe/mapChangeSplfUser?jobNum=000000000030072&qname=PRT01&value=my value mapChangeSplfSave : Change spool file Save Sample GET http://localhost:8002/cgi-bin/mapsoapserver.exe/mapChangeSplfSave?jobNum=000000000030072&qname=PRT01&value=my value

			mapLogSplf : View spool file log

Sample GET http://localhost:8002/cgi-bin/mapsoapserver.exe/mapLogSplf?qname=PRT01&jobNum=000000000030072&login=yourvalue&filter=yourvalue&dateFrom=yourvalue&dateTo=yourvalue&level=yourvalue 9.3. Functions on Multiple Spooled Files mapHoldMultiSplf : Hold multiple spool files Sample GET http://localhost:8002/cgi-bin/mapsoapserver.exe/mapHoldMultiSplf?jobNum=000000000030072&qname=PRT01 mapReleaseMultiSplf : Release multiple spool files Sample GET http://localhost:8002/cgi-bin/mapsoapserver.exe/mapReleaseMultiSplf?jobNum=000000000030072&qname=PRT01 mapDelMultiSplf : Delete multiple spool files Sample GET http://localhost:8002/cgi-bin/mapsoapserver.exe/mapDelMultiSplf?jobNum=000000000030072&qname=PRT01 mapMoveMultiSplf : Move multiple spool files Sample GET http://localhost:8002/cgi-bin/mapsoapserver.exe/mapMoveMultiSplf?jobNum=000000000030072&qname=PRT01&oldqname=PRT02 mapSplfPreviewURL : Download the spool file preview URL Sample GET http://localhost:8002/cgi-bin/mapsoapserver.exe/mapSplfPreviewURL?qname=PRT01&jobNum=000000000030072

mapSplfPreviewStream : Download spool file preview stream Sample GET http://localhost:8002/cgi-bin/mapsoapserver.exe/mapSplfPreviewStream?qname=PRT01&jobNum=000000000030072

Printer Functions

mapRefreshStatus : Refresh printer status Sample GET http://localhost:8002/cgi-bin/mapsoapserver.exe/mapRefreshStatus?qname=PRT01 mapRestartDevice : Restart a device Sample GET http://localhost:8002/cgi-bin/mapsoapserver.exe/mapRestartDevice?deviceName=DEVPRT01&qname=PRT01 mapStartQueue : Start a queue Sample GET http://localhost:8002/cgi-bin/mapsoapserver.exe/mapStartQueue?qname=PRT01 mapStopQueue : Stop a queue Sample GET http://localhost:8002/cgi-bin/mapsoapserver.exe/mapStopQueue?qname=PRT01 mapInfoPrinter : Display printer information Sample GET http://localhost:8002/cgi-bin/mapsoapserver.exe/mapInfoPrinter?qname=PRT01&user=mapadmin mapLogQueue : View queue log Sample GET http://localhost:8002/cgi-bin/mapsoapserver.exe/mapLogQueue?qname=PRT01&login=mapadmin&filter=yourvalue&dateFrom=yourvalue&dateTo=yourvalue&level=yourvalue

Print Request Functions

mapUploadMessage : Upload a message as a spool file This function inserts a message in the spooler by sending the text message as a parameter. For instance, the method lets you start a process. This method is not suited for binary data or larger size data. Sample GET http://localhost:8002/cgi-bin/mapsoapserver.exe/mapUploadMessage?qname=PRT01&title=yourvalue&user=yourvalue&stream=yourvalue&key=yourvalue&value=yourvalue mapUploadFile : Upload a file as a spool file This function inserts a file in the spooler by sending the file as a stream (base64 encoding). This method lets you transfer binary files but does not support larger size data. Sample GET http://localhost:8002/cgi-bin/mapsoapserver.exe/mapUploadFile?qname=PRT01&title=yourvalue&user=yourvalue&stream=yourvalue&key=yourvalue&value=yourvalue mapUploadURL : Upload a url as a spool file This function inserts a file in the spooler by asking the Mapping web service to retrieve the file from a URL passed as a parameter. This function supports binary files and larger files. Sample GET http://localhost:8002/cgi-bin/mapsoapserver.exe/mapUploadURL?qname=PRT01&title=yourvalue&user=yourvalue&url=yourvalue&key=yourvalue&value=yourvalue mapRunStream : Run Mapping engine data stream This function submits a base 64 encoded file to the rules engine and receives a base 64 encoded document in return. The rules engine has the value MAP_SOAP = On enabled automatically to support specific rules for SOAP accesses. Sample GET http://localhost:8002/cgi-bin/mapsoapserver.exe/mapRunStream?stream=base 64 data&key=anyname&value=any value

	Note

For SOAP accesses with a GET request, if you add the parameter getobject=1 the response will be the document without base 64 encoding, which lets you use it in HTML pages to request a document preview for example. http://localhost:8002/cgi-bin/mapsoapserver.exe/mapRunStream?stream=base 64 data&key=anyname&value=any value&getobject=1 mapRunURL : Run the stream and get URL This function submits a base 64 encoded file to the rules engine and receives the URL of the document produced in return, letting the web client delete the document through the mapRemoveTempURL request or any other script. The rules engine has the value MAP_SOAP = On enabled automatically, which lets you set specific rules on SOAP accesses. Sample GET http://localhost:8002/cgi-bin/mapsoapserver.exe/mapRunURL?stream=yourvalue&key=yourvalue&value=yourvalue mapRemoveTempURL : Remove the temp URL built by SOAP server This function deletes the file created by the mapRunURL or mapSplfPreviewURL method. Sample GET http://localhost:8002/cgi-bin/mapsoapserver.exe/mapRemoveTempURL?downloadurl=http://localhost/shareFolder/090432424242343243.tmp

Detailed Upload Method Information

The upload method sends a spooled file to a queue. A temporary file is created on the server side containing the data that has been sent. The temporary file is deleted when the map_lp command is run.

For the URL version, the file must be copied to a site that can be accessed by the web service.

Below is a diagram showing the architecture used during an upload.

Legend

0b Copy file to remote URL (URL version)
1 Launch client
2 Call remote method
3b Read file at specified URL (URL version)
4 Create temporary file
5 Launch map_lp
6 Read temporary file data
7 Create the spooled file in the queue

Detailed Preview Method Information

The preview method returns the content of a spooled file that has been sent to a queue. Below is a diagram showing the architecture used during an preview.

Legend  1 Launch client  2 Call method remotely  3 Launch map_view  4 Communicate with the spooler  5 Receive results through web service  6a Send data streamed to client  6b Write result to a file  7a Return spooled file + headers to client  7b Send URL to client  8b Send URL to application

9.8. Detailed Run Method Information The run method remaps the spooled file that was sent. The run can be seen as 3 consecutive steps: upload, process, and preview generated file. The difference with a usual upload is that the spooled file does not have to be sent to a queue for printing, it has to be sent to an entry. This way, the spooled file is processed by the rules engine. User data called SOAP_RUN_FILE is added automatically. A rule testing whether the user data can be found is used to call a specific process: call mapcpysplf with different arguments (mapnam, mapseq, mapmod, inFile, outFile and lang) to remap the file. Below is a diagram showing the architecture used during a run:

Legend  0b Copy file to remote URL (URL version)  1 Launch client  2 Call remote method  3b Read file at URL specified  4 Create temporary file  5 Launch map_lp  6 Read temporary file data  7 Create spooled file in the queue  8 Process and create temporary file (remapped file)  9 Read file through web service  10a Send data streamed to client  10b Write result to file  11a Return remapped spooled file content to client  11b Return remapped spooled file URL to client 9.9. XML Data Diagram for Spooled File View

10. Returning a File to the Web Service Client from the Rules Engine To enable the rules engine to return responses to the web service client, the rules engine needs to be used. "map_echo.exe" "Cache-Control: no-cache\nContent-type: application/pdf;\n\n" "map_echo.exe" "-infile:C:\Program Files\MappingWindows\Temp\myfile.pdf" 11. Protocol Used The protocol used is described in http://www.w3.org/TR/soap 11.1. SOAP HTTP GET Usage Question: GET /travelcompany.example.org/reservations?code=FT35ZBQ HTTP/1.1 Host: travelcompany.example.org Accept: text/html;q=0.5, application/soap+xml Response: HTTP/1.1 200 OK Content-Type: application/xml; charset="utf-8" Content-Length: nnnn

 <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
           xmlns:x="http://travelcompany.example.org/vocab#"
    env:encodingStyle="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
  <x:ReservationRequest 
rdf:about="http://travelcompany.example.org/reservations?code=FT35ZBQ">
     <x:passenger>Åke Jógvan Øyvind</x:passenger>
     <x:outbound>
      <x:TravelRequest>
       <x:to>LAX</x:to>
       <x:from>LGA</x:from>
       <x:date>2001-12-14</x:date>
      </x:TravelRequest>
     </x:outbound>
     <x:return>
      <x:TravelRequest>
       <x:to>JFK</x:to>
       <x:from>LAX</x:from>
       <x:date>2001-12-20</x:date>
      </x:TravelRequest>
     </x:return>
   </x:ReservationRequest>

11.2. SOAP HTTP POST Usage Question: POST /Reservations HTTP/1.1 Host: travelcompany.example.org Content-Type: application/soap+xml; charset="utf-8" Content-Length: nnnn

<?xml version='1.0' ?> <env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" >

<env:Header>
  <t:transaction
          xmlns:t="http://thirdparty.example.org/transaction"
          env:encodingStyle="http://example.com/encoding"
          env:mustUnderstand="true" >5</t:transaction>
</env:Header>  
<env:Body>
 <m:chargeReservation
    env:encodingStyle="http://www.w3.org/2003/05/soap-encoding"
         xmlns:m="http://travelcompany.example.org/">
  <m:reservation xmlns:m="http://travelcompany.example.org/reservation">
   <m:code>FT35ZBQ</m:code>
  </m:reservation>
   <o:creditCard xmlns:o="http://mycompany.example.com/financial">
    <n:name xmlns:n="http://mycompany.example.com/employees">
          Åke Jógvan Øyvind
    </n:name>
    <o:number>123456789099999</o:number>
    <o:expiration>2005-02</o:expiration>
   </o:creditCard>
  </m:chargeReservation
 </env:Body>

</env:Envelope> Response: HTTP/1.1 200 OK Content-Type: application/soap+xml; charset="utf-8" Content-Length: nnnn