02.Apr.18

Dimitar Pechev

Dimitar Pechev

Starting up with Kinvey’s Flex Services

Kinvey is a Backend-as-a-Service provider which offers robust data and user management tools, push notifications, integration with social networking services and more. One other prominent feature is the platform’s custom business logic mechanism, as for most applications it’s not enough to just push and pull data from a backend. There are various cases which require some custom server logic like getting data from multiple collections in one request, acquiring data from external services or even triggering push notifications or other custom logic on predefined occasions. Kinvey offers several ways of creating such wrappers for external data and implementing custom server logic. The Business Logic in-browser code editor and the Rapid Data feature provide a simple way for achieving that goal. These features are configured through your Kinvey Console. However, there isn’t really a convenient way to test that custom code, and you cannot use additional npm modules to get the job done faster. And as the Rapid Data wrappers are configured entirely from a set of static options, it would be hard for you to create some more complex and flexible data mapping. Not surprisingly, the platform offers a solution for that problem as well with the Flex Services.

Flex Services

Flex Services are low code, lightweight microservices that are used for data integrations and functional business logic. Using the kinvey-flex-sdk you can write locally your custom logic in JavaScript with the help of whatever external modules you need and also easily test the code. The introduction for the usage of those services on the Kinvey website is quite descriptive for the most part, however, the instructions on how to wire up the custom code with Kinvey’s collections and custom endpoints is rather vague. So, in this tutorial, we’ll have a look at how that’s done. I will not be focusing on the flex data and flex functions implementation and syntax as that is covered quite well in the official docs.

Flex Data

The Flex Data feature provides a mechanism to integrate any external data, utilizing the vast library of modules from the npm ecosystem. After being configured, it is used as a source for any regular Kinvey collection.

After acquiring the kinvey-flex-sdk from npm, we initialize the flex service, pass the secret key that will later be used for authentication and create a service object that will be used to access our external data. For the sake of simplicity, I will be using a local array of data, however, here would be the place where you make the calls to retrieve the needed data from external sources or from other Kinvey collections. Npm modules like request (for HTTP requests) can be used as you please here.

Another important part is defining the rules how to create, read, update and destory the data when corresponding requests are made. You need to implement each method of this list to define how Kinvey is going to perform the CRUD operations on the data collection. In this tutorial, we'll stick to the minimum: the "onGetAll" handler is called when a GET request for the entire collection is made. The other two handlers in the code snippet are implemented as they are required for viewing the data in the Kinvey Console. 

Before we can successfully deploy the data service to the Kinvey backend, however, we need to configure a Flex Service Runtime in the Kinvey Console. Go to the Service Catalog and create a new service. From the given options select “Flex” and then “Flex Services Runtime”.

kfs-create-services-screen

Then, fill out the required fields. Under “Secret” provide the secret key we used for the configuration of the service (line 11 in the above code snippet).

kfs-create-flex-service

Now, you can deploy the service to your Kinvey backend using the kinvey-cli. After you acquire it from npm, you can check out the detailed instructions on how to perform the operation in the provided link. But in a nutshell, the process includes running the following commands in the Command Prompt in the directory where your custom code lies:

  • login via "kinvey init"
  • associate the flex data service with the runtime you’ve configured with "kinvey flex init"
  • deploy to the server with "kinvey flex deploy"
  • as the upload to the server may take a while, you can always check the progress with the command "kinvey flex job"

Once the service is successfully deployed you can create a Kinvey collection that will be used to access the flex data service. Go to your Kinvey Console and add a new collection. Once you give it a name, you’ll be given the option to use a local data store or a data service. Select the latter and then select the flex service object you created earlier. Don’t forget to click confirm after you have your selection ready.

kfs-create-collection

With that done, you can explore the collection from your application or from the console as if it was a local Kinvey collection.
kfs-collection-view

Flex Functions

The Flex Functions allow you to execute custom server-side logic invoked by hooks or endpoints. In this case, we are going to wire it up with a custom endpoint. And in the example, we have a simple function that returns a hard-coded value just to demonstrate how it works and how to set it up.

After that, we repeat the steps necessary to redeploy the service to the Kinvey backend.  We can this time skip the setup and only two actions are needed:
  • change the version of the package.json - required by Kinvey to keep track of different versions and if needed to fall back to an older one
  • "kinvey flex deploy" - deploy your changes
Then, navigate to your Kinvey Console and from the options on the left select "Custom Endpoints". Create a new endpoint and as type select "Microservice".

create-custom-endopoint

After that, simply select the flex service handler function we configured a while ago and save your changes.

custom-endpoint-config

And with that, the flex function is configured as a source for your custom endpoint! You can test it from your application or the Kinvey Api Console.

kinvey-api-console

 

Need consulting on this topic?

Yes No