This example illustrates how to expose a sample mapping job as a Web service. The sample mapping was already designed with MapForce; it reads data from a Microsoft Access database which stores a list of person records. The mapping retrieves from the database only person records whose last name begins with a specific letter (supplied as a parameter). You will learn how to deploy the existing mapping from MapForce to FlowForce Server (either on the same or on a different machine), and turn it into a Web service. After completing this example, you will be able to invoke the Web service from a browser.
|•||Required licenses: MapForce Enterprise or Professional edition, MapForce Server or MapForce Server Advanced Edition, FlowForce Server|
|•||FlowForce Server is running at the configured network address and port (see Setting the Network Address and Port)|
|•||You have a FlowForce Server user account with permissions to one of the containers (by default, the /public container is accessible to any authenticated user)|
|•||The mapping used in this example reads data from a Microsoft Access database. Either Microsoft Access or Microsoft Access Runtime (https://www.microsoft.com/en-us/download/details.aspx?id=50040) must be installed on the machine where FlowForce Server runs.|
Demo files used
This example makes use of the following files, available at the following path on the computer where MapForce is installed: ..\Documents\Altova\MapForce2019\MapForceExamples.
|•||DB_PhoneList.mfd (the MapForce mapping design file)|
|•||altova.mdb (the Microsoft Access database from which the mapping reads data).|
Preparing the mapping for deployment to a different machine
Since this mapping reads data from a database file, additional configuration must be done before deploying the mapping, as explained in this section. If MapForce and FlowForce Server are installed on the same computer, you can skip to section "Deploying the mapping" below.
|Note:||The term "source machine" refers to the computer where the MapForce is installed and the term "target machine" refers to the computer where FlowForce Server is installed.|
Before attempting to deploy the mapping to the target machine, do the following:
|1.||On the target machine, configure the "FlowForce Web Server" service to listen either on all interfaces, or on a specific IP address other than the local host, see Defining the Network Settings. You can check whether the service is configured correctly by accessing the following URL from the browser: http://<FlowForce Web Server><port>. Make sure that the incoming connections to the specified address and port are not blocked by the firewall.|
|2.||As mentioned above, the job created in this example must be available as a Web service. In FlowForce, any requests to jobs exposed as Web services are handled by the "FlowForce Server" service (not by the "FlowForce Web Server" service, see also How It Works). Therefore, if the Web service should be accessible to HTTP clients outside of the local host, the "FlowForce Server" service must also be configured to listen either on all interfaces, or on a specific address other than the local host. You can check whether this service is configured correctly by accessing the following URL from the browser: http://<FlowForce Server><port>/service/ . All jobs that are exposed as Web services (if any) should appear as links directly in the browser window.|
Before it is deployed, the mapping must also be reconfigured to use relative instead of absolute paths, as follows:
|1.||Open the DB_PhoneList.mfd mapping in MapForce, right-click the mapping area, and select Mapping Settings from the context menu.|
|2.||Clear the Make paths absolute in generated code check box.|
|3.||Save the mapping.|
File-based databases such as Microsoft Access or SQLite are not deployed to a target machine together with the mapping. Therefore, the Access database must be manually copied from the source machine to the target machine. Copy the altova.mdb database file from the directory ..\Documents\Altova\MapForce2019\MapForceExamples on the source machine to some empty directory on the target machine. In this example, the target directory is "C:\FlowForceWorkingDir". This directory will be referenced later from the FlowForce job.
The mapping is now ready for deployment to FlowForce Server. For more information about deploying mappings which include database connections, see Preparing Mappings for Server Execution.
Deploying the mapping
|1.||Open the DB_PhoneList.mfd in MapForce.|
|2.||On the File menu, click Deploy to FlowForce Server. For the purpose of this example, we assume the mapping is deployed to the default path (/public container). If you are deploying the mapping to FlowForce Server on a different machine, change the server address and port from "localhost:8082" to those configured from FlowForce Server (see above).|
Creating the FlowForce job
So far, you have deployed the mapping to FlowForce Server and have the job configuration page open in the browser (provided that you selected the check box Open web browser to create new job on the dialog box above). Otherwise, login to the FlowForce Server Web administration interface, open the previously deployed mapping function (it should be in the /public container), and then click Create Job.
To configure the job:
|1.||Under "Job Input Parameters", create a new input parameter of type string and name it NamePrefix.|
|2.||Under "Execution Steps", next to NamePrefix, click Set to, and then select NamePrefix. This sets the value of the mapping parameter NamePrefix to the value of the NamePrefix input parameter created in previous step.|
|3.||Next to Working-directory, enter "C:\FlowForceWorkingDir" (this must be the same directory where the Access file was previously copied).|
|4.||Under "Service", select the Make this job available via HTTP check box, and enter "GetPhoneList" as name of the service.|
|5.||Under Credentials, select an existing credential record or specify a local credential (see also Credentials).|
A credential record is the combination of user name and password associated with a user account on the operating system where the FlowForce Server job runs. When you define a job in FlowForce Server, you must supply the credentials with which the job must be executed. Note that if the user account associated with the supplied credentials does not have sufficient rights on the operating system, the job cannot execute successfully.
|Note:||Do not confuse these credentials with the ones used to access the FlowForce Server Web administration interface. Also, make sure that the user entered here is able to access the altova.mdb database file from the working directory; otherwise, the job will fail to execute successfully.|
Invoking the Web service
You can now invoke the Web service you just created, as follows:
|1.||Open a Web browser and type the following URL in the address bar (replace [FlowForceServer] and [Port] with the settings configured in the administration page):|
If you use Internet Explorer to test FlowForce Server jobs exposed as Web services, you may need to disable the "Show friendly HTTP error messages" option in the Advanced tab.
|2.||When prompted to supply credentials, enter the credentials you use to access the FlowForce Server Web administration interface.|
|3.||When prompted to enter the parameters of the Web service, enter F (assuming that you want to retrieve all persons whose surname begins with "F").|
|4.||Click Submit. FlowForce Server processes the job and returns the result.|
If the job executes successfully, the job's output is displayed directly in the browser (and it is also generated in the working directory C:\FlowForceWorkingDir). Otherwise, if you are seeing an execution error, refer to the job log for more details (see Viewing the Job Log).
© 2019 Altova GmbH