Build.One Documentation
Page tree
Skip to end of metadata
Go to start of metadata

FlexServices is a framework for developing low code, lightweight microservices that are used for data integrations, functional business logic, and integration with custom authentication providers. FlexServices utilizes the Flex SDK.

More information can be found here: https://devcenter.kinvey.com/rest/reference/flex/reference.html


In order to setup a new Flex Service you need to:

For adding Service Objects( that can be used to connect the FlexService with different REST API endpoints ) in the kinvey node project you need to define multiple Service Objects ( see Xentral configuration and service registration as an example )

Kinvey Console

Current Akioma Kinvey console URL: https://kvy-eu3-console.kinvey.com/

From here, you can view/edit applications, services, custom endpoints/functions and test kinvey collections.


Kinvey Configuration


Kinvey Profile Configuration File

First, make sure kinvey cli is installed on your machine. If not, you can use the following command: npm install kinvey-cli

When deploying the Kinvey service locally, you need to have a config file in the current folder from which you are deploying the service. The file name will be '.kinevy'. This will be configured using the kinvey init command.

Once you run this command, you will need to supply your kinvey console credentials and the Kinvey instance ID (optional - in our case this is kvy-eu3).

Alternatively, if you already have a profile configure, you can use it with the command kinvey profile use.


Pasoe Config

In order to connect the application to to Kinvey, we need to set 3 session properties in the pasoe-config.xml file from the ofr-config project: kinveyAppSecret, kinveyInstanceId, kinveyAppKey.

The above 3 properties can be found by selecting an environment within a Kinvey App and clicking on the 3 dots:


After you set the properties in the file, restart the PASOE.


Kinevy Service/Functions

https://devcenter.kinvey.com/rest/guides/flex-services

https://devcenter.kinvey.com/rest/guides/flexservice-runtime

https://devcenter.kinvey.com/rest/reference/flex/reference.html#FlexDataEvents

Flex Service

Flex Events are exposed by the service object and invoked by the kinvey collections. Each event takes a single function as a handler. Events include: onInsert, onUpdate, onDelete, onGetAll etc. See doc above for more details.

Each handler function bound to an event, has the following parameters: : context, complete, and modules.

  • context: current context of the request made to kinvey; here we will find any parameters passed as input in the query
  • complete: handler for completing the data request
  • module: contains several libraries for accessing kinvey functionality


On our end, we define a function for each desired event, then we bind that function to the event:


const sdk = require('kinvey-flex-sdk');

sdk.service((err, flex) => {

const data = flex.data; // gets the FlexData object from the service

function getRecordById(context, complete, modules) {

// flex function implementation

}


// set the serviceObject

const widgets = data.serviceObject('widgets');


// wire up the event that we want to process

widgets.onGetById(getRecordById);

});


Flex Functions

Functions are similar to the methods bound to events. Flex functions are used to execute custom code by either hooks, or in our case, endpoints.

In the code, you can access the flex functions through the functins property: 

const functions = flex.functions;


Then, you can register a custom function using this property:

flex.functions.register('someEventHandlerName', 'someFunctionHandlerName');


Custom flex functions must receive as parameters: (context, complete, modules).


Flex Logger

For logging purposes, Kinvey provides a logging module, which can be used inside handler functions of functions for custom endpoints. It provides different functionality for logging several levels: info(), warn(), error(), fatal().

We can access it using flex.logger.

function deleteOldItems(context, complete, modules) {

const logger = flex.logger;

logger.info('Executing deleteOldItems Flex function');

// flex function implementation

}


These log entries can be accessed from the terminal, using the kinvey flex logs command.


Kinvey Create/Deploy Service

To deploy the Kinvey Camunda service, use the following command: kinvey flex deploy --runtime node12.

NOTE: Each time you redeploy the service, you need to bump the version in the package.json.


After you run the deploy command, you can check de deploy status using kinvey flex status.


For more details, you can use the kinvey flex logs command to see deploy logs or even request logs from Kinvey.

For more details on each commands options, you can use kinvey flex <command> --help


Once your service was deployed, you can check your collection from the API console, under Dashboard →Data (see Kinvey Collections screenshot below).

Here, you can test your collection/service with different requests: GET, POST, PUT, DELETE:



Kinvey Collections

Kinevy collections are essentially data abstractions, representing a group of related data entities. They are defined in the Environment → Data → Collections tab:


To define a new collection, click on Add collection. Then, select the data service, environment and service for which you want to define a collection for. Finally, click on activate service.


Collections will be used to make data available in the application UI, in grids. This will be explained below.


Kinevy DSO Setup

After we set the Kinvey parameters in the pasoe-config.xml file and we define a kinvey collection, for the dataSource we can use the SimpleSwatBusinessEntity.

Here, we would need to set 2 attributes:

  • SUBTYPE : 'KinveyCollection' (without the quotes)
  • resourceName: name-of-camunda-collection

Then simply create a DATA link from the DSO to the grid and you should be able to see the collection data.


Kinvey Custom Endpoints

Custom endpoints are defined on the Application Environment settings. They can be called from the frontend using akioma.InvokeServerTask. A custom endpoint is linked to a service flex function. Essentially, when a custom endpoint is called, we are calling the the flex function defined in the service.

Custom endpoints can be defined on the application environment from the Business Logic → Custom Endpoints:


Click on the add new Endpoint button, give the new endpoint a name and select the Business Logic Type.

In our case, that is Microservice (Execute a handler function running inside a Flex Services Runtime service).

Once the endpoint is created, select the service, then environment and finally the handler function:

Kinvey Calling the Custom Endpoints

Calling a Kinvey custom endpoint is done using akioma.InvokeServerTask.

The only thing we need to specify is the methodType: "kinvey" in the request and the name of the custom endpoint in our, case "completeTask".


akioma.invokeServerTask({
       name: "completeTask", 
       methodType: "kinvey", 
       paramObj: { 
               id: "id-of-task"
       }
})
.then(resp => { //process response// }  );



Digest-Fetch

Digest-fetch is a plugin used for fetch/node-fetch. We make use of it for the event handler functions. It also supports http basic authentication.


Local Development

Kinvey Flex Services could be tested locallly.

Prerequisites: 

  1. nodemon: the tool for hot-reload https://www.npmjs.com/package/nodemon
  2. ngrok: the tool for public port exposing https://ngrok.com/download (don't forget to setup auth token)


Setup:

  1. Go to the project root folder (flex-services)
  2. Launch nodemon at any empty port (in this case it's 10001): nodemon . localhost 10001
  3. Launch ngrok and expose port: ngrok http 10001
  4. Create an external flex service 


Put your public url from ngrok to a host field at flex service:

Link the collection to your flex-service

Use public url for requests same as application (Build.one UI) sends them:







  • No labels