Register a visit with GPS coordinates in Creatio Mobile

Level: advanced

To implement the example:

1. Create a TypeScript project. Read more >>>
2. Create a custom request. Read more >>>
3. Create a custom request handler. Read more >>>
4. Add the custom request handler to the Freedom UI page. Read more >>>

Example

Add a Check in button to the contact mobile page. When a user taps the button, Creatio Mobile must get the current GPS coordinates of the device and register the visit to the contact. Display the registered visits in the Visits list on the Details tab of the contact mobile page. Each visit must be displayed as a separate list item that includes the "Visit date and time," "Latitude," and "Longitude" columns.

If Creatio Mobile cannot get the coordinates or register the visit, display a notification and do not register the visit.

Implement a request handler using a remote module created in a TypeScript project.

1. Create a TypeScript project

To create a TypeScript project, follow the instructions: Create a TypeScript project.

For this example, change the directory name of the TypeScript project to "check_in_mobile."

As a result, a TypeScript project to develop a custom request handler using a remote module will be added.

2. Create a custom request

1. Open the "index.ts" file.
2. Inherit the BaseRequest class from the @creatio/mobile-common library.
3. Import the required functionality from the libraries into the class.
4. Save the file.

"index.ts" file

/* Import the required functionality from the libraries. */
import {
    BaseRequest,
    CrtRequest
} from "@creatio/mobile-common";

/* Add the "CrtRequest" decorator to the "CheckInRequest" class. */
@CrtRequest({
    type: 'usr.CheckInRequest'
})

export class CheckInRequest extends BaseRequest {}

3. Create a custom request handler

1. Implement a custom request handler that gets the GPS coordinates of the device and registers the visit.

   1. Open the "index.ts" file.

   2. Add the configuration object that declares the request handler.

      • Set the type property to "usr.CheckInRequestHandler." The type property is the type of handler.
      • Set the requestType property to "usr.CheckInRequest." The requestType property is the type of request to execute the handler specified in the type property.
      • Set the scopes property to "['Contact_MobileFormPage']." The scopes property is the list of Freedom UI page schemas where Creatio Mobile runs the handler.

   3. Flag the CheckInRequestHandler class using the CrtRequestHandler decorator.

   4. Inherit the BaseRequestHandler class from the @creatio/mobile-common library.

   5. Call the getCurrentCoordinates() method of the GeolocationService service and pass the accuracy from the GeolocationAccuracy enumeration to implement getting the GPS coordinates of the device. For this example, use the "high" accuracy. Learn more: GeolocationService service.

      If the errorCode property of the result is empty, the latitude and longitude properties contain the coordinates. Otherwise, Creatio Mobile could not get the coordinates. For example, the user denied access to the device location. In this case, display a notification and stop processing the request.

   6. Register the visit.

      1. Call the Model.create() method to create an instance of the UsrContactVisit model.

      2. Call the insert() method to add a record to the model. Use the Id attribute of the contact mobile page to bind the visit to the contact. Use the encodeDate() function to pass the date and time of the visit.

         If the success property of the result is "true," Creatio Mobile saves the record locally and synchronizes it with the main Creatio app. Otherwise, display a notification and stop processing the request.

      3. Execute the crt.LoadDataRequest base request to reload the data of the Visits list. Set the mode property of the refreshDataConfig configuration object to "RefreshMode.RefreshAll" to reload all data sources of the page. Creatio Mobile does not reload the list automatically after the record is added.

      4. Call the showSnackBar() method of the ModalPresenter class to notify the user that the visit is registered.

   7. Use the DialogService service to implement the showMessage() method that displays a notification.

   8. Import the required functionality from the libraries into the class.

   9. Save the file.

   "index.ts" file

   /* Import the required functionality from the libraries. */
   import {
       BaseRequestHandler,
       CrtRequestHandler,
       GeolocationService,
       GeolocationServicePosition,
       GeolocationAccuracy,
       Model,
       HandlerChainService,
       LoadDataRequest,
       RefreshMode,
       ModalPresenter,
       encodeDate,
       DialogService,
       BaseDialogConfig
   } from "@creatio/mobile-common";
   
   /* Add the "CrtRequestHandler" decorator to the "CheckInRequestHandler"
   class. */
   @CrtRequestHandler({
       requestType: 'usr.CheckInRequest',
       type: 'usr.CheckInRequestHandler',
       scopes: ['Contact_MobileFormPage'],
   })
   
   export class CheckInRequestHandler
       extends BaseRequestHandler<CheckInRequest> {
   
       public async handle(request: CheckInRequest): Promise<unknown> {
   
           /* Get the GPS coordinates of the device. */
           const coords: GeolocationServicePosition =
               await new GeolocationService()
                   .getCurrentCoordinates(GeolocationAccuracy.high);
           /* Notify the user and stop processing if Creatio Mobile cannot get
           the coordinates. */
           if (coords.errorCode) {
               await this.showMessage(
                   request,
                   'Check in',
                   'Unable to get the device location.'
               );
               return this.next?.handle(request);
           }
   
           /* Register the visit in the "UsrContactVisit" object. */
           const contactId: string = await request.$context['Id'];
           const contactVisitModel: Model =
               await Model.create('UsrContactVisit');
           const insertResult = await contactVisitModel.insert({
               UsrContact: contactId,
               UsrVisitDate: encodeDate(new Date()),
               UsrLatitude: coords.latitude,
               UsrLongitude: coords.longitude
           });
           /* Notify the user and stop processing if Creatio Mobile cannot save
           the visit. */
           if (!insertResult.success) {
               await this.showMessage(
                   request,
                   'Check in',
                   'Unable to register the visit.'
               );
               return this.next?.handle(request);
           }
   
           /* Reload the data of the "Visits" list. */
           await HandlerChainService.instance.process({
               type: 'crt.LoadDataRequest',
               $context: request.$context,
               refreshDataConfig: {
                   mode: RefreshMode.RefreshAll
               }
           } as LoadDataRequest);
   
           /* Notify the user that the visit is registered. */
           await ModalPresenter.showSnackBar(
               'Check in',
               'The visit is registered.'
           );
   
           return this.next?.handle(request);
   
       }
   
       /* Display the notification that contains the message. */
       private async showMessage(
           request: CheckInRequest,
           title: string,
           message: string
       ): Promise<void> {
           const dialogService = new DialogService(request.$context);
           const config: BaseDialogConfig = {
               title: title,
               message: message,
               actions: [{
                   key: 'ok',
                   config: {
                       caption: 'OK',
                       color: 'primary'
                   }
               }]
           };
           await dialogService.open(config);
       }
   }

2. Register the request handler.

   1. Open the "index.ts" file.
   2. Add the CheckInRequestHandler handler to the requestHandlers section in the CrtModule decorator.
   3. Import the required functionality from the libraries into the class.
   4. Save the file.
   "index.ts" file

   /* Import the required functionality from the libraries. */
   import {
       CrtModule,
       bootstrapCrtModule,
       DoBootstrap
   } from "@creatio/mobile-common";
   ...
   
   @CrtModule({
       /* Specify that "CheckInRequestHandler" is a request handler. */
       requestHandlers: [
           CheckInRequestHandler
       ]
   })
   
   export class SdkCheckInApp implements DoBootstrap {
       bootstrap(): void {
           bootstrapCrtModule('SdkCheckInApp', SdkCheckInApp);
       }
   }

3. Build the project. Instructions: Build the project.

As a result, the "main.js" build file will be added to the TypeScript project's directory that is specified in the "webpack.config.js" file → baseConfig configuration object → output configuration object → path property. For this example, the build file will be added to the "../check_in_mobile/out/mobile/SdkCheckInApp" project directory.

4. Add the custom request handler to the Freedom UI page

1. Repeat steps 1-7 of the procedure to add the custom request handler to the Freedom UI page.

   For this example:

   • Create the sdkCheckInMobile user-made package.
   • Create the "../Terrasoft.WebApp/Terrasoft.Configuration/Pkg/sdkCheckInMobile/Files/src/mobile/SdkCheckInApp" directory.
   • Copy the "main.js" build file from the "../check_in_mobile/out/mobile/SdkCheckInApp" project directory to the "../Terrasoft.WebApp/Terrasoft.Configuration/Pkg/sdkCheckInMobile/Files/src/mobile/SdkCheckInApp" directory.

2. Create the object that stores visits. Instructions: Implement an object.

   For this example:

   1. Create the "Contact visit" (UsrContactVisit code) object.

   2. Add the columns listed in the table below.

      Column	Type	Property	Value
      Column that contains the contact	Lookup	Code	UsrContact
      		Title	Contact
      		Lookup	Contact
      Column that contains the visit date and time	Date/Time → Date/Time	Code	UsrVisitDate
      		Title	Visit date and time
      Column that contains the latitude	Number → Decimal (0.00000001)	Code	UsrLatitude
      		Title	Latitude
      Column that contains the longitude	Number → Decimal (0.00000001)	Code	UsrLongitude
      		Title	Longitude

   3. Publish the object.

3. Open the Customer 360 app in the Application Designer.

4. Open the Contact mobile edit page.

5. Add a button that registers the visit to the contact.

   1. Drag the Button component from the element library to the Profile block of the Details tab.

   2. Fill out the button properties.

      Element	Property	Value
      Button that registers the visit to the contact	Title	Check in
      	Style	Focus
      	Element code	UsrCheckInButton

6. Add a list that stores visits.

   1. Add an expansion panel.

      1. Drag the Expansion panel layout element from the element library to the Details tab.

      2. Fill out the expansion panel properties.

         Element	Property	Value
         Expansion panel that contains the list of visits	Title	Visits
         	Element code	UsrContactVisitExpansionPanel

   2. Add a list.

      1. Drag the List component from the element library to the Visits expansion panel.

      2. Fill out the list properties.

         Element	Property	Value
         List that stores visits	Object	Contact visit
         	Apply filter by page data	Click . Set the Contact parameter to "Id." Set the Contact visit parameter to "Contact."
         	Columns	Click . This opens the Select field window. Select the Visit date and time, Latitude, and Longitude fields. Click Select.
         	Sort by column	Click . This opens the Select field window. Select the Visit date and time field. Click Select. Click .
         	Element code	UsrContactVisitList

7. Click → Source code to open the source code of the Freedom UI mobile page.

8. Set up how to handle the action executed on button click.

   1. Go to the viewConfigDiff schema section → UsrCheckInButton element.
   2. Bind the sending of the custom usr.CheckInRequest request to the clicked button event.
   Contact_MobileFormPage

   {
       "viewConfigDiff": [
           ...,
           /* Button that registers the visit to the contact. */
           {
               "operation": "insert",
               "name": "UsrCheckInButton",
               "values": {
                   "type": "crt.Button",
                   "caption": "#ResourceString(UsrCheckInButton_caption)#",
                   ...,
                   "clicked": {
                       /* Bind the sending of the custom request to the
                       "clicked" button event. */
                       "request": "usr.CheckInRequest"
                   }
               },
               ...
           }
       ]
   }

9. Save the changes.

As a result, the Check in button and the Visits list will be added to the contact mobile page.

View the result

1. Synchronize the changes. Instructions: Add the custom request handler to the Freedom UI page (steps 13-14).

2. Open the Contacts section.

3. Open a contact. For example, "Alexander Wilson."

4. Tap Check in.

5. Allow access to the location of the device if needed. Creatio Mobile requests the permission when you use geolocation for the first time.

   If you use a mobile app emulator configured in Android Studio, set the device location. Instructions: Extended controls, settings, and help (official vendor documentation).

As a result, Creatio Mobile will get the current GPS coordinates of the device and register the visit. The Visits list will display the new visit that includes the visit date and time, latitude, and longitude. After the visit is registered, Creatio Mobile displays the "The visit is registered" message. Each subsequent check-in adds a new list item. View the result >>>

If you deny access to the device location, Creatio Mobile displays a notification that contains the corresponding message and does not register the visit.

The handler is implemented using the remote module created in a TypeScript project.

---

Resources

*.zip archive that contains the implemented Freedom UI app for Creatio Mobile

TypeScript project that contains the implemented example