Exposing Jobs as Web Services

www.altova.com Print this Topic Previous Page Up One Level Next page

Home >  Configuring Jobs >

Exposing Jobs as Web Services

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.Click to select the Make this job available via HTTP... check box.

ff-service

3.Type the name of the Web service in the myURL text box.

 

At the request URL specified, FlowForce Server starts a listener service which accepts HTTP GET and POST requests. Jobs exposed as services remain active as long as FlowForce server is running.

 

When the 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 (see Viewing the Job Log).

 

For a step-by-step example of how to configure such a job, see Exposing a Job as a Web Service.

 

 

To view all currently running FlowForce Server Web services:

Open your browser and enter the following URL in the address bar.

 

http://[FlowForceServer][ServerPort]/service/*

 

[FlowForceServer] and [ServerPort] refer to the network address and port where FlowForce Server is running. 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 Setting the Network Address and Port).

 

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).

 

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.

 

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).

ff_login_04

To make a Web service available without credentials, grant the Use Service permission to the default useranonymous 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.

ff_login_03

 

Queue settings

Service execution behaves like execution via trigger, and is subject to the same queue constraints (see Defining Queue Settings).


© 2019 Altova GmbH