Predix Sync

© 2020 General Electric Company

Contents

Predix Sync Overview 1

Predix Sync Overview 1

Predix Sync Components 1

Data Integration 3

Get Started with the Predix Sync and SDKs 4

Getting Started with the Predix Sync and SDKs 4

Predix Sync Setup 4

Installing the pm Command-Line Interface 5

Defining Proxy Connections to Remote Resources 6

About the Predix Mobile Setup Script 7

Creating a Predix Mobile Developer Account 8

Requesting Public Domain Routes for Mobile Service 9

Manually Setting Up Predix Sync Service 9

Supported Devices for Mobile App Development 11

Running the Mobile Sample App 12

About the Mobile Sample App 12

Creating a Predix Mobile Workspace 12

Publishing the Web App to the Predix Mobile Service 13

Creating the Mobile Sample App Configuration File 14

Defining the Mobile Sample App 14

Loading the Mobile Sample App Data 15

Granting Access to the Mobile Sample App 15

Get the Mobile Reference App Container 16

About the Mobile Reference App Containers 16

Downloading the Android Predix Mobile App Container 16

Downloading the iOS Predix Mobile App Container 17

Downloading the MacOS Predix Mobile App Container 18

Creating a Mobile Hello World Web App 21

Creating a Mobile Hello World Web App 21

Setting up Your Directory Structure 21

Populating Your JSON Files 22

Coding the Mobile Hello World Web App 22

ii Predix Sync

Publishing and Defining the Hello World Web App 23

Running the Android Mobile Hello World App 23

Running the iOS and MacOS Mobile Hello World Web App 24

Release Notes 25

Release Notes 25

iii

Copyright GE Digital© 2020 General Electric Company.

GE, the GE Monogram, and Predix are either registered trademarks or trademarks of General Electric Company. All other trademarks are the property of their respective owners.

This document may contain Confidential/Proprietary information of General Electric Company and/or its suppliers or vendors. Distribution or reproduction is prohibited without permission.

THIS DOCUMENT AND ITS CONTENTS ARE PROVIDED "AS IS," WITH NO REPRESENTATION OR WARRANTIES OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF DESIGN, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. ALL OTHER LIABILITY ARISING FROM RELIANCE UPON ANY INFORMATION CONTAINED HEREIN IS EXPRESSLY DISCLAIMED.

Access to and use of the software described in this document is conditioned on acceptance of the End User License Agreement and compliance with its terms.

iv © 2020 General Electric Company

Predix Sync Overview

Predix Sync OverviewPredix Sync provides a Backend-as-a-Service to Industrial Internet mobile applications built with thePredix SDKs for Hybrid and iOS.

Predix Sync consists of the Sync service and the Predix SDKs for Hybrid and iOS. It includes the pmCLI,example apps, and a reference application container. The Sync service supports applications that requireoffline support and integration with the data domain, including enterprise systems, third-party services,and Predix microservices such as Machine, Asset, Time Series, and Security.

For iOS, you build the Predix Mobile Reference App Container for iOS. For MacOS, you build the AppContainer for MacOS.

Additional Information

Predix Mobile Sync Starter

Predix Sync ComponentsUse the SDK for Hybrid to interact with the Sync service components and your Mobile application code.

Figure 1: Predix SDK for Hybrid and Predix Sync Service

The components are described below.

Security Layer

The Security layer includes Authentication and the Authorization Interface.

© 2020 General Electric Company 1

Authentication (Auth)About the User Account and Authentication Security Service is a web service provided by CloudFoundry to manage users and OAuth2 clients. Its primary role is as an OAuth2 provider, issuing tokensfor client applications to use when they act on behalf of Cloud Foundry users. In collaboration with thelogin server, it can authenticate users with their Cloud Foundry credentials, and can act as an SSOservice using those credentials (or others). The service provides endpoints for managing useraccounts and for registering OAuth2 clients.

Authorization Interface (AUTH-I)Predix Mobile integrates with your application's authorization system through the AuthorizationInterface (AUTH-I) microservice. The microservice can map the roles and policies of an applicationauthorization service whether it is ACS, ZAC, or a custom authorization service. Authorization policesare applied by the AUTH-I microservice as implemented by the development team. Developers canimplement the AUTH-I microservice in any programming language.

Client API Gateway (API)

The Client API Gateway and the UAA Service work together to ensure that all clients that access thePredix Sync service possess a valid authentication token.

Session

The Session component establishes a client session with the Sync Gateway.

Sync Gateway (Sync) and Couchbase Server (Cache)

The Predix Sync service includes a Sync Gateway and Couchbase Server. The Sync Gateway is asynchronization server that enables Couchbase Server to act as a replication endpoint for Couchbase Lite.Sync Gateway runs an HTTP listener process that provides a passive replication endpoint and uses aCouchbase Server bucket as persistent storage for all database documents.

Sync Processors and Command Processors use the Sync Gateway REST interface to access and createdocuments on the Couchbase Server.

See the Couchbase Mobile Developer site for more information about the Sync Gateway and CouchbaseServer.

Integration

The Integration layer consists of the Sync Processor and Command Processor microservices. They worktogether to connect the Predix Sync service to data from systems and services (for example, Predix Asset,SalesForce, or a railroad train-management system). The Sync Processor primarily reads data. The mainfunction of a Command Processor is to write data to the data domain.

Sync service employs Command Query Responsibility Segregation (CQRS) as an integration pattern toseparate read and write processes.

Sync Processor (Sync)A Sync Processor performs the following tasks:

• Gathers data from the source systems.• Transforms the data into a JSON document.• Write the document to the Couchbase Server.• Defines access to the JSON document.

The application development team is responsible for building the Sync Processors required by themobile application.

2 © 2020 General Electric Company

For more information, see https://github.com/PredixDev/PredixMobileSDK for Sync Processorexamples with instructions on how to deploy them to a Predix Sync service.

Command Processor (Process)A Command Processor is responsible for commands that it receives from the mobile applicationthrough the Predix Sync service. While mostly responsible for updating the source data, a CommandProcessor can also perform other tasks, such as managing data access for a user. The applicationdevelopment team is responsible for building the Command Processors required by the mobileapplication.

Command Router (Route)The Predix Sync service includes a Command Router that routes new command objects to aCommand Processor. When an error occurs, the Command Router updates the command with theerror information as a notification to the mobile application. A command is a JSON document createdby the Predix Mobile application and replicated to the Couchbase Server. The command headerproperties contain information for use by the Command Router in mapping to a Command Processor.The command payload contains application data required by the Command Processor to completethe command request. The developer determines how to model the payload.

For more information, see https://github.com/PredixDev/PredixMobileSDK for examples of CommandProcessors and Commands.

Data IntegrationAs a back-end developer writing code to integrate with the data , you must manage the read and writerules that support your data model. Mobile service employs Command Query Responsibility Segregation(CQRS) as an integration pattern to separate read and write processes.

This integration pattern includes the following rules:

• Read (“Pull”) Rules – If your source system supports broadcasting events, the Mobile service supportsmicroservice designs that can subscribe to the system. Then, when your data is updated, themicroservice reads and writes the data into the data model for access by application clients. If yoursystem is not event-based, your microservice might have to poll the system and check for updates.

• Write (“Push”) Rules – The Mobile service features built-in command routers that route commandsfrom devices to your app-specific command processors.

The Mobile service supports applications that require offline support and integration with the datadomain, including enterprise systems, third-party services, and Predix microservices such as Machine,Asset, Analytics, Time Series, and Blobstore.

© 2020 General Electric Company 3

Get Started with the Predix Sync and SDKs

Getting Started with the Predix Sync and SDKsInstall developer tools, configure your proxy settings, and run setup and configuration scripts.

To get started with the Predix Sync setup, follow the tasks outlined in the Task Roadmap table.

(Optional) To manually set up the Predix Sync service, follow the tasks described in Manually Setting UpPredix Sync Service on page 9 .

Related Concepts

Predix Sync Overview on page 1

Predix Sync provides a Backend-as-a-Service to Industrial Internet mobile applications built with thePredix SDKs for Hybrid and iOS.

Predix Sync SetupAuthentication for Sync service is controlled by the designated trusted issuer and is managed by the UserAccount and Authentication (UAA) web service. You must set up a UAA service instance as the trustedissuer before getting started with the Sync service. For more information on authentication andauthorization in Predix services, see UAA Service Overview.

Task Roadmap

Task Information

1. Configure your proxy settings if necessary. Depending on your location and network configuration, you may

need to configure your proxy settings to access remote resources.

See Defining Proxy Connections to Remote Resources on page

6.

2. (Optional) Set up access to Predix platform Artifactory. If you need access to Predix platform artifacts, you need to set up

access for Artifactory.

See Defining Predix Platform Artifactory Access.

3. Install the Cloud Foundry command-line interface (CLI)

utilities.• Install Cloud Foundry's cf CLI.

See https://github.com/cloudfoundry/cli#downloads.

• Install Cloud Foundry's cf-uaac CLI.

See https://github.com/cloudfoundry/cf-uaac and

Troubleshooting UAA Service.

4. Install the Predix Mobile pm CLI. See https://github.com/PredixDev/predix-mobile-cli/releases/

latest and Installing the pm Command-Line Interface on page 5.

5. Install tools for your mobile development platform. • Install Xcode version 9.0, and Swift 3 (available as part of the

Xcode developer tools).

See https://developer.apple.com/download/.

• Install Android Studio, latest version.

See https://developer.android.com/sdk/index.html.

4 © 2020 General Electric Company

Task Information

6. Install and configure Node.js package-management

utility.

See https://nodejs.org/en/download/ and https://docs.npmjs.com/

getting-started/fixing-npm-permissions.

7. Run the Predix Mobile (PM) setup script. It creates a

UAA instance and a Sync service instance. It creates a

dummy app and connects it to the UAA and Sync

service instances so that it can retrieve the necessary

environment variables for you.

Note: We recommend using the PM setup script to

create and bind Sync service and UAA instances.

However, if you wish to manually create and bind the

Predix Sync service and UAA instances, see Manually

Setting Up Predix Sync Service on page 9

See About the Predix Mobile Setup Script on page 7.

The Predix Mobile scripts are located in the /uaa-scriptssub-directory where you unpacked the latest pm-v1.x.x-Mac.zip file or pm-v1.x.x-win.zip file.

9. Run the Predix Mobile Add Developer script. It creates a

user on the UAA server and adds it to the

pm.admin group.

See Creating a Predix Mobile Developer Account on page 8.

11. (Optional) Update the Oath2 client to add service

specific scopes or authorities.

To enable your application to access a platform service, your JSON

Web Token (JWT) must contain the scopes required for a platform

service.

See Updating the OAuth2 Client for Services.

After setting up your Predix Mobile development environment, you can download Mobile App Containerproject and run the Predix Mobile Sample App for iOS and Predix Mobile Sample App for Android

Installing the pm Command-Line InterfaceUse the pm CLI to manage Predix mobile users, roles, Predix mobile applications, and their web appdependencies.

Before You Begin

The pm CLI depends on both the Cloud Foundry (CF) and UAAC command-line tools.

• Install Cloud Foundry's cf CLI.See https://github.com/cloudfoundry/cli#downloads.

• Install Cloud Foundry's cf-uaac CLI.See https://github.com/cloudfoundry/cf-uaac and Troubleshooting UAA Service.

About This Task

Install the pm CLI:

Procedure

• Download the pm .zip file from https://github.com/PredixDev/predix-mobile-cli/releases/latest.

◦ For iOS and MacOS platforms, unpack the pm-v1.x.x-Mac.zip file in your workspace.◦ On the Windows platform, unpack the pm-v1.x.x-win.zip file in your workspace.

© 2020 General Electric Company 5

Defining Proxy Connections to Remote ResourcesIf traffic between your corporate network and the internet is monitored, access to certain tools (cURL,Maven, Git, Eclipse, and so on) may be blocked by the proxy.

About This Task

You may need to configure your proxy settings to access remote resources. The values for your proxysettings vary depending on your location and network configuration. Contact your IT administrator for thecorrect proxy settings.

Procedure

• For Windows:

1. On the Start menu, right-click Computer > Properties.2. Click Advanced system settings.3. Click the Advanced tab.4. Click Environment Variables.5. Click New and enter the Variable Name and Variable Value for each variable.

Set these values:

Variable Name Variable Value

HTTP_PROXY <host>:<port>HTTPS_PROXY <host>:<port>http_proxy <host>:<port>https_proxy <host>:<port>no_proxy <domain>

Note: HTTP_PROXY and HTTPS_PROXY variables are case-insensitive on Windows.

To set the environment variables for the current session, enter the following from a commandprompt:

set HTTP_PROXY=http://<host>:<port>set HTTPS_PROXY=http://<host>:<port>set no_proxy=<domain>

For example:

set HTTP_PROXY=http://proxy.mycompany.com:8080set HTTPS_PROXY=http://proxy.mycompany.com:8080set no_proxy=mycompany.com

• For Mac OS:

◦ Define system proxy connections to remote resources by adding the following entries to the ~/.profile, ~/.bash_profile or ~/.bashrc file.

For example, MacOS settings should reflect the following changes to the ~/.bash_profile file:

export HTTP_PROXY=http://<host>:<port>

6 © 2020 General Electric Company

export HTTPS_PROXY=http://<host>:<port>export http_proxy=http://<host>:<port>export https_proxy=http://<host>:<port>export no_proxy=<domain>

• Additional Information:

Dev Tools: Define network proxy settings

About the Predix Mobile Setup ScriptUse this script to create an app and connect it to a UAA instance, and create a Mobile service instance andbind the app to it.

If you wish to perform the Predix Mobile Setup tasks manually, ie. without using the setup script, seeManually Creating and Binding a Mobile Service Instance.

The Predix Mobile scripts are located in the /uaa-scripts sub-directory where you unpacked thelatest pm-v1.x.x-Mac.zip file or pm-v1.x.x-win.zip file.

The Predix Mobile setup script (pm_setup.sh) performs the following tasks for you:

1. Verifies that you have the prerequisite Cloud Foundry tools installed and that you are logged in.2. Uploads a dummy app, pm-tmp-hello-world-app, into your org and space. This app is deployed

to Cloud Foundry and is used to work with your UAA instance and your Mobile service instance so thatthe script can retrieve your environment variables..

3. Creates a UAA instance, if you do not have one.User Account and Authentication (UAA) is a web service provided by Cloud Foundry to manage usersand OAuth2 clients. Its primary role is as an OAuth2 provider, issuing tokens for client applications touse when they act on behalf of Cloud Foundry users. In collaboration with the login server, it canauthenticate users with their Cloud Foundry credentials, and can act as an SSO service using thosecredentials (or others). The service provides endpoints for managing user accounts and for registeringOAuth2 clients.

4. Binds the dummy app to the UAA instance.5. Creates a Mobile service instance and binds the dummy app to it.6. Records your environment variables in a pm_config.txt file. For example:

uaa_secret : "abc123"uaa_uri : "https://59dd94a5-4965-4050-8be3-45d2c2737c5c.predix-uaa.run.aws-usw02-pr.ice.predix.io"

cf_app : "pm-tmp-hello-world-app"

pm_instance_name : "script_pm_test"pm_service_short_uri : "https://r2chn6.run.aws-usw02-pr.ice.predix.io"

7. Creates the pm-api-gateway-oauth OAuth account and the pm OAuth account, or recreatesthem if they already exist. The Sync service uses the pm-api-gateway-oauth account for clientauthentication, using the authorization_code grant type.

8. Creates the pm OAuth account, or recreates it if it already exists. The pm CLI tool uses the pm OAuthaccount. It is animplicit_grant type account, similar in functionality to the cf user account usedby the Cloud Foundry cf command-line tool.

9. Creates the pm.admin user group, if it does not exist.

© 2020 General Electric Company 7

Running the Predix Mobile Setup Script

Before You Begin

Make sure you have installed all required software. See Predix Sync Setup on page 4 for a list of requiredsoftware.

Open your pm_config text file to access the uaa_instance_uri anduaa_instance_issuerId values that you recorded when configuring your UAA service.

You will need the details in your pm_config.txt file when running the Predix Mobile Sample app andwhen building your own web apps.

About This Task

Procedure

1. At the command prompt, go to the directory where you downloaded the pm CLI.2. Go to the uaa-scripts sub-directory.3. Run the setup script:

$ ./pm_setup.sh

Creating a Predix Mobile Developer AccountThe pm-add-developer.sh script creates a user on the UAA server and adds it to a pm.admin group,allowing that user to publish apps to the Mobile service.

About This Task

The Predix Mobile scripts are located in the /uaa-scripts sub-directory where you unpacked thelatest pm-v1.x.x-Mac.zip file or pm-v1.x.x-win.zip file.

Any user that is not part of the pm.admin group cannot publish apps.

Procedure

1. At the command prompt, go to the directory where you downloaded the pm CLI.2. Go to the uaa-scripts sub-directory.3. Run the pm-add-developer.sh script to set up a developer account.

For the developer_username, you can use any username.

$ /.pm-add-developer.sh -e <developer_username>

If you enter a user name that already exists, that user is added to the pm.admin group. If theusername does not exist, the script creates the user and adds it to the group.

8 © 2020 General Electric Company

If an authentication not valid error occurs, try re-logging into the UAA server, using thestandard uaac commands, and then execute the user creation operation again:

$> uaac target <uaa-server-url> --skip-ssl-validation$> uaac token client get <username>// (enter UAA admin password when prompted)

Next Steps

Once you have successfully set up your Predix Mobile development environment, see About the MobileSample App on page 12.

Requesting Public Domain Routes for Mobile ServiceTo enable public Internet access to your Mobile service instance on Predix-Select, you must request publicdomain routes for your Mobile instance and submit the routes for whitelisting.

Procedure

1. Go to Predix Support and submit a ticket to request public domain routes for your Mobile serviceinstance.

2. Submit the allocated routes to your IT department for whitelisting.

Manually Setting Up Predix Sync ServiceYou can manually create the Predix Sync service, UAA instance, and bind an app to it without using thePredix Mobile scripts. You can then retrieve details about the Predix Sync service, the Predix UAA instance,and the app used to bind to the service.

Before You Begin

Make sure you have installed all required software. See Predix Sync Setup on page 4 for a list of requiredsoftware.

About This Task

Note: This is an alternate method to set up your PM service. You can skip this method, and use the PredixSync setup script to automatically perform these tasks for you. See About the Predix Mobile Setup Scripton page 7.

Procedure

1. Configure your UAA service.

2. Create a text file to store values related to your UAA and PM service instances. You can name this filepm-config.txt and store (copy and paste) some parameters and values that you may need to referto when you start working on a sample application. Following is an example of the pm-config.txtfile :

uaa_instance_name:uaa_instance_uri:uaa_admin_account_name:uaa_admin_client_secret:

© 2020 General Electric Company 9

predix-hello-world-app-<YourName>:pm_instance_name:pm-service_short_uri:

developer_username:developer_password:predix_mobile_api_gateway_short_route_url:

3. Create your Sync service instance.

$ cf create-service "predix-mobile" "<your_plan>" "pm-service" -c'{"trustedIssuerIds": ["<uaa_instance_issuerId>"]}'

4. Bind the Predix Sync service to the Predix hello-world app. Follow the procedure in Binding anApplication to the UAA Instance, but use the new predix-mobile service instead of the UAAservice.

5. Display your environment variables using the cf env command.

cf env <app name that was used to bind service>6. Save the Predix Sync service api_gateway_short_route URL in your pm-config text file.

You need this URL when running the Predix Mobile Sample App.

The command returns details about the Predix Sync service, the Predix UAA instances, and the appthat you used to bind to the service.

The api_gateway_short_route property contains is the Predix Mobile API Client Gateway URL.This is the URL that your client app interacts with.

"VCAP_SERVICES": {"predix-mobile": [{"credentials": {"api_gateway_direct_route": "https://

bc6823df-004c-441c-991a-3f2cdf8cef2d-pm-gateway.run.aws-usw02-pr.ice.predix.io/",

"api_gateway_short_route": "https://193435.run.aws-usw02-pr.ice.predix.io/",

"dbname": "pm","hostname": "193435.run.aws-usw02-pr.ice.predix.io","instance_id": "bc6823df-004c-441c-991a-3f2cdf8cef2d","port": "443","ports": {"443/tcp": "443","80/tcp": "80"},"uri": "https://193435.run.aws-usw02-pr.ice.predix.io/"},"label": "predix-mobile","name": "pm-service","plan": "<your_plan>","tags": []}],

7. Check on the console/terminal if the uaac target is set to the correct uaac uri and enter thecorrect uaac token.

10 © 2020 General Electric Company

8. Set up a user account to work with the pm CLI and publish apps to your Sync service instance. Use theuaac user add $user_email --emails $user_email --password$user_password command to add your user credentials (user's email and password).

uaac user add $user_email --dev1@gmail.com $user_email --123Abz

Note: Edit the pm-config.txt file and add your developer credentials to the file.9. Add the user that you created (see Step 8) to the pm.admin group. Adding the user to the pm.admin

group allows the user to access the PM backend service via, the PM CLI.

uaac member add pm.admin $user_email10. (Optional) Update the Oath2 client to add service specific scopes or authorities . See Updating the

OAuth2 Client for Services .

Supported Devices for Mobile App DevelopmentPredix Mobile supports the following devices for corresponding app-development platforms.

Platform Supported Devices

Android Any device running Lollipop and above.

iOS Any device running iOS 8 and above.

MacOS Any device running El Capitan and above.

© 2020 General Electric Company 11

Running the Mobile Sample App

About the Mobile Sample AppThe Predix Mobile Sample App demonstrates app navigation and the architecture for building mobile webapps.

The Sample app consists of simple features for the following field-service mobility scenario:

• An organization needs to track a list of issues.• The app needs to run on mobile devices and desktops, as well as on different platforms.• The app needs to support both online and offline modes. In offline mode, the application needs to store

data locally in an on-device data store, then transmit and synchronize the data with an enterprise datastore when an Internet connection is re-established.

The Sample app is geared towards a field-service engineer who has been assigned a list of issues. Itincludes a dashboard for Creating a Predix Mobile Workspace on page 12 viewing the number of issues,classified by levels of severity. Tapping a severity indicator displays a list of issues classified by thatseverity. Tapping an issue displays details about that issue. The Sample app teaches you how to use thePredix Mobile API in the context of a web application built on top of the Predix Mobile Reference AppContainer.

The Sample app technology stack is based on Foundation for Apps, a framework that uses HTML5,JavaScript, CSS3, AngularJS, and Sass. However, Foundation for Apps, AngularJS, or Sass are not requiredto write apps on Predix Mobile.

To get started, see Creating a Predix Mobile Workspace on page 12.

Creating a Predix Mobile WorkspaceCreate a workspace for your Predix Mobile web app.

About This Task

Before you start working on your sample you must create a Predix Mobile workspace. A workspaceprovides implicit and explicit relationships among the included multiple projects and their targets. Theworkspace has a hierarchical structure. Projects are at the top level of the hierarchy and inside them youcan have files and folders.

Procedure

1. Retrieve the URL for your Mobile service instance by executing the following command on the app thatyou bound to the Predix Mobile service:

$ cf env <your_app_name>

The command returns app details, including information on the Predix Mobile service. Theapi_gateway_short_route property is the URL for the Predix Mobile service(predix_mobile_service_url).

Use this command to display the current target.

2. Run the following command to set the target for the Mobile Service:

$ pm api <predix_mobile_service_url>

12 © 2020 General Electric Company

In a typical application-development workflow, you begin by targeting the Predix Mobile Client APIGateway service. The Client API Gateway and the UAA Service work together to ensure that all clientsthat access the Predix Mobile service possess a valid authentication token.

3. Log into the pm CLI, using the developer_username that you created with the pm-add-developer.sh script in Creating a Predix Mobile Developer Account on page 8.

$ pm auth developer_username developer_password

4. Create a directory for your Predix Mobile workspace and make it the current directory.

5. Run the following command to create your workspace:

$ pm workspace --create

Next Steps

Publishing the Web App to the Predix Mobile Service on page 13

Publishing the Web App to the Predix Mobile ServicePublish your web app using the pm publish command.

About This Task

The functionality of a Predix Mobile application is derived from the set of web apps. You can include a webapp in more than one Predix Mobile application. In your workspace, the web apps/ directory stores webapps for use by applications.

Before You Begin

Download the web app used in the Sample app and install it in your workspace.

Follow these steps to publish the web app:

Procedure

1. Set the current directory to the webapps/ folder in your workspace.

2. Run the following command to clone the Sample app repository:

$ git clone https://github.com/PredixDev/MobileExample-WebApp-Sample.git

3. Change your directory:

$ cd MobileExample-WebApp-Sample

4. Run the following npm commands to install the Sample app in your directory.

$ npm install

$ npm run build

5. Run the following command to upload your Predix Mobile web app to your Predix Mobile serviceinstance.

$ pm publish

© 2020 General Electric Company 13

Next Steps

Creating the Mobile Sample App Configuration File on page 14

Creating the Mobile Sample App Configuration FileThe app.json configuration file defines the app and the web apps that the app contains. It also specifieswhich web app should appear when you start your app.

Procedure

1. Change the current directory to <workspace>/pm-apps/Sample1.2. Update the app.json file contents with the following entries:

{"name": "Sample1","version": "1.0","starter": "sample-webapp","dependencies": {"sample-webapp": "0.0.1"}}

Next Steps

Defining the Mobile Sample App on page 14

Defining the Mobile Sample AppUse the pm define command to define a Predix Mobile application as a collection of one or more webapps.

About This Task

Define version 1.0 of the Sample app:

Procedure

1. Change the current directory to <workspace>/pm-apps/Sample1.2. Run the following command:

$ pm define

This command defines the Predix Mobile Sample app. It accepts an --app parameter that specifiesthe path to an app.json file. This app.json file defines the application as a collection of one ormore web apps.

Next Steps

Loading the Mobile Sample App Data on page 15

14 © 2020 General Electric Company

Loading the Mobile Sample App DataUse the pm import command to import data into your Predix Mobile service.

Procedure

1. Change directories to the sample web app directory:

cd <workspace>/webapps/MobileExample-WebApp-Sample2. Run the following command:

pm import --data ./test/data/data.json --app <workspace>/pm-apps/Sample1/app.json

The import command takes a --data parameter specifying the location of a raw JSON data file. Italso takes an --app parameter specifying the path to an app.json file that defines the dataimport's target app. The tool imports the data into the Mobile back-end database and associates itwith the main web app defined in the specified app.json file.

Next Steps

Optionally, you can grant access to additional users.

Next, see About the Mobile Reference App Containers on page 16.

Granting Access to the Mobile Sample AppUse the pm grant command to grant additional users access to the Sample app.

About This Task

Users need access a Predix Mobile app so that they can download and configure the app to their device. Inthe development phase, the pm CLI automatically grants access to the user (developer) who has definedthe application. You can use the pm grant command to grant access to additional users for testingpurposes.

Procedure

• To grant other users access to the Sample app, run the following command in the directory thatcontains your app.json file.

$ pm grant --user=<username>

Next Steps

See About the Mobile Reference App Containers on page 16.

© 2020 General Electric Company 15

Get the Mobile Reference App Container

About the Mobile Reference App ContainersThe Predix Mobile SDK includes Reference App Containers for various platforms.

A Mobile Reference App Container is a native application that includes the Predix Mobile Client CoreServices framework that enables you to load, display, and run your Predix Mobile applications.

• For Android, you build the Predix Mobile Reference App Container for Android.• For iOS, you build the Predix Mobile Reference App Container for iOS.• For MacOS, you build the App Container for MacOS.

Downloading the Android Predix Mobile App ContainerTo run your Predix Mobile app, download and build the Predix Mobile App Container.

About This Task

Procedure

1. Go to https://github.com/PredixDev/PredixMobileAndroidSampleApplication.2. Download and extract the latest .zip file into your workspace.3. In a terminal, change the current directory to the location where you extracted the file.4. Set the app name and version in the ReferenceApplication/app/src/main/resources/

config.properties file:

pmapp_name=sample1pmapp_version=1_0

5. Set your Mobile service API endpoint and your logging level value in the ReferenceApplication/app/src/main/assets/config.properties file:

server_hostname=<your Mobile service instance API endpoint>logging_level=trace

Where server_hostname is the API endpoint for you Mobile service instance.6. In Android Studio, open the PredixMobileAndroidReferenceApplication project:

a) Click Open an Existing Android Studio Project and select the Reference Application.project.

b) Select the build.gradle file and click OK.

Next Steps

Running your Android Sample App on page 17

16 © 2020 General Electric Company

Running your Android Sample AppDisplay your app by running it in Android Studio.

Before You Begin

Download the Mobile Reference App Container and build your gradle project.

Procedure

1. In Android Studio, click Open an Existing Android Studio Project and select the ReferenceApplication. project.

2. Click the button.3. Select your target device or simulator and click OK.

The app is displayed in Android Studio.4. Log into the app. Use the developer username and password that you defined when you ran the Predix

Mobile service instance.setup script.

Downloading the iOS Predix Mobile App ContainerTo run your Predix Mobile app, download and build the Predix Mobile App Container.

About This Task

Procedure

1. Go to https://github.com/PredixDev/PredixMobileiOS/releases.2. Download and extract the latest .zip file into your workspace.3. In a terminal, change the current directory to the location where you extracted the file.4. Set the Mobile service endpoint in the app container by running the following script:

$ ./set-pm-host.sh5. In Xcode, double-click the PredixMobileiOS.xcodeproj file to open it.

Optionally, you can change the Xcode default simulator to match your device by selecting a simulatorfrom the drop-down list:

© 2020 General Electric Company 17

Figure 2: Selecting a simulator

Next Steps

Running your iOS Sample App on page 18

Running your iOS Sample AppDisplay your app by running the Sample app in Xcode.

Procedure

1. Start the Sample app in Xcode by clicking the button.2. Log into the app. Use the developer username and password that you defined when you created your

Predix Mobile service instance.The app is displayed in Xcode.

Next Steps

Now that you have a working Sample app, you can add a webapp to it. See Creating a Mobile Hello WorldWeb App on page 21.

Downloading the MacOS Predix Mobile App ContainerTo run your Predix Mobile app, download and build the Predix Mobile App Container.

About This Task

18 © 2020 General Electric Company

Procedure

1. Go to https://github.com/PredixDev/PredixMobileMacOS/releases.2. Download and extract the latest .zip file into your workspace.

3. In a terminal, change the current directory to the location where you extracted the file.4. Set the Mobile service endpoint in the app container by running the following script:

$ ./pm-set-pm-host.sh5. In Xcode, double-click the PredixMobileReferenceApp.xcodeproj file to open it.

6. Open the Info.plist file and make sure that the pmapp_name key and the pmapp_version keymatch the values that you defined in your app.json file.

By default these settings are:

pmapp_name: Sample1pmapp_version: 1.0

7. Optionally, you can change the Xcode default simulator to match your device by selecting a simulatorfrom the drop-down list:

Figure 3: Selecting a simulator

Next Steps

Running your MacOS Sample App on page 19

Running your MacOS Sample AppDisplay your app by running the Sample app in Xcode.

Procedure

1. Start the Sample app in Xcode by clicking the button.

© 2020 General Electric Company 19

The first time the MacOS container starts, the Settings dialog opens.

Figure 4: MacOS Sample App Settings dialog2. In the Server field, enter the endpoint URL for your Mobile service instance.

The endpoint is the Predix Mobile service api_gateway_short_route URL defined in ManuallySetting Up Predix Sync Service on page 9.

3. Click Save.

The Predix login screen appears.4. Log into the app. Use the developer username and password that you defined when you created your

Predix Mobile service instance.

20 © 2020 General Electric Company

Creating a Mobile Hello World Web App

Creating a Mobile Hello World Web AppCreate your own Hello World web app and add it to the Reference App Container.

Before You Begin

You should have the Sample app up and running. For more information, see About the Mobile SampleApp on page 12.

Setting up Your Directory StructureIn your workspace, add directories and files to your pm-apps/ and webapps/ directories.

Procedure

1. In pmworkspace/pm-apps/, create a mobile_hello_world_appdirectory.2. In mobile_hello_world_app/ directory, create a app.json file to define your app and its

webapp dependencies. An app can contain multiple webapps.3. In <workspace>/web-apps/, create a mobile_hello_world_webapp/ directory.4. In mobile_hello_world_webapp/, create a webapp.json file to define your webapp.5. In <workspace>/webapps/mobile_hello_world_webapp/, create a dist/ directory to

store the final webapp code. The directory will be specified in the webapp.json file.Your directory structure should look similar to this:

Figure 5: Directory Structure

© 2020 General Electric Company 21

Populating Your JSON FilesAdd JSON code to your app.json and webapp.json files.

Procedure

1. Copy the following JSON code into your pmapps/mobilehelloworldapp/app.json file todefine your app and its web app dependencies:

{"name": "mobile-helloworld-app","version": "1.0","starter": "mobile-helloworld-webapp","dependencies": {"mobile-helloworld-webapp": "0.0.1"

}}

where:

// name: name of your application// version: version of your application// starter: the web app that will open on starting the application// dependencies: web app dependencies of this application// name and version of a web app (see webapp.json below)

2. Copy this JSON code into your webapps/mobilehelloworldwebapp/webapp.json file todefine your web app definition:

{"name": "mobile--helloworld-webapp","version": "0.0.1","main": "index.html","nativeScroll": "false","src-folder": "./dist/","output-folder": "./dist-zip/"

}

where:

// name: name of your web application// version: version of your web application// main: starting html file of your web application// nativeScroll: boolean value that determines if the app shows thenative scroll bar or not

Coding the Mobile Hello World Web AppCreate an index.html file for your app.

About This Task

The index.html file is the HTML file that appears in a browser when a user starts the mobile_hello_world_app/ web app.

22 © 2020 General Electric Company

Procedure

From the web apps/ mobile_hello_world_app/dist/ directory, create an index.html filethat contains the following code:.

<!DOCTYPE html><html><head>

<title>Page Title</title></head><body>

<h1>Hello World</h1><p>Powered by Predix Mobile</p>

</body></html>

Publishing and Defining the Hello World Web AppUse the pm auth command to authenticate your user, then use pm publish and pm define toupload and define your app.

Procedure

1. Log into the pm tool, using the developer username and password recorded in your parameters textfile.

$ pm auth username password

Note:

The pm auth service authenticates you against the Predix Mobile service and stores anauthentication token locally. Once authenticated, you do not need to run this every time before youpublish or define.

2. Upload the web app with the publish command.

$ cd <workspace>/webapps/mobilehelloworldwebapp$ pm publish

3. Upload the web app definition file (app.json) with the define command:

$ cd <workspace>/pm-apps/mobilehelloworldwebapp$ pm define ./app.json

Running the Android Mobile Hello World AppDisplay your app by running it in Android Studio.

Procedure

1. Start the app in Android Studio by clicking the button.2. Select your target device or simulator and click OK.

The app is displayed in Android Studio.

© 2020 General Electric Company 23

3. Log into the app. Use the developer username and password that you defined when you created yourPredix Mobile service instance.

Running the iOS and MacOS Mobile Hello World Web AppUpdate your PLIST file and run your web app in Xcode.

Procedure

1. Open the PredixMobileReferenceApp.xcodeproj file that you used for the Sample app.

The Xcode project contains the Predix Mobile App Container. As the project builds, it imports yourapplication-specific code, specifying the code location in a property list (PLIST) file. You can use anew Xcode project for this, but it is simpler to change two properties in the property list file than toswitch from the Sample project to the mobile_hello_world_app project.

2. In Xcode, open the Info.plist file in the PredixMobileReferenceApp/ directory. Change thefollowing keys:

Key Value Description of value

pmapp_name MobileHelloWorld App name as specified in the app.jsonfile.

pmapp_version 01.0 App version as specified in the app.jsonfile.

3. Run the mobile_hello_world_app web app in Xcode by clicking the button.4. Enter the developer username and password saved in your parameters text file.

Your app is displayed in Xcode.

24 © 2020 General Electric Company

Release Notes

Release Notes

Related Reference

Predix Sync and SDK for Hybrid on page 25

Predix Sync and SDK for Hybrid

Q3 2017 Release

iOS/MacOSUse the zip files for the iOS/macOS framework (v3.5 and v3.4) to create your own containerapplication. The iOS framework is the same as the integrated iOS SDK framework in thePredixMobileiOS project. The macOS framework is the same as the integrated Mac SDK framework inthe PredixMobileMacOS project.

• Introduced hybrid UI database that allows web applications to load faster. Hybrid UI database is anadditional database that contains the hybrid UI pmapp and webapp documents and attachments.These documents and attachments are independently synchronized, and/or stored in theapplication bundle.

• Enhanced security for web apps that need to call the bridge using SSL encryption (secure HTTPsupport).

• Delete method is added to the Secure Storage Service.• Create, Update, and Delete documents feature is added to the database (DB) Service.• Querying views are added to DB Service.• Command Service is added.

Java

The official Predix Mobile Java SDK for use with Java based applications. For an example on how touse this SDK, see the PredixMobileJavaSampleApplication

Note: The Predix Mobile Java SDK is not meant to be used with or as a replacement for the AndroidSDK. If you are developing an Android application, use the Predix Mobile SDK for Android.

• Introduced hybrid UI database that allows web applications to load faster. Hybrid UI database is anadditional database that contains the hybrid UI pmapp and webapp documents and attachments.

• Enhanced security for web apps that need to call the bridge using SSL encryption (secure HTTPsupport).

• Command Service is added.• Bug fixes and performance enhancements.

Android

• Introduced hybrid UI database that allows web applications to load faster. Hybrid UI database is anadditional database that contains the hybrid UI pmapp and webapp documents and attachments.These documents and attachments are independently synchronized, and/or stored in the assetfolder.

• Enhanced security for web apps that need to call the bridge using SSL encryption (secure HTTPsupport).

• Command Service is added.

© 2020 General Electric Company 25

• Bug fixes and performance enhancements.

pm CLI Updates

• Support for hybrid UI database.• invalidate-session command added to pm command-line tool.• Minor bug fixes and enhancements.

Q2 2017 Release

JavaThe official Predix Mobile Java SDK for use with Java based applications. For an example on how touse the Java SDK, see sample application repo.

Note: The Predix Mobile Java SDK is not meant to be used with or as a replacement for theAndroidSDK. If you are developing an Android application, use the AndroidSDK.

There are several bug fixes and performance improvements in this release.

• Added the ability to apply filters to the push and pull replicators.• Improved support for Java based browsers like JavaFX to interact with the SDK.• Added support for JavaDoc.• Upgraded database support to v1.4 .• Improved handling of replication failures .• Fixed a crash that occurred while using the attime notifications.

iOS/MacOSUse the zip files for the Apple Framework v3.2 to create your own container application. The iOSframework is the same as the integrated iOS SDK framework in the PredixMobileiOS project. ThemacOS framework is the same as the integrated Mac SDK framework in the PredixMobileMacOSproject.

• Added ServiceInvokeNotification and PMAPIRequestHandledNotification tosupport metric gathering.

• Added notifications to provide more information when replication pauses or resumes.• Exposed UserManager to native code for easier access to user information post-login.• Upgraded database support to v1.4• Improved handling of repeated replication failures.

AndroidThe Predix Mobile Android SDK for use with the Predix Mobile Android Container. This release includesseveral bug fixes and performance improvements.

• Added the ability to apply filters to the push and pull replicators.• Added the ability to query the proximity sensor and orientation of the device.• Upgraded database support to v1.4 .• Improved handling of replication failures.• Fixed a crash that occurred when using the attime notifications.• Improved the JavaScript bridge performance.• Fixed a bug that prevented JavaScript bridge requests from executing when a json object passes

as the request body.• Reduced memory consumption.• Low memory warnings are no longer sent as broadcast messages.• Exposed an internal API to allow the developer to wipe the device's local database. This does not

cause data to be removed from the server.

26 © 2020 General Electric Company

pm CLI UpdatesNew commands added and enhancements to existing commands in pm command-line interface.

• role and conflicts commands are added to pm command-line tool.• role assignment option added to the channels command.• apps/webapps commands are enhanced.

Q1 2017 Release

JavaPredix Mobile SDK framework is now supported on the Java platform, including the Predix MobileClient Core Services Framework and the sample hybrid application using JavaFX .

Support for applications built with JavaFX.

Note: The Predix Mobile SDK for Java is not meant to be used with or as a replacement for theAndroidSDK. If you are developing an Android application, use the AndroidSDK.

iOS/MacOS

• Added Filter and Channel replication support.• Exposed DatabaseManager class for basic database interaction from native code.• Added ServiceInvokedNotification to gather basic metrics for requests/responses that

pass through the service router.

AndroidNew sample Android client hybrid application example.

pm CLI updatespm version command added to the pm command-line tool.

Q4 2016 Release

AndroidPredix Mobile SDK framework is now supported on the Android platform, including the Predix MobileClient Core Services Framework and the Predix Mobile Reference App Container for Android.

Apple iOS and MacOS

• SDK is compiled in XCode 8.3 and updated to Swift 3.• Updated various constants and enums to fit Swift 3 standards.• PGSDKLogger is deprecated. Native logging is supported via a new class: Logger.• Logging under iOS 10+ and macOS 10.12+ (Sierra) uses Apple's new Unified Logging System.• When logging out via /auth/logout, session cookies are automatically cleared. Since /boot/

restart calls /auth/logout this behavior also cascades to restarts.• If the server endpoint changes, the app will automatically reset itself.• Changed handling of application lifecycle events and notifications. These methods are available

through the PredixMobilityManager.applicationDelegates property.• Added documentation markup to code.

Q2 2016 Release

Mac OSPredix Mobile SDK framework is now supported on the MacOS platform, including the Predix MobileClient Core Services Framework and the Predix Mobile MacOS Reference App Container.

© 2020 General Electric Company 27

Example Microservices

• Sample Command Processor (https://github.com/PredixDev/MobileExample-Microservice-CommandProcessor).

• Sample Sync Processor that communicates with Predix Asset service (https://github.com/PredixDev/MobileExample-Microservice-AssetIntegration) .

iOS

• Requires device to have a passcode set by default.• Now optional for container app to post UIReadyNotification.• Simplified application-state event communication from Container to SDK.• Added ability to create full text search views.• Exposed default Type query to CDB service as “views/type” view name.• Updated User Settings service to support JSON objects or JSON fragments.• Added replicationAdditionalPushSettings and

replicationAdditionalPullSettings to PredixMobilityConfiguration to allowcontainers to finely tune additional replication settings.

• Updated SDKto allow passing web app documents as parameters to the container during offlineauthentication.

• Updated SDK to clear PMApp document cache whenPredixMobilityConfiguration.loadConfiguration is called.

• Added the following services to the Predix Mobile Client Core Services Framework:

◦ OpenURL◦ SecureStorage◦ TouchId

• Updated to Xcode 7.3.

Example iOS Services

• Basic native iOS service example (https://github.com/PredixDev/MobileExample-iOSService-Sample).

• Retrieve user's current location in iOS using a service example (https://github.com/PredixDev/MobileExample-iOSService-SingleLocation).

• Barcode scanner implementation for iOS using a native service (https://github.com/PredixDev/MobileExample-iOSService-Barcode-Scanner).

• Camera service implementation for iOS using a native service (https://github.com/PredixDev/MobileExample-iOSService-Camera).

Example iOS Clients

Enhancements for customizing the Predix Mobile Reference App for IOS:

• Store logs in the database (https://github.com/PredixDev/MobileExample-iOS-StoreLogsInDatabase)

• Create a non-hybrid, native iOS app with Mobile SDK (https://github.com/PredixDev/MobileExample-iOS-NativeIssuesListApp).

• Development-time rapid on-device web app iterations (https://github.com/PredixDev/MobileExample-iOS-DeviceDevWebAppUpdater).

28 © 2020 General Electric Company