Versions Compared

Old Version 4

changes.mady.by.user Ludo Schoonen

Saved on

compared with

New Version 5

changes.mady.by.user Tijmen Daatselaar

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

The AQ_RestServiceClient service makes it possible to call a REST webservice. Besides the functionality found in the old AQ_WebServiceClient this service introduces the possibility of connection overriding and inputting the URL parameter as an expression. 

Parameters

The following parameters can be set for the service from Studio:

NameDescriptionTypeRequiredDirectionSelect module
restServiceThe name of the REST service along with the module where it is defined.Module ElementtrueInputtrue
operationThe name of the operation that needs to be called.StringtrueInputfalse
urlThe URL of the REST webservice.String ExpressionfalseInputfalse
connectionOverride

The name to use when overriding connection in the Runtime configuration files (more about this in the following section).


String ExpressionfalseInputfalse
mappingThe name of the data mapping to use along with the module where it can be found.Data mappingfalseBiDirectionalfalse
usernameThe username to use in the service calling.StringfalseInputfalse
passwordThe password to use in the service calling.StringfalseInputfalse

Overriding parameters

Tip

The parameters url, username and password can be overridden in the Runtime's configuration files. 

...

Code Block
blueriq.connection.connectionName.http.url=http://randomUrl:8080
blueriq.connection.connectionName.http.username=randomUsername
blueriq.connection.connectionName.http.password=randomPassword

Overriding using the service name VERSUS overriding using the connectionOverride

In order to illustrate the benefit of using the new connectionOverride parameter a simple example will be presented.

...

Warning
titleFinal considerations

One must be consistent in the way it assigns value to the service parameters. Giving value to one parameter in a place and to another parameter in another place might prove faulty. For instance if one overrides the url by using a connection override but keeps the username and password values in the Studio model the latter will not be used by the Runtime since it expects them to also be overridden in the configuration files.

Error handling

From Blueriq 11.10 and onward, any status code will be mapped to the profile. However, if the response body doesn't match the domain schema, the exception exit is taken. For empty response bodies, the status code is mapped to the profile as well.

Exit events

NameDescriptionType
TimeoutWhen the REST request returns a timeout exception.

Continue

ClientError (since 16.7)When the REST request returns a 4xx exception.

Continue

ServerError (since 16.7)When the REST request returns a 5xx exception.

Continue

Info

All unmapped events will be redirected to the default exit node of the service call, even errors. Therefore it is recommended to always map all possible expected exit events.

Authentication options

There are several authentication options, which are configurable per connection with properties:

No authentication

When no username and password are set for the service call (none is Studio and also non in the Connections Properties), then no authentication will be attempted. You should use this when the Rest Endpoint that you are calling is not secured.

Basic authentication

When a username and password are supplied, either in Studio or in the Connections Properties, these credentials will be supplied to the Rest Endpoint.

OpenID Connect authentication

See OpenID Connect for more information.

Oauth2 authentication

Note

OAuth2 describes an authentication scheme. In its specification, it is explained what information should be in requests and responses, but not how this information should be transmitted.

Therefore, we use sensible defaults as described in this section. If you need other behavior, you can develop a custom Blueriq extension, as described below.

...

  • When requesting a token, the grant_type and scope attributes will be sent in the request body, using the application/x-www-form-urlencoded encoding scheme.
  • When requesting a token, the Client ID and the Client Secret will be sent as Basic Authentication.
  • When requesting a token, the POST method is used.

  • In the token response, we expect a JSON structure that at least contains an access_token and a token_type:

    Code Block
    languagejs
    {
  "access_token": "f608a968-b1ef-457a-8d1a-71ee007ac4d2",
  "token_type": "bearer"
}

  • Access tokens are not cached. Each Rest Service call will request a new token.

Customization

If you need different behavior, you can write your own custom Access Token Provider, that needs to implement the com.blueriq.component.api.oauth2.Oauth2AccessTokenProvider interface and you need to define it as a Spring Bean in your application.

...