Blueriq functions are intended for decoupling smaller calculations. This is what they are good at and should be used for.

There are other scenarios, in which you might consider functions, for which a function may not be the best choice. Below there are some scenarios discussed:

• A function which has side effects. For example when a function stores data in an aggregate or writes data to an external system. This would mean that the outcome of a function can differ after calling it multiple times. This may be confusing to users which expect the outcome to be identical.
• A function which interacts with the process engine. In basis this is the same as above, as the state of the process engine would change, and the result of the function may be different on the second call. In fact using the process engine in a function currently does not work at all.
• A function with complex parameters. When you need to send a complex structure with instances which have relations to other instances and so on, then a web service is a much better option. Functions intentionally have simple parameters.
• A recursive function. You could model a function which calls another function. There is however no mechanism in place to prevent infinite looping and you have to be really carefull on what you do. Therefore this is discouraged.

Modeling

A function call can be compared to a service call in your flow. It behaves more or less the same, except that a different part of the model is used for execution. To use a given function, you create a function call by filling in the input parameters, and mapping the output parameters. Here is an example:

Now, you can place this function call in a flow from which you want to consume the function:

Input validation

When modeling a function, it is possible to check the validity of your input parameters. The input type is always checked, but other validations can be added to the parameters. Please note that when a multi-valued attribute as target attribute, your parameter also becomes multivalued. The validations can be added by adding a validation rule or validation type to the input attribute. This validation will then be triggered when calling the function. When a validation is triggered there will be an error message, on screen for the user when the function is called from within Blueriq or in the JSON result when exposed and called as a webservice.

Exposing the function as a REST webservice

Blueriq offers the option to expose a function as a REST webservice. This is done by selecting the Exposed as webservice checkbox in the properties tab.

When you reload projects in the runtime after saving the flow with this option checked, the function can be approached as a webservice.

The URL of the webservice will be:

http://<environment>:<port>/Runtime/server/api/v2/function?project=<project>&function=<flowname>&version=<branch>&module=<module>

In which <environment>, <port>, <project>, <flowname> & <branch> can be found by selecting the flow and right clicking on the start button on the runtime overview and then copying the link address.

The call to the webservice is a JSON message containing the parameters defined in the function. The HTTP method being called is POST.

For the example used to calculate the loan remainder this would look like:

{
	"LoanAmount":100000,
	"NumberOfYears":5,
	"InterestRate":3.5,
	"MonthlyPayment":500
}

The webservice will also return a JSON message containing the output parameters of the function.

For the example it would look like:

{
	"MoneyOwed":25000
}

Shortcut to exposed function flow

It is possible to make a shortcut to an exposed function flow.

To do this you must add a shortcut in the application.properties with the following content:

blueriq.function-shortcut.{shortcutname}.project=
blueriq.function-shortcut.{shortcutname}.version=
blueriq.function-shortcut.{shortcutname}.module=
blueriq.function-shortcut.{shortcutname}.function=

The url to call the shortcut will be: /Runtime/server/api/v2/function/shortcut/{shortcutname}/

If the property `blueriq.production.shortcutsOnly` is set and the runtime is running in production mode, only shortcuts can be used to start a function.

OpenAPI feed for exposed function flows

An OpenAPI feed of Function Flows exposed as a webservice is provided by the Runtime, see OpenAPI for more information.

Securing an exposed function flow

By default, an exposed function flow can be called without authentication. It is necessary to add at least one role to make sure that the endpoint is secured and the user is authorized. If you add one or more roles to the function flow, the runtime will require credentials via basic authentication.

Further Reading

• Flow type: function