Aperio DevPack

Aperio DevPack

Aperio Development Pack for DC1 is a set of components and tools to help you develop Aperio mobile apps for DC1.

It includes:

• API Tool to test your API requests and to generate mobile apps
• AperioClient to run your mobile apps for testing

This development pack is built as a Docker image and is accessible from this project image registry.

How to use the development pack with my mobile apps?

Prerequisites

• Have the mobile apps you want to work with cloned in a local folder, e.g. “C:\MobileAppsDev\dc1_12”

  • Note: the apps should have develop.json file present describing its development profile (e.g. default DC1 company)

• Docker desktop app installed

  • Important: for proper operation of File watcher (JForms), the following property needs to be turned off in Docker settings: “Use the WSL 2 based engine” (OFF).
    • Note: if the file watcher still does not work - try restaring your PC.
  • Docker settings -> Resources -> File sharing
    • add the root folder of your Mobile Apps, so the Docker container will have access to the folder and the API Tool will be able to generate Mobile Apps there.

• To pull the Docker image you need to be logged-in to the Git repository. Login with this command:

  docker login gitlab.int.iptor.com:5050
  

  To check if you are logged in, use ‘git config -l’ command and look for user.name and user.email properties.

Starting the container

To start AperioDevPack, run docker command with environment variables that define your Mobile Apps development environment and API connection. You can run your command directly or using a script.

Note: If you prefer to have the command in a startup script, you can use the examples from this project. See Configure the startup script paragraph further down.

Direct command

Follow these steps to run the dev pack:

1. Prepare the following command to run the development pack as Docker container:

   docker run -it -p 8080:8080 -e API_ADDRESS=http://dkdcvs134.ibs.net:9091/api -e aperio.apps=mwhs-dc1_12 -e aperio.default.user.name=aperio -e aperio.default.user.password=mypassword --mount type=bind,src="C:\MobileAppsDev\dc1_12",dst=/usr/local/aperioapps gitlab.int.iptor.com:5050/pd-standard/aperio/aperiodevpacks/aperiodevpack-dc1
   

   In the command, set the following 5 variables:

   • API_ADDRESS

     It points to API Bridge that is configured to serve API for a DC1 version. Known bridges:

     • DC1_12 : http://dkdcvs134.ibs.net:9091/api
     • DC1_11 : http://dkdcvs134.ibs.net:9191/api The number identifies DC1 environment, e.g. DC1_12 for “DC1 version 12”.

   • aperio.apps

     The list of mobile app names that will be enabled for development. They should exist in the local folder provided in –mount/src attribute. Example:

     aperio.apps=mwhs-dc1_12,crm-dc1_12
     

     Note: do not put spaces between the app names.

   • aperio.default.user.name

     User profile name for API Tool to load the metadata when generating app forms.

     aperio.default.user.name=aperio
     

   • aperio.default.user.password

     User password for the profile above.

     aperio.default.user.password=mypassword
     

   • src

     The path to your local folder with mobile apps (src).The API tool will use this folder to find mobile apps for development. The list of apps to look for is taken from aperio.apps variable. Example:

     --mount type=bind,src="C:\MobileAppsDev\dc1_12",...
     

2. Run the command in the command prompt (terminal).

   • When running for the first time, the command will download the image from the Git project’s repository. It may take some time and you may be required to provide your Git credentials to login
     • to login to GitLab use the following command:

     docker login gitlab.int.iptor.com:5050
     

   • When the container is starting up:
     • Docker may ask for permission to share the folder - allow it to give Docker access to your mobile apps folder (see Prerequisites).
     • the command window will log some information about the apps and their properties. After a succesfull start, among other lines, there should be the following statements displayed:
       • [APP] 20230222 10:09:38 INFO AperioClient started.
       • [TOOL] 20230222 10:09:39 INFO Aperio API Tool started

Run & test

When the development pack container is running, use the following links to start:

• API Tool: http://localhost:8080/aperio/tool

• Mobile app: http://localhost:8080/aperio/app?name=[app-name]&develop=true

  Example to run MobileWarehouse in develop mode:

  http://localhost:8080/aperio/app?name=mwhs-dc1_12&develop=true

• Test API Bridge, using the readiness end-point: http://<api_server:port>/health/readiness

  Example: http://dkdcvs134.ibs.net:9091/health/readiness

When working with jforms

To verify that the JFroms generation works fine, check the container console. After changing a jform, the console should display the messages about processing the jform. Example, assuming that we have just changed jform “nurfBalancesEnquiry.json”:

• [TOOL] 20230221 08:25:17 INFO Processing form: nurfBalancesEnquiry …
• [TOOL] 20230221 08:25:19 INFO Form processed: nurfBalancesEnquiry

Note: The errors/warning that occurs during generation are printed out to /log folder of the jforms folder.

Stopping the container

In the console, press Ctrl-C to stop the container. You can stop the container also in the Docker deskop app. In the desktop app you can also inspect all the settings, logs and remove unused containers.

Configure the startup script (optional)

There are 2 example scripts in the project:

• start.bat - for Windows command prompt
• start.sh - for Linux/bash

Configure the following properties (the same that the command uses):

1. API_BRIDGE

   It points to API Bridge that is configured to serve API for a DC1 version. Known bridges: - DC1_12 : http://dkdcvs134.ibs.net:9091/api - DC1_11 : http://dkdcvs134.ibs.net:9191/api

   Yuo can use one of the predefined variables, e.g.:

    API_BRIDGE=$DC1_12
   

2. APPS_PATH

   The path to your local folder with mobile apps

   The API tool will use this folder to find mobile apps to develop. The list of apps to look for is provided in APPS property. Example:

   APPS_PATH="C:\MobileAppsDev\dc1_12"
   

3. APPS - The list of mobile app names that will be enabled for development. They should exist in the local folder provided in APPS_PATH. Example:

   APPS_PATH=mwhs-dc1_12,crm-dc1_12
   

   Note: do not put spaces between the app names.

4. Default user profile - credential used by API Tool to login to the system to load the metadata used when generating mobile app forms.

   • USER - default user name
   • PWD - default user name password

Note: you can use muliple startup scripts to run the dev pack with different settings.

How to build image & push it to the container registry? (for project maintainers)

When comtting changes to the repository the pipeline automaticaly is created to build a new image. Check CI/CD of the project.