The AQ_RestServiceClient service 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 StudioEncore:

Name	Description	Type	Required	Direction	Select module
restService	The name of the REST service along with the module where it is defined.	Module Element

true

Yes

Input

true

Yes
operation	The name of the operation of the REST service that needs to be called.	String

true

Yes

Input

false

No
url	The URL of the REST webservice.	String Expression

false

No

Input

false

No

connectionOverride

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

Not that if the expression returns the value unknown ( ? ) as result, an error is thrown. In this scenario no fallback is used.

String Expression

false

No

Input

false

No
mapping	The name of the data mapping to use along with the module where it can be found.	Data mapping

false

No	BiDirectional

false

No
username	The username to use in the service calling.	String

false

No

Input

false

No
password	The password to use in the service calling.	String

false

No

Input

false

No

Overriding parameters

...

The parameters url, username and password can be overridden in

...

the Runtime's configuration files.

...

To do so, In order to override parameters from configuration files one can use either the name of the service call of type AQ_RestServiceClient in Blueriq Encore or the value given to the connectionOverride field. For better understanding the following picture is presented:Image Removed

Expand

title	Configuration example

The overriding can be done in

...

the application.properties

...

file by either using the

...

name of the service call in Blueriq Encore (SendRest20) like this:

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

... or by using the connection name (connectionName) like this:

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

Expand

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

Say there is webservice with 5 operations: add, subtract, multiply,

...

divide and

...

modulo. For each operation there is a corresponding service call and for each of those service calls

...

the url, username

...

and password

...

are overridden in

...

the application.properties

...

file using the name of the service

...

call. This means that even if the services call the same webservice (thus calling the same url with the same credentials) the override data must be specified for each of them. This is where the connectionOverride becomes useful by

...

allowing each of those services to use a common connection name and eliminating the need of duplication.

Info
If the value for one of those parameters is specified in more than one place (for instance if the *url* parameter is defined in

the Studio project

Encore but also overridden using the service name) the following prioritization is used by the Runtime:

If there is a connectionOverride defined in

the Studio model

Encore then that connection will be used over the others;
If there is no connectionOverride defined in

the Studio model

Encore, the Runtime will look into the configuration files for (and will use if it exists) a property to override parameters using the service's name;
Finally, if there is no connectionOveride value defined in

the Studio model

Encore and there is no property to override a parameter in the configuration files then the values defined in the

Studio

model in Encore for the url, username and password will be

used.

UI Text Box

type	note

Please note that when the connectionOverride expression returns the value unknown ( ? ) as result, an error is thrown. In this scenario no fallback is

used.

Warning

title	Final 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 Encore, the latter will not be used by the Runtime since it expects them to also be overridden in the configuration files.

Error handling

...

When the runtime sumbles upon an arror during execution of the AQ_RestServiceClient, there are serveral options to handle this:

The exception exit can be used to handle exceptions such as a failing data mapping, or a response body that doesn't match the domain schema

...

.
Use the

...

exit events to handle timeouts, client errors (http status code 4xx), and server errors (http status code 5xx).
- If there is a need to distinguish on a more specific http status code than the aforemantioned ranges, you can use the header in the REST service to map the status code with the name "Status" to the profile.

Exit events

Name	Description	Type
Timeout	When 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

...

default exit event

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.

Continue

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 Encore and also none 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 Encore 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 the Rest Endpoint that needs to be called is secured with OAuth2, you can set the property blueriq.connection.<connectionName>.http.authentication to oauth2. You need to fill out some extra properties that should be provided by the maintainer of the endpointdefine a Spring Security Oauth2 Client Registration and Provider and set the blueriq.connection.<connectionName>.http.oauth2-client-registration to the corresponding client registration. See Connections Properties for those. Blueriq will request a token from the oauth2-token-endpoint and call the Rest Service with that token.

Since OAuth2 doesn't specify how certain properties are transmitted when requesting a token, we include a set of default behavior:

...

Since 17.0 we use Spring Security OAuth2, which makes it a lot more versatile and better configurable.

Code Block

language	yml
title	After

spring:
  security:
    oauth2:
      client:
        registration:
          my-oauth2-client:
            provider: my-auth-server
            client-id: my-client-id
			client-authentication-method: client_secret_basic
            client-secret: secret-password-text
            authorization-grant-type: client_credentials
        provider:
          my-auth-server:
            token-uri: https://identity.provider.com/token
blueriq:
  connection:
    my-connection1:
      http:
        url: https://some.domain.com/resource1
        authentication: oauth2
        oauth2-client-registration: my-oauth2-client
    my-connection2:
      http:
        url: https://some.domain.com/resource2
        authentication: oauth2
        oauth2-client-registration: my-oauth2-client

When requesting a token, the Client ID and the Client Secret will be sent as Basic Authentication as default, but you can also use client_secret_post as client-authentication-method so it will be sent in the body.
Since 17.2 it is also possible to send along custom parameters when requesting a token, see Connections Properties
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
language js
{ "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.

Note

title	Limitations

The current implementation is limited to one Access Token Provider per Blueriq Runtime, so all of your OAuth2 enabled Rest Service Calls will use the same schemeimplementation of the Access Token Provider.
The current implementation does not support the grant type password. We only tested the default implementation only supports the client_credentials grant type.The current implementation will send the Access Token as Bearer to the Rest Service endpoint.

Space shortcuts

Page tree

Versions Compared

Old Version 4

New Version Current

Key

Parameters

Overriding parameters

Error handling

Exit events

Authentication options

No authentication

Basic authentication

OpenID Connect authentication

Oauth2 authentication

Customization

Space shortcuts

Page tree

Page History

Versions Compared

Old Version 4

New Version Current

Key

Parameters

Overriding parameters

Error handling

Exit events

Authentication options

No authentication

Basic authentication

OpenID Connect authentication

Oauth2 authentication

Customization