Skip to Content
Technical Articles
Author's profile photo Piotr Kurzynoga

Creation of an Offline Custom Business Object

In this blog the following topics are covered:

  • Creating an Offline Custom Business Object
  • Creating content for the Custom Business Object
  • Going Offline for the first time!
  • Debugging tips and tricks.


Creating an Offline Custom Business Object

We start by creating a Business Object and inserting the annotations.  [OfflineEnabled][WithAdministrativeData(IncludeSubnodes)]

The tag [WithAdministrativeData(IncludeSubnodes)] identifies the delta changes which are required for syncing the data Offline.

Note: If you are enabling an already existing Custom Business Object for Offline, you will have to update each screen separately to generate the required metadata for Offline, this involves opening the screens in the UI Designer and re-generating the metadata.

Before the new BO can be saved we need to define at least one element on the root node.


Offline Custom Business Object structure

Save & Activate the newly created Business Object

The next step is to create the screens. The following pop-up will show:



Screen Generation

You will notice that the Thing-based Navigation screens are being generated and the option for Object Based Navigation screens is not possible (This is because only Thing-based navigation is supported for offline).

Let’s create a Before-Save event script on the Root Node and a Validation event on the Item Node


Creating content for the Custom Business Object

Note: In order to create a script for online you will have to mark the checkbox in the “Create” column on the left-side.


Script Creation

Let us populate the Validation event with some code:

In this case if the price is less than 5 the validation should not go through i.e the Item should not be persisted into the database.

Now let’s do the same for the Before-Save event, here we are setting a Fixed price on the item from the Root level.

Now we will activate both of the scripts (BeforeSave and Validation) and proceed to test the functionality from the UI.


Going Offline for the first time!

To open the test offline environment you will have to modify the URL adding the following:

You will be asked to create a passcode. This is done so that users on mobile devices can access the environment quicker.

When we expand the user drop-down, the “Go Offline” button will be greyed out. Before going Offline a Synchronisation has to be performed to download the content that will be used while the user is in the offline mode.

You can view the content that will be downloaded by going to the “Offline Settings”. More detailed configurations can be accessed by navigating to the Administrator WorkCenter > General Settings View and opening the Offline Settings screen (this will be covered in a separate blog in more details).

For this scenario to enable the data download for our Custom Business Object we add it to the Data Download Rules, by clicking Add and selecting the required parameters.

Before performing a sync and going offline the WorkCenter Floorplan and WorkCenter View has to be assigned to the Business User.


The OWL can now be accessed. However, since there are no instances available, let’s perform a sync and go offline where we will add an instance.


To perform the sync you can either click “Sync Now” in the user drop-down or simply click the Sync button in the top right corner.

The progress of the sync can be monitored by clicking the Sync button once again.


As per the warning message when performing a sync on a mobile device do not close the application as this will impact the sync.

Once the sync is finished we can now “Go Offline”

Once in Offline mode you will notice significantly less WorkCenters available, and the “Go Offline” button is now called “Go Online”.

Let’s create an instance in the Custom Business Object.

You can notice a little orange identifier beside the UUID, this means that the particular instance was created while being Offline and is not Synchronized.

The Sync Button also has a notification available informing the user that there are synchronized changes (Note: Automatic synchronization occurs depending on the configuration).

Having performed the Sync, let’s return back to the Online environment by pressing the “Go Online” button in the user drop-down.

We can see that the instance is now available and the orange identifier is gone meaning the instance is persisted into the database.

There is also a log available which features all the changes that were made during a sync. You can view by navigating to the Offline Settings (from the user drop-down) and inspecting the “Upload Sync Log”.

3 different filters are available, which can aid in troubleshooting should a sync of an instance fail:

  • All Uploads
  • Last Upload (Used in this example)
  • Upload Errors

Click the magnifying glass to directly navigate to the processed instance.



You can access the generated scripts from the Developer Console in the browser, to find the particular script search for the solution Y name.

Note: The scripts will only be available when the particular Business Object instance is opened/is being created.

You can see the JavaScript representation of our Before Save script above. We can debug the same by setting a breakpoint directly in the generated script.

Let us test if the validation message is raised for the Item node correctly in the Offline environment.

The same message would not be raised once we go online as the script only exists for the Offline environment!

Note: It is important to understand that during a Sync the Online Scripts will be called, hence if the coding is not reflected in both Online & Offline scripts the data can vary between the Online and Offline environments.


Thanks for reading, more information to come with the next blog series!


You can find the parent blog here:

Piotr Kurzynoga.

Assigned Tags

      You must be Logged on to comment or reply to a post.
      Author's profile photo Anant Acharya
      Anant Acharya

      Nice Blog Piotr 🙂

      Author's profile photo Piotr Kurzynoga
      Piotr Kurzynoga
      Blog Post Author

      Thanks Anant !

      Author's profile photo Deepty Mohnani
      Deepty Mohnani

      Thanks for writing this:)
      Very nice documented!

      Author's profile photo Piotr Kurzynoga
      Piotr Kurzynoga
      Blog Post Author

      Thanks Deepty 🙂

      Author's profile photo Mithun Panchal
      Mithun Panchal

      Nice blog......

      Author's profile photo Jens Limbach
      Jens Limbach

      Piotr Kurzynoga : Really cool to see a very nice blog on this! Well done!

      Author's profile photo Piotr Kurzynoga
      Piotr Kurzynoga
      Blog Post Author

      Thanks Jens!

      Author's profile photo Amrit Bansal
      Amrit Bansal

      Nice blog!!

      Author's profile photo Jacqueline Hemmimghaus
      Jacqueline Hemmimghaus

      Nice blog!


      But how do you define which data is synched? We`re currently facing the problem, that when you create an instance of a custom BO offline, which has some subnodes, and change data also in the subnodes only the root elements are synched and the data in the subnodes is lost.

      Further, can you check in the online script if the current script run is because of a synch process or triggered by an online created instance?

      Author's profile photo Anil Kumar Rana
      Anil Kumar Rana

      Hi Jaqueline,

      could you please check the help document on Enabling Custom Objects for Offline Use and see if you have set all the annotations for your Business Object? Ideally the synchronization should happen for all nodes.

      I am not aware of an element which could be used to indicate if a Business Object instance was created via online/offline or a way in a script to determine what kind of a Business Object instance it is. I would suggest putting this as an idea in the influence forum

      It is a good requirement!

      Best regards,


      Author's profile photo Jacqueline Hemmimghaus
      Jacqueline Hemmimghaus

      Hey Anil,

      yes I followed that guide. I also debugged the synch process and only the scripts of the root node are called. The ones in the subnodes are ignored.

      if I create the instance offline, don't change anything, do a synch and afterwards change something in the subnodes, those changes are considered in the next synch. So is it worth a ticket?


      Me neither. I thought we can use the information in the administrative data, which is added by the annotation, but this node is empty. So I will open up an influence ticket.



      Author's profile photo Anil Kumar Rana
      Anil Kumar Rana

      Hey Jaqueline,

      during the sync process, the online scripts of the sub nodes were ignored even though a change was done on one of the elements on those nodes?

      Ideally, all of the content should be synchronized during the first run. The way it is currently working in your constellation, doesn't sound right. I would suggest opening a ticket with providing all the details as outlined here and I will have a look.

      Regarding the administrative data, I would assume the elements underneath the node are not PSM Released.

      Hope this helps!

      Best regards,


      Author's profile photo Jacqueline Hemmimghaus
      Jacqueline Hemmimghaus


      it is already opened: 8568/2021
      I'll check if I missed some information in the ticket 😉