You can expose FlowForce Server jobs as Web services. Jobs exposed as Web services are primarily meant to be accessed programmatically. For testing and debugging purposes, however, you can also invoke such jobs from a browser.
To make a job available as a Web service:
1.Create a new job or open an existing one for editing.
2.Select the Make this job available via HTTP... check box.
3.Type the name of the Web service in the "myURL" text box.
When you save the job, FlowForce Server starts a listener service which accepts HTTP GET and POST requests at the specified request URL specified. Jobs exposed as services remain active as long as FlowForce server is running.
| Note: | The Call Web Service  button is available only if you have set the Host name field of the FlowForce Server service from the Setup page. Clicking this button invokes the Web service in a new browser window. If you haven't configured a host name for FlowForce Server, the button is not displayed, but you can still call the Web service by typing its URL manually in the browser's address bar. |
When the Web service is invoked, FlowForce Server runs the job execution steps specified and returns one of the following:
•The first result file of the last step, if the job produces a result file;
•The standard output of the last step, if no result files are produced (this might be the case when you are working with command line output).
A valid result is returned with a HTTP 200 status, with the Content-Type header set according to the result. The Content-Type header depends on the actual result. A MapForce mapping will result in text/xml if it has XML output, or text/plain for text output. Standard output of other functions is also returned as text/plain. The result is returned as the response body, without any embellishments.
Execution errors are reported as HTTP 5xx status with a generic error message. For further information, check the FlowForce Server log.
For a step-by-step example of how to configure such a job, see Exposing a Job as a Web Service.
It is possible to configure FlowForce to return a result before all the job steps are executed. This is particularly useful if the job invoked as a service takes a long time. The early result could be treated by the caller as a confirmation that the task has been accepted by FlowForce Server for processing. For details, see Postponed Steps.
To view all currently configured FlowForce Server Web services:
Do one of the following:
•In the FlowForce Web administration interface, go to Home and click Show all active triggers and services. See also Active triggers and services.
•Access the following URL from your browser: http://[FlowForceServer][ServerPort]/service/*
| Note: | In the URL above, [FlowForceServer] and [ServerPort] refer to the network address and port where FlowForce Server is listening. By default, FlowForce Server runs on http://localhost:4646 (assuming you are accessing it from the same machine). The server name and port are as defined in the administration page, see Defining the Network Settings. |
Web service parameters
When you expose a job as Web service, all job parameters automatically become parameters for the service. If a job parameter does not have a default, it is mandatory and must be provided when invoking the service. Optional parameters take the default value if not provided in the request.
When the service is invoked, FlowForce Server verifies the parameters supplied in the request against those defined in the job. If parameter validation fails, FlowForce Server returns a 5xx HTTP status. In this case, FlowForce Server also displays an HTML parameter form, for debugging and testing purposes. You can use the HTML form to enter manually any parameters, for debugging and testing. For each parameter of type Stream, a Browse button becomes available in the page, and you can use it to upload the file required as parameter.
To display the testing HTML form unconditionally, supply the built-in parameter showform in the request (with any value).
To call a FlowForce Web service with parameters, a client can use one the following options:
1.For parameters of simple type such as strings or numbers, a client can supply them in the URL of the GET or POST request. For an example, see Expose a Job as a Web Service.
2.In case of POST requests, a client can additionally provide parameters as multipart/form-data, or as application/x-www-form-urlencoded. If the parameter is of type "stream" in FlowForce, then the client must provide them (and FlowForce expects them) as multipart/form-data. For such parameters, the browser test HTML form displays a Browse button next to the corresponding parameter, as mentioned above.
3.The client call can also include arbitrary content in the body of the POST request (this specifically refers to content such as JSON or XML posted not as a parameter but as the body of the HTTP request). In order for this to be possible, the FlowForce job must contain a single parameter of type stream. If you need additional non-stream parameters, these must be supplied in the POST URL. However, only one parameter of type stream must be defined in FlowForce; other parameters must be of non-stream type. When these conditions are met, the request body will be treated as data for the stream parameter. No other configuration is required. For an example, see Post JSON to FlowForce Web Service.
Web service authentication
By default, FlowForce Server uses HTTP Basic authentication to authenticate clients calling a Web service. User credentials are checked against the FlowForce Server user database (the same user name and password used to log on to FlowForce Server Web administration interface).
To make a Web service available without credentials, grant the Use Service permission to the default 
anonymous user (see also How Permissions Work).
You can still supply HTTP credentials when a service is available for anonymous use. The credentials are then checked against the FlowForce Server user database and the service execution is attributed to the authenticated user instead of user anonymous.
If you supply invalid credentials, the request interface returns an HTTP status of 401. If you did not supply credentials and service use has not been granted to anonymous on this service, the request interface also returns an HTTP status of 401.
If you supplied valid credentials, but the authenticated user is not granted Use Service permission on this service, the request interface will return an HTTP 4xx failure status. If you try accessing a service that does not exist, an HTTP 4xx failure status is returned.
Optionally, domain authentication can also be configured, in addition to HTTP basic authentication. For information about how to configure it, see Changing the Directory Service Settings. Once domain authentication has been configured, users will be able to access Web services exposed by FlowForce Server, provided that they supply a valid username and password for the respective domain. Importantly, for Active Directory, the username must contain the prefix NT/ and must include the domain name, for example: NT/john.doe@my.domain.com.
Queue settings
Service URL requests are a particular kind of trigger, and are therefore subject to the same queue constraints once the connection has been established. See Defining Queue Settings.
Configuring the maximum size of the HTTP request body
A default limit exists in FlowForce Server that establishes the maximum size of the HTTP request body, which is around 100 MB. When a caller posts HTTP requests to FlowForce jobs exposed as Web services and the HTTP request body exceeds this limit, FlowForce Server may return an error with the following text:
The entity sent with the request exceeds the maximum allowed bytes.
To accept requests of larger sizes:
1.Open the flowforce.ini file in a text editor.
2.Add the option max_request_body_size to the [Listen] or [ListenSSL] section and set it to the maximum number of bytes that should be allowed.
For example, in order to enable a maximum size of 500 MB, your flowforce.ini file could look like this:
[Listen] |
For more information about the .ini file, see Configuration File Reference.
Reconfiguring FlowForce Server pool threads
If you expect a large number of parallel HTTP service requests (for example, 20 or more at a time), it is possible to reconfigure the server for a slightly larger number of pool threads.
1.Open the flowforce.ini file in a text editor.
2.Add the option thread_pool to the [Listen] or [ListenSSL] section of the .ini file and set it to a value larger than 20.
3.Restart the service.
| Note: | It is a good idea to have two separate [Listen] sections, one for FlowForce Web Server (which doesn’t require that many pool threads) and the other for all other requests (on a different port, preferably). Otherwise, FlowForce Web Server will be competing with all the other HTTP requests for pool threads. |
