Blog post | Mendix Offline-First

I T V I S O R S | B L O G P O S T

Why offline first apps?Limited or lost connection

When a person steps into the elevator or walks into a parking garage, places where internet is limited, they expect their apps to keep working. In crowded area’s a connection can be limited, but also here a person expects his app to keep wor-king smoothly. The problem with an online app is that the app would break as soon as the connection is lost.

An offline first app will keep on working and synchronize with the backend whenever possible. The app does not keep an open network connection. Pages and data do not need to be retrieved from a backend. Not only is this an advantage in enabling a user to work in all places it also prevents a synchronization to the server after every action. Therefore it’s also a massive performance improvement and even on a fast Wi-Fi network the response times of the app improve tremendously.

IntroductionWhy would we want offline apps in a world where everything is connected? The reasons are actually quite simple. We will go into more details of each of them. This blog post also summarizes the items presented on the MendixWorld breakout session about Offline-First.

I T V I S I T O R S | B L O G P O S T

Synchronization

To keep the server date synchronized with the app data, the offline app will synchronize all relevant data whenever an internet connection is available. Currently, there are two levels of synchronization, each described in more detail below.

Automatic synchronization

This is the basic level and the only option for Mendix 7. The Mendix model looks through the navigation profile and recognizes entities used on pages accessed through the offline navigation profile. Data retrieved in nanoflows using the Retrieve activity is also considered. Of course, entity access rules govern which data the user will have on the device.

Configurable synchronization

Quite often the app user is allowed access to more data than what is needed on the device, for example last year’s sales orders. A new exciting option in Mendix 8 is that it’s possible to configure custom sync options quite easily from the modeler, allowing you to limit the data that is stored on the device. Note that the entity access rules still apply. The synchronization can be configured through the navigation profile.

For those entities where you want to synchronize less than what the user is authorized to it is possible to specify an XPath constraint on the entity. In this example, we only want the account of the current user. Data that has ‘moved on’ in the business process, and is marked as online only, should also not be available on the device anymore.

More synchronization features to come

In addition to specifying XPath constraints, more synchroniza-tion features will come:- Calling a microflow, which could not only return a list of objects but an entire object structure- Calling REST services, on the app backend or even other systems

These features will allow you to handle more complex tasks, a few examples:- Maintain a synchronized copy of master data on the de vice by synchronizing only changes- Updating master data upon request only while synchro- nizing transactions whenever possible

I T V I S O R S | B L O G P O S T

How does ITvisors help you?Nanoflow Commons ITvisors Appstore module

The Nanoflow Commons ITvisors module provides you with several functions to make life easier when developing offli-ne-first apps.

GetOffline actions

The GetOffline… actions allow data retrieval functionality with combinations as is possible in microflows, but not (yet) possi-ble in nanoflows like retrieve over an association, filter on ano-ther attribute and sort the result.

For simple use in a nanoflow, you can retrieve:- A list- The first object that matches the criteria- The total count of objects rather than the full list

Note that, similar in the case of retrieving objects from a data-base and count, the Count action is more efficient in use than retrieving the actual objects and counting them.

For basic usage, the GetOfflineBasic functions (First, List and Count) allow you to specify up to three search criteria and sort values. Attributes and associations can be used to search up on.

Nanoflow Commons

Nanoflow Commons contains a great collection of functions that will make your developers life easier, some examples:

- Showing a confirmation dialog from a nanoflow and waiting for the result- Calling a phone number- Opening the map on the device- Getting the current location

Native Mobile Actions

Native Mobile Actions extends the list even further with actions for use in native mobile apps. Some examples:

- Take a picture or access the picture gallery from a nano- flow. There is no need for a custom widget anymore- Checking the network connectivity- Access device info- Various notification functions- Set a badge number on your app icon

Sub nanoflow callsFinally! One of the major burdens in Mendix 7 was that you could not reuse nanoflow functionality, calling a sub nanoflow wasn’t possible. Many times this results in a lot of duplicati-on and huge nanoflows. Within Mendix 8 it is possible to split them up in manageable chunks and re-usable functionality.

JavaScript actionsAs of Mendix 8, you can create custom JavaScript actions in the same way as the Java actions we already use in microflows. This opens the device environment to access device features or work beyond limitations of current nanoflow functionality. Also, actions for which we needed a custom widget can now be done from a nanoflow, like taking a picture or checking whether we have a connection. Mendix already did a great job by supplying a bunch of JS actions. We even had a MVP JS action hackathon around this theme, which was great and lots of new JavaScript actions were developed.

Please note that if you used the Native Mobile QuickStart app to create your app, you will already have these JS actions. However, the modules are updated frequently, so keep an eye out for them.

The next constraint is an attribute, we only want images with content. So, that is done here.

Note that each constraint can be negated.

For a constraint on an enumeration value, you need the enumeration key. For getting the enumeration key, a separate JavaScript action is available too. However, Mendix 8 also al-lows you to use toString() as well.

Up to three sort criteria can be specified, these must be attri-butes of the entity being retrieved. For each sort value you can choose to sort ascending or descending.

GetOfflineBasicListThis action is the same as GetOfflineFirst but returns a list of objects. It is possible to specify an offset and a limit, when leaving this empty it retrieves the entire list.

GetOfflineFullThe get offline full actions allows to take full advantage of the Mendix client API function GetOffline. It is on this documenta-tion page. Just scroll down or search for it on the page.

The actions have the same parameters, the constraints and fil-ter JSON as strings. The Mendix documentation page, which I mentioned earlier, has several examples on how to use the API.

For GetOfflineFullFirst, don’t forget to include a zero offset and a limit of one in your JSON to prevent a poor performing re-trieval action.

Together with the power comes great responsibility: The Ge-tOffline… JS actions are little more than a front to the Mendix client API function. This places the developer in direct control, therefore the developer has to deal with errors sent from the Mendix API himself.

Show pageShow a page using a variable for the page name. This is useful when writing reusable modules. It allows you to configure the page in your database or in a constant.

In the backend you can call a microflow dynamically using functions in CommunityCommons. However, a nanoflow can-not be called by its name. But you can open a page, containing that nanoflow.

Supporting functions- Date to milliseconds, for retrieving data while filtering on a date- Format date/time- Format decimal- Get enum key or value, for retrieving data while filtering on an enum key

GetOfflineBasicFirst

As an example, the GetOfflineBasicFirst action is explained here in more detail.

The screenshots are from one and the same action in the nanoflow, explained step by step. Start by specifying the entity which needs to be retrieved. Then specify the constraints.

The first constraint is an association. Here it’s needed to supply the full association name: module.association.

To compare against an association, use the GUID of the other object, in this example that would be a TaskFormElement.

The Nanoflow Commons Appstore module has a Get Guid action which can be used to get the GUID and store it in a variable so you can reference it here.

I T V I S O R S | B L O G P O S T

My experiences creating offline appsA clean business process is key

Online apps have one advantage: there is a single database for all users to work with.

As soon as you take data offline, you need to be aware of synchronization issues.

The easiest way around this is to assign the items to the device user, so other users cannot change it. For example, by assig-ning tasks to users and constraining it so only the assigned user may change the task data.However, there may be situations where this is not that easy to realise. In that case, you need to design your business process carefully, considering that some key user may need to integra-te work of several other users. For example, you could create mutations rather than changing objects, allowing you to wrap up the mutations into a new version. This all depends on the business model of the organization.

Double check your entity access

Quite often, users are authorized to use much more data than they really need. By restricting this and setting custom synchro-nization options you can drastically reduce the amount of data being transferred to the device.

Sync debug page

When using custom widgets or JS actions, the model might miss entities in the synchronization. It is possible to manually add them to the synchronization configuration. However, it’s better to see all the data in the device during development and testing. Especially master data and other data that are not directly visible in device pages.

For this purpose, I create a sync debug page, which holds all data relevant for the offline app. It is on the main page or menu, but hidden trough a flag on the account. This way, the user will not see it when working with the app, but it is possible to see all data on the device during development.

How does that help:

- See whether your entity access and sync configuration are setup correctly- The model will easily see all required entities - Debug your offline app by checking whether the data is created or processed correctly- Prove to the customer that sensitive data really is removed after processing

Use an icon on entities used in the offline app

Especially with larger projects and teams, not all team members will know what the offline part of the Mendix app does. The domain model allows you to choose an icon for your entities. By setting a specific icon on each entity used offline, the entire team will know that the entity is used in the offline app.

Don’t rename or delete entities used in the offline appThis is most important for projects that are already live.

When you rename an entity or module used in an offline app, the offline app will break with errors about missing entity access or missing objects.

This can only be solved by removing the app from the device and adding it again.

So, in short:- Do not rename or remove attributes or associations used in the offline app - Do not rename entities or modules used in the offline app- Basically, you can only add new stuff

You may be able to get rid of attributes or associations that are no longer used throughout the model, but make sure to first remove any usage and transfer to production. Now you can remove the old stuff. Still, tread carefully here and test each step extensively. This is really tricky!

Deleting dataIn the offline app

You cannot delete data in an offline app. What you can do is set a flag or a status, so it is no longer visible in the app, and no longer synchronized as well using the custom synchronization options. In the backend, a clean-up job can remove the data.

Note that in many situations you are not allowed to delete data anyway for auditing purposes.

In the backend

You will get synchronization errors when a back-office user de-letes data that another user has changed while being offline.Again, it is important to start with a well-designed business process.

Wrapping it up

Mendix offline apps provide you with the power to create gre-at apps. There is a noticeable difference when clicking trough an app, especially response times on the device are improved. This way, the new React Native apps make way for a better user experience.

The offline-first approach helps you in keeping that app going not influenced by the environment.

We can help you in developing these apps even more easily.

Go make it!

itvisors