Make a Business Service Call

Introduction

A new module is introduced in Axelor Connect 3.0 to call APIs developed in enterprise or client projects.

Configuration

Make a Business Service Call module introduces a set of components which can be used to configure the web services called from Axelor Connect.

@Connect

An annotation to add on the methods exposed to Axelor Connect.

@Path
@POST
@Connect(
    name="Create order", (1)
    description = "Create order from Axelor Connect", (2)
    tag = "Sale" (3)
)
public void create() {
    // implementation...
}

java

1	Required, it takes a unique and descriptive name for the web service.
2	Optional, describes what the web service does.
3	Required, defines to which module the action belongs to.

The tag is a key used to group the web services you want to expose to Connect, even if they have different characteristics:

Functional module: Sale, CRM, BPM, Project…
HTTP method: GET, POST, DELETE…
Related model: Product, SaleOrder, User…

It is recommended to define a string constants for tag name instead of using hard-coded values.

Scan package

At startup time, the context scans the AOS package com.axelor.apps by default to extract all the tags defined within it.

To scan a custom package during startup, override the method getPackagesToScan of class ConnectWebServiceServiceImpl:

public class ConnectWebServiceServiceCustomImpl extends ConnectWebServiceServiceImpl {

  @Override
  protected Set<String> getPackagesToScan() {
    Set<String> packages = super.getPackagesToScan();
    packages.add("com.customer");
    return packages;
  }
}

java

Then bind it in the module configuration:

@Override
protected void configure() {
    bind(ConnectWebServiceServiceImpl.class).to(ConnectWebServiceServiceCustomImpl.class);
}

java

Rules to follow

Use DTOs: In the controllers, it is recommended to not use the persisted entities as entry of the methods, instead define custom DTOs.
Constructors: Ensure the DTOs have a default constructor to bind the incoming JSON data properly.
Required field: To set a field as required, add on it the annotation @NotNull from java.validation.constraints package.
Min & Max: The annotations @Min and @Max are managed by the module to set the min and max values for fields of type number or length for text fields.
Query parameters: To bind query parameters automatically, use the annotation @QueryParam.
Path parameters: To bind path parameters automatically, use the annotation @PathParam.
Header parameters: To bind header parameters automatically, use the annotation @HeaderParam.
Body: The parameter representing the body of the request requires no specific annotation.

Use case

Let’s configure an API endpoint to create a product from Axelor Connect using Call a business service module.

Create the API

Create the DTO

class ProductDto {
    @NotNull
    private String code;
    private String description;

    @Min(5)
    @Max(100000)
    private String price;
}

java

Create the controller

The API should be defined in a controller with the annotation @Path.

@Path("/store")
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
public class ConnectStoreController {

    @POST
    @Path()
    @Connect(name="Create new product", tag="Store")
    public Response create(ProductDto productDto) {
        // business logic...
    }

    @PUT
    @Path("/{id}")
    @Connect(name="Update product", tag="Store")
    public Response update(ProductDto productDto, @PathParam("id") Long id) {
        // business logic...
    }
}

java

Don’t forget to add the annotations @Consumes and @Produces from javax.ws.rs package. The connect app needs them to fill the headers properly. You can put them on the class or on the methods.

Axelor Connect

From Axelor Connect, follow the steps below:

In your scenario, Click on add module icon.
Search for Axelor 3.0 app.
Search for Make a Business Service Call module.
From the module configuration, add the connection.
The list of modules will appear in selection input.
Once you select a module (i.e. Store), a dropdown menu appears to select an action.
Select an action (i.e. Create product). The full form opens.