This chapter describes how you can setup Blueriq, so that it exposes itself as a web service. This means that other parties are able to call Blueriq and that Blueriq will formulate an answer. You can both use Blueriq as a SOAP and REST service. What type exactly does not matter for most steps this chapter.
You start with the same steps that you would take when you would call a web service. This means that you have to import a WSDL for SOAP or import an XSD or define a Domain schema for REST. These steps are described in 4. Calling a SOAP service and in 5. Calling a REST service. The main difference is that everything you define is for your own web service. This means that the WSDL you import will be yours, you are able to define it yourself. (For more information on this, see Appendix 1 - Writing your own WSDL). For REST, the Domain schema or all the imported XSD and defined fragments and arguments will be for your own web service. The main conceptual difference when using the REST service editor is that the request message now defines the message that you receive, and the response message is the message that you are sending as a response to the other party. This is exactly the opposite manner compared to when you call an external web service.
When calling an external REST service, you can place the status header in an attribute, which holds the status code of a the response. For BAARS, this is not an output parameter but an input parameter, and you can set the status code of the response yourself. A good use of this functionality is for instance to set status code 201 when you created a new entry in the system (for example when the Service call type: AQ_Aggregate_Create service was used)
Expose the REST or SOAP service
After you are done, it is time to expose your webservice. For this you need a configuration module. In this configuration module, create a new web service. The name of this web service is important, as it will be used in the base URL that Blueriq will generate to consume this service.
First, select the module in which your REST or SOAP service is defined (service module), and then the service definition (this is your REST or SOAP service). You can specify whether the webservice should validate the dynamic fragments/arguments and validations that are defined in the domain schema or schema set.
After selection of the service definition, a list of services within this SOAP or REST service will appear. Obviously, only exposed operations can be called.
You can optionally specify extra options for your web service:
You can specify a data mapping, which is located in the same configuration module. If your web service is located in a different module than your business logic, you need to make a data mapping between the two modules.
Attention: the module with the business logic needs to be set as entry point in this case!
You can specify a flow which will executed when your web service is called. For example, in this flow you can use other external sources or even call a different web service. There are no pages allowed in this flow.
You can also specify roles that a user should have.
Save, and your web service is ready to use. Go to the runtime dashboard and reload your project. Go to 'Widgets' and activate the 'Exposed Blueriq webservices' widget.
Select your project and choose the web service. If you expose a SOAP service, then you can view the WSDL of your SOAP Service, in which the correct URL location can be found.
Now you can call your web service, for example using SoapUI.
If you exposed a REST service, then the REST service URL will be shown. You can test your service by pasting this URL in your browser.
In case the validation checkbox is toggled in the service definition, the created validation rules are taken into consideration. So the message is checked and gives either the requested information or a validation message. These validations will be returned per attribute or for the entire request.
For example, let's say that there are two attributes in the request: Request.Attribute1 and Request.Attribute2 with the following Validation rules:
- A validation rule which validates that Request.Attribute1 has a value between 1 and 5
- Another validation rule which validates that Request.Attribute2 is greater than Request.Attribute1
When the request is made having Request.Attribute1 = 3 and Request.Attribute2 = 2, the first validation rule is true but the second validation is violated and in the response, an error message will be returned having the validation message stated. This works for both validation rules as well as for validation types.
Shortcuts
It is possible to create a shortcut for yourwebserviceso that location URL is shorter and hides details such as the branch. This also gives you the flexibility to change the application that the shortcut is pointing to without the need to change the URL in calling systems.
Read more about how to configure a shortcut here. For webservices, there is no need to select a flow, and other settings such as User Interface or Theme are also not important now.
Such a shortcuts looks like this in the application.properties:
blueriq.shortcut.ShortcutName.flow= blueriq.shortcut.ShortcutName.languageCode=en-GB blueriq.shortcut.ShortcutName.project=studio-Web_Calculator-WebCalculatorAAAS blueriq.shortcut.ShortcutName.theme=blueriq blueriq.shortcut.ShortcutName.ui=xslt blueriq.shortcut.ShortcutName.version=0.0-Trunk
Now you can select the shortcut in the 'Exposed Blueriq webservices' widget on the runtime dashboard, and view the new WSDL. You will see that the location of your webservice was changed and now uses the shortcut.
OpenAPI feed for REST services
An OpenAPI feed of REST services is provided by the Runtime, see OpenAPI for more information.
Previous: 5. Calling a REST service
Overview
Content Tools