App Events: Notify internal Staff live via User input (Technical Details)
This article describes the implementation and configuration of the "App Events" feature in the Innosoft Mobile App.
Table of Contents
Introduction
Support for App Events has been added with app version 2.7.1 and app backend version 2.7.2. This feature allows certain user actions (events) within the app to be transmitted to the app backend and stored in a database table. This process takes place at the moment of occurrence and independently of the app's usual synchronization process to ensure increased responsiveness to specific actions. The collected data can then be analyzed or further processed either immediately or later on.
Activating the feature
To enable App Events as a whole, a row must be entered in the Phx_Server_Settings table with the value appeventconfiguration for the ID column and the value {"appEventsEnabled":true} in JSON format for the VALUE column.
INSERT INTO PHX_SERVER_SETTINGS (ID, VALUE)VALUES (N'appeventconfiguration', N'{"appEventsEnabled":true}');Capturing location data
It is possible to transmit the current location with each event. This feature is only available for Android and iOS platforms.
To add location data to events, the requestLocation property must be added to the JSON object with the value true. To do this, the app must be granted the appropriate permissions to collect location data.
INSERT INTO PHX_SERVER_SETTINGS (ID, VALUE)VALUES (N'appeventconfiguration', N'{"appEventsEnabled":true,"requestLocation":true}');When this feature is activated for the first time, the app displays a dialog box in which the user can grant the necessary permissions. Alternatively, permissions can also be set manually via the operating system's app settings or via the settings within the app.
Supported actions
The actions that trigger events in the app are predefined. One exception is the creation of time stamps, which are only triggered for configured activity types. The following describes the currently supported actions that can trigger App Events:
Overview of supported actions
Starting the timer on the time tracker: This event is triggered as soon as the timer on the time tracker is started.
Creating time stamps for certain activity types: This event is triggered as soon as a time stamp is created in the app. This can be done via the time tracker or in the service reports view. For this activity type, you can configure whether or not an event should be triggered.
Signing service reports (differentiated by technician and customer): This event is triggered as soon as the technician or customer has confirmed their signature in the signature dialog.
Completion of service reports: This event is triggered when the service report is completed using the corresponding button in the completion tab.
Completion of an assignment: This event is triggered when the checkbox for job completion is selected in the completion tab of a service report.
Architecture overview
The architecture of the new App Events feature consists of several components that work together to capture user actions, send them to the backend, and store them in the database.
Overview of components
App
Event service: This component monitors certain user actions within the app. When a supported action is detected, an event is triggered. Once an event has been triggered, this component sends the relevant data to the backend.
App-Backend
API endpoint: The API endpoint receives the events sent from the front end and processes them further.
Event handler: This component is responsible for processing the received events. It extracts the relevant information and stores it in the database.
Database
Phx_AppEvents: This table stores all recorded app events.
Phx_AppEventConfiguration: This table contains the configuration specifying which activity types should trigger an event.
Database structure
This section highlights the two database tables Phx_AppEvents and Phx_AppEventConfiguration.
Phx_AppEvents
This table stores all recorded App Events. Each row represents a single event with relevant details such as time, action type, and user information.
|
Column |
Type |
Nullable |
Significance |
|
Id |
nvarchar(50) |
No |
Unique GUID for the event. |
|
CreatedAtUtc |
datetime |
No |
Date and time when the event was created in UTC. |
|
CreatedAtLocal |
datetime |
No |
Date and time when the event was created locally in the app. |
|
TransferredAtUtc |
datetime |
No |
Date and time when the transfer was completed (in UTC). |
|
RessNr |
nvarchar(10) |
No |
User's resource number. |
|
AssignmentId |
nvarchar(50) |
Yes |
ISGUID of the associated assignment. This value is only null for the TimeClockStarted event and is otherwise always set. |
|
Payload |
nvarchar(-1) |
Yes |
Additional information about the event in JSON format. For details, see the explanation below. |
|
EventName |
nvarchar(255) |
No |
Type of event. For details, see the table below. |
|
Latitude |
float |
Yes |
Latitude of the geographic location of the event. |
|
Longitude |
float |
Yes |
Longitude of the geographic location of the event. |
The EventName column can have the following values:
|
EventName |
Description |
Payload |
|
WorkLogCheckpoint |
Saving a timestamp for a defined activity |
{ activityTypeId: string, begin: string, end: string, serviceReportId: string } |
|
WorkLogEnd |
Saves a timestamp for a defined activity and signals the completion of an assignment or service report. |
{ activityTypeId: string, begin: string, end: string, serviceReportId: string } |
|
TimeClockStarted |
Start of time recording via the time tracker. |
No Payload |
|
TimeClockStopped |
End of time tracking via the time tracker. (from app version 2.8.1) |
No Payload |
|
AssignmentCompleted |
Assignment completed (e.g., in the Closure tab). |
No Payload |
|
AssignmentNotCompleted |
Completion of the assignment was canceled (e.g., checkbox in the Closure tab was reset). |
No Payload |
|
ServiceReportSignatureTechnician |
The technician has signed off on it. |
{ serviceReportId: string } |
|
ServiceReportSignatureCustomer |
The customer has signed. |
{ serviceReportId: string } |
|
ServiceReportCompleted |
Closure of the service report. |
{ serviceReportId: string } |
Example Payload
This Payload could occur during the WorkLogCheckpoint event:
{
"activityTypeId": "31af2dd3-f57c-46cf-8187-bd4cf3c8127b", "serviceReportId": "c4679b7d-8c48-457f-9bf8-45c0e42853f1", "machineId: "296b83db-66eb-451e-a524-bbf6d439c25e" "begin": "2025-05-05T08:00:00+02", "end": "2025-05-05T12:00:00+02"
}
Explanation
activityTypeId: This value is a string and corresponds to the ISGUID column from the TimeTypes table. It specifies the service report from which the event originated.
serviceReportId: This is also a string and corresponds to the ISGUID column from the LBKOPF table. Please note: This ID may not yet be available in LBKOPF at the time of the event, as the service report only exists on the app at this point and synchronization has not yet taken place.
machineId: This is a string or null and corresponds to the ISGUID column from the MAPARK table. If the machine is not available for the activity type or is not set in the form, the value is null.
begin: This value is a string and specifies the start time of the activity in ISO 8601 format (e.g. 2025-05-05T08:00:00+02).
end: This value is also a string and specifies the end time of the activity in ISO 8601 format (e.g. 2025-05-05T12:00:00+02).
Phx_AppEventConfiguration
This table contains the configuration for the activity types that are to trigger an event. It allows you to customize the events for time recording without making any changes to the code.
|
Column |
Type |
Nullable |
Significance |
|
ActivityTypeId |
nvarchar(50) |
No |
Activity type for which an event is to be triggered. |
|
EventType |
nvarchar(255) |
No |
Event type with possible values WorkLogCheckpoint or WorkLogEnd. |
Explanation
ActivityTypeId: This column corresponds to the ISGUID from the TimeTypes table and specifies that an event should be triggered for this activity type as soon as the user has created a time stamp with this activity type.
EventType: This column specifies whether only the event is transmitted (WorkLogCheckpoint) or whether this activity type should also signal the end of the service report (WorkLogEnd). WorkLogEnd also causes the user to be asked in the app to complete the assignment after creating the time stamp for this activity type. If the user confirms the completion of the assignment via this dialog, another event, AssignmentCompleted, is triggered.
If the value for ActivityTypeId does not exist in the TimeTypes table or the EventType does not correspond to WorkLogCheckpoint or WorkLogEnd, the corresponding row in Phx_AppEventConfiguration is ignored. In addition, the following applies:
INSERT INTO Phx_AppEventConfiguration (EventType, ActivityTypeId)SELECT 'WorkLogCheckpoint' EventType, ISGUID ActivityTypeIdFROM TIMETYPESWHERE NOT EXISTS (SELECT * FROM Phx_AppEventConfiguration WHERE ActivityTypeId = ISGUID) AND ISTYPE NOT IN (1, 4, 5, 6);Configuring App Events
If you want to record the creation of a time stamp for a specific activity type as an app event, you must add an entry to the Phx_AppEventConfiguration. To do this, enter the ISGUID of the desired activity type from the TimeTypes table for the ActivityTypeId column and enter either WorkLogEnd or WorkLogCheckpoint in the EventType column. WorkLogCheckpoint should be used for a simple event. If the activity represents the completion of the entire process, you should enter WorkLogEnd.