This example shows you how to create a FlowForce Web service that accepts POST requests carrying JSON data in the HTTP request body. Secondly, it illustrates how to call the Web service from a client like MapForce.
In this example, the Web service will be configured to accept JSON data; however, you could also post XML or other content to a service created with FlowForce Server in a similar way as shown below. The Web service is intended to be very simple so it will merely accept JSON data and save it locally without any further processing. It is possible to further extend the job to validate the JSON data with RaptorXML Server, or process it, although this will not be done in this example.
This example specifically illustrates the case when data is posted in the body of the HTTP request, not as a parameter. For an example that invokes a Web service with parameters, see Expose a Job as a Web Service.
•Required licenses: FlowForce Server, MapForce Enterprise Edition.
FlowForce Server provides a quick way to create the Web service that will be called by MapForce. MapForce Enterprise Edition acts as a client that calls the Web service created with FlowForce Server. You may also use a different Web client and achieve the same result.
•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)
•This job saves input data received by the Web service to a local working directory, C:\POST. This directory (or a similar one) must exist on the machine where FlowForce Server runs, and your operating system user account must have rights to write to this directory.
Creating the FlowForce job
Login to the FlowForce Server Web administration interface, open the /public container, and then click Create Job. Next, enter a name and, optionally, a description for the Web service you are creating.
In order for the job to treat the POST data as arbitrary content, it must have exactly one parameter of type stream. To create the parameter, click Add parameter , enter a parameter name (in this example, "data"), and select stream as data type.
Next, add a new execution step and configure it as follows:
The execution step above calls the FlowForce built-in copy function. The expression shown in the "Source" text box converts the input received by the Web service to a file by using the as-file expression function (recall that the input parameter was named data in a previous step). To obtain this expression automatically, click the button next to the "Source" text box and then select data.
The "Target" text box contains an expression that produces a unique file name each time when the job is invoked. To obtain the unique file name, the FlowForce instance-id expression function is called; therefore, the JSON file name will look something like "file35.json", and the number will be different with each job call (corresponding to the ID of that FlowForce job instance). You could also enter a full path, but it is not necessary if the "Working directory" path is set, as it was done in this example. When you set the working directory path, any relative file name will be resolved relative to the working directory path.
The directory C:\POST (or a similar one if you changed the path) must exist and your operating system user account must have rights to write to it.
Under "Service", select the Make this job available via HTTP check box, and enter "POST_JSON" or a similar name for the new Web service.
Under "Credentials", select an existing credential record or specify a local credential (see also Credentials). These must be the credentials of the user account on the operating system where FlowForce Server runs.
|Note:||Do not confuse these credentials with the ones used to access the FlowForce Server Web administration interface.|
Click Save. You are now ready to call the new Web service from a client.
Calling the Web service from a browser
As a first step to test the Web service, you can call it from the browser, as follows:
1.Open a Web browser and type the following URL in the address bar:
By default, this URL is http://localhost:4646/service/POST_JSON, if you did not change the FlowForce Server host and port. Otherwise, replace [FlowForceServer] and [Port] with the settings configured in the FlowForce setup page, see Defining the Network Settings. 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 your FlowForce Server credentials.
This is only for testing the Web service and should not be done in production. It is recommended that you create a new FlowForce user, grant the Service - Use permission to this user on the container where the job is, and then access the Web service with the corresponding user account. To disable HTTP authentication and make the Web service public, grant the Service - Use permission to the user Anonymous, see How Permissions Work.
3.Click Browse and select the JSON file to be submitted in the POST request.
4.Click Submit. FlowForce Server processes the job and outputs the response to the browser.
If the job executes successfully, the browser displays "true" and the JSON file is saved to the working directory C:\POST. Otherwise, if you see an execution error, refer to the job log for more details, see Viewing the Job Log.
Calling the Web service from MapForce
You can also call the Web service from a client other than the Web browser, for example, from MapForce Enterprise Edition.
1.On the File menu, click New to create a new mapping.
2.On the Insert menu, click Web Service Function. The Web Service Call Settings dialog box opens.
3.Click Manual, choose POST as request method, and enter the URL of the web service in the URL box. This is the same URL that was used to test the Web service from the browser.
4.Click the Edit button next to "HTTP Security Settings", and enter the credentials required to access the Web service.
|Note:||If you would like to supply the credentials from the mapping instead of saving them in this dialog box, select the Dynamic authentication check box. This makes it possible to supply the credentials interactively as input parameters to the mapping when the mapping runs.|
5.Click OK to close the dialog box. The mapping now looks as follows:
6.Add to the mapping a simple input that will supply the JSON data, by selecting the Insert | Insert Input menu command. Also, enter some sample JSON data to be used for executing this mapping at design time, like the one shown below:
|Note:||The sample JSON data shown here is very short, for demo purposes. When MapForce Server runs the mapping, you can supply the JSON data as input parameter to the mapping from an actual JSON file.|
7.Add the output of the mapping, by selecting the Insert | Insert Output menu command.
8.Drag the charset-encode and mime-entity functions from the Libraries window and make the connections as shown below. You will also need to add two constants, by selecting the Insert | Constant menu command.
Web service call with unstructured body
In the mapping above, the JSON input is provided to the mapping by means of a simple input component. The charset-encode and mime-entity functions are MapForce built-in functions that prepare the body of the HTTP request. The status code returned by the Web service is mapped to the result returned by the mapping.
Preparing the body of the HTTP request in an unstructured manner as shown above is just one of the ways to send data in the POST request. For JSON and XML structures, you can enter the JSON or XML schema of the request in the "Web Service Call Settings" dialog box instead. In this case, the body of the Web service component provides mapping inputs (connectors) based on the JSON/XML structure of the request.
You can now execute the mapping with MapForce, by clicking the Output tab. If an error occurs, it is displayed in the Messages window. To debug, you may need to check the FlowForce Server log as well (assuming that the POST request reached the server). Otherwise, if execution is successful, the following happens:
1.The HTTP status code "200" is displayed in the Output pane.
2.On the server side, the submitted JSON data is written to a file and saved to the C:\POST directory.
The exact behavior of the mapping in case of an error can be further configured from MapForce. Also, the mapping can be run with MapForce Server, or be deployed to FlowForce Server, and turned into a job or even another Web service. For further information, refer to MapForce documentation https://www.altova.com/documentation.