Altova FlowForce Server 2024 Advanced Edition

FlowForce Server allows you to configure jobs as Web services. FlowForce Server Advanced Edition also allows you to configure AS2 messages as Web services. For more information, see Send AS2 Messages and Receive AS2 Messages.Jobs configured as Web services are primarily meant to be accessed programmatically. For testing and debugging purposes, you can also invoke such jobs from a browser.

Configure a job as a Web service

To make a job available as a Web service, take the following steps:

1.Create a new job or open an existing one for editing.

2.Select the Make this job available via HTTP at URL check box (see screenshot below).

3.Type the name of the Web service in the text field.

Jobs configured as services remain active as long as FlowForce server is running.

Note:

The button (Call Web Service) 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 have not 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.

Possible outcomes

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 an 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 are also returned as text/plain. The result is returned as the response body.

Execution errors are reported as an HTTP 5xx status with a generic error message. For further information, check the FlowForce Server log.

For examples of Web services, see Expose 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.

View current Web services

To view all current Web services, do one of the following:

•Go to the Home page and click Show all active triggers and services. See also Active timers.

•Access the following URL from your browser: http://[FlowForceServer][ServerPort]/service/*.

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 defined on the Administration page. For more information, see Defining the Network Settings.

Web service parameters

When you expose a job as a Web service, all job parameters automatically become parameters for the service. A job parameter must have a default.

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.

For each parameter of type stream, the Browse button becomes available on the page, and you can use the button to upload the file required as a 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 the 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 as multipart/form-data. For such parameters, the browser test HTML form displays the Browse button next to the corresponding parameter.

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 supply valid credentials, but the authenticated user is not granted thr 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, you will get the HTTP 4xx failure status.

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:

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.