Server-side code execution

Writing backend services

Overview

The typical Dynamics Mobile application may be considered as client-side code. The code is executed on the client side, either in a webview histed inside a mobile native app or in a web browser.

The Dynamics Mobile backend apps are hosted in a web browser and all of the interactions with the service side are client side calls to a REST API hosted on the service side.

This concept works for most scenarios , but it comes with certain "cost" - performance. Each REST API call takes time and sometimes we might need greater performance, faster REST API calls.

In such cases we might use the server-side code execution concept - e.g. write the code in such a way that it will be executed on the server side. This allows to package a big number of API calls in a server-side calls and expose them as a single API call. We can even embed some complex logic inside and use it by making a single API call to the server by passing certain input arguments and receive certain output.

Server-side Code

The server side code must be places in a special file under the ./src folder of the app called backendservice.ts This file must:

• contain one exported default class called BackendService, which extends ApplicationBackendServiceBase

• export @dms module

• export @dms-bo module

The BackendService class must implement at least one public async method called processEvent

Having this class in your backend app, will make Visual Studio Code to utilize a special compilation routine to turn this code into server-side code. This will package and make the class executable on the server side.

Make sure you don't use USER INTERFACE features like UserInterfaceService, JQuery, DOM manipulations and other APIs which works only in the browser. Otherwise your will be compiled, but will fail when executed on the server side. Make sure you do don't use other classes which in turn rely on UI processing.

Server-side Events

Once compiled and uploaded to the server, the BackendService class will be executed on various "places and moments". These "places and moments" are designated as events.

The BackendService's processEvents method will be called on the occurring of the following events:

• system:schedule:tick

This is a system event, which occurs on a predefined time interval. This must be used be the server-side code developer to attach a server-code to be executed periodically. The current time interval is 15 minutes. Note that the system does not guarantee hard time interval. The interval is not guaranteed and it might happen for the system to miss certain calls. The server side code must compensate such occurings.

• system:api:inbound

This is a system event, which occurs whenever an external client ( program, script) calls the Dynamics Mobile external REST API. The externa rest API is accessible on the following urls and http methods: GET http://api.dynamicsmobile.com/api/livelink/app/:APPCODE/:MyRESTservice PUT http://api.dynamicsmobile.com/api/livelink/app/:APPCODE/:MyRESTservice POST http://api.dynamicsmobile.com/api/livelink/app/:APPCODE/:MyRESTservice

APPCODE is the application unique identifier of your backend application. MyRESTservice is the name of the service or method from your app which is called. When an external script calls the given url with any of the allowed http methods, the system will call your BackendService.processEvents method and will pass the actual name of the MyRESTservice parameter. You can then decide what to do depending on the actual http method and MyRESTservice value

This mechanism can be used to package a complex business logic which requires large number of API calls as a single API call.

• system:packet:push

This is a system event, which occurs whenever a push JSON packet is received on the server side. The mobile applications created with Dynamics Mobile send data changes like record insertions , record updates or other "interesting" events, which require server processing. These interesting events are sent as Sync Packets. The Sync Packets are generally JSON array of objects with well known structure. The actual packet structure - e.g. the fields of the objects depends on the actual mobile application.

The server-side code is the called on every packet push and the system passes the actual packet content to the BackendService.processEvent method. The processing may analyze the content and create, and update records on the backend.

Best practices

There are certain best practices and hard limits, which you shall have in mind when writing server-side code:

• Don't use user interface related code in your backend service ( like DOM manipulations, calls to "window" object , calls to jQuery and others).

• Keep minimum logic in BackendService class - move the actual business logic to external classes and functions and call them inside the BackendService class

• Do not return more than 4Mb as a response from your system:api:inbound call.

• Your code can not run for more than 30 seconds. It gets killed after.

• Use Unit Tests to bullet-proof your BackendService class.