Predix SDK for Hybrid - 2020 General Electric Company
←
→
Page content transcription
If your browser does not render page correctly, please read the page content below
Contents Predix SDK for Hybrid 1 About Predix SDK for Hybrid 1 Predix Mobile Command Line Interface 3 Predix Mobile Command-Line Interface (pm CLI) Commands 3 Installing the pm Command-Line Interface 3 pm api 3 pm apps 4 pm auth 5 pm channels 6 pm conflicts 7 pm data-delete 7 pm define 7 pm grant 8 pm import 8 pm invalidate-session 8 pm logs 8 pm oauth-token 9 pm publish 9 pm revoke 10 pm routes 10 pm version 11 pm webapps 13 pm workspace 13 Predix Mobile Client Core Services Framework 14 Predix Mobile Client Core Services Framework 14 Predix Mobile Authentication Service 14 Predix Mobile Boot Service 14 Predix Mobile Command Service 15 Predix Mobile Connectivity Service 15 Predix Mobile Data Access Services 15 Predix Mobile Logging Service 16 Predix Mobile OpenURL Service 17 ii Predix SDK for Hybrid
Predix Mobile Notify Service 17 Predix Mobile User Information Service 18 Predix Mobile User Settings Service 19 Predix Mobile Version Service 19 Predix Mobile Window Service 21 Predix Mobile Client Advanced Services 21 Configuration Preferences and Properties 23 Configuration Preferences and Properties 23 Troubleshooting Predix Sync and SDK for Hybrid 25 Troubleshooting UAA Service 25 UAA User Account not Found 28 User Token Invalid - Expired 28 Authentication Not Valid when Creating User 29 Running pm CLI in Debug Mode 29 Developing Apps for Apple Devices 31 Developing Apps for Apple Devices 31 Build an App with Native iOS Components 31 Submitting a Predix Mobile Container to the Apple App Store 31 Release Notes 33 Release Notes 33 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 SDK for Hybrid About Predix SDK for Hybrid The Predix SDK for Hybrid includes Reference App Containers for various platforms, the pm command-line tool, and several services that help you to extend the container. A Mobile Reference App Container is a native application that includes the Predix Mobile Client Core Services 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. The Predix Mobile (pm) command-line tool allows you to manage your Predix Mobile apps and your mobile back-end processes. The pm CLI commands depend on the Cloud Foundry and UAAC command-line tools, so make sure they are installed and properly configured prior to installing the pm tool. See Predix Mobile Command-Line Interface (pm CLI) Commands on page 3. The SDK for Hybrid provides several services as REST APIs to provide functionality to hybrid or native Mobile applications. The Client SDK consuming application (Predix Mobile App Container) can interact with these local services following this general URL structure: http://pmapi//. The Predix Mobile Reference App Container interprets URL requests and delegates them to the services in the Predix Mobile Client Core Services framework , which respond with a JSON payload describing the result of the call. See Predix Mobile Client Core Services Framework on page 14. © 2020 General Electric Company 1
Figure 1: Predix Mobile Reference App Container and Mobile Service See also https://github.com/PredixDev/PredixMobileSDK. 2 © 2020 General Electric Company
Predix Mobile Command Line Interface Predix Mobile Command-Line Interface (pm CLI) Commands Predix Mobile command-line interface (pm CLI) is a set of command line utility tools Use the pm CLI to manage your Predix Mobile apps and Mobile Service processes. The pm CLI includes a set of commands that are invoked through the pm command-line interface. The pm CLI commands use the following syntax: pm [options] [command] Installing the pm Command-Line Interface Use the pm CLI to manage Predix mobile users, roles, Predix mobile applications, and their web app dependencies. 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 on page 25. 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. pm api Use this command to display the current target, set the target, or change the target Predix Mobile Client API Gateway service. In a typical application-development workflow, you begin by targeting the Predix Mobile Client API Gateway service. The Client API Gateway and the UAA Service work together to ensure that all clients that access the Predix Mobile service possess a valid authentication token. In this example, the command returns an empty target. $ pm api info: API> © 2020 General Electric Company 3
You can pass the URL of your Predix Mobile API Gateway host to the command to set or change the target. For example: $ pm api https://015272.grc-apps.svc.ice.ge.com info: API> https://015272.grc-apps.svc.ice.ge.com Run each pm command against the targeted Client API Gateway. If you do not set a target, any pm command fails with an error. pm apps Use this command to list each Predix Mobile app defined in your Predix Mobile service. $ pm apps ┌──────────┬──────────────────────────────┬──────────┬───────────────── ───────────────────────┐ │ Type │ Name │ Version │ Channel │ ├──────────┼──────────────────────────────┼──────────┼───────────────── ───────────────────────┤ │ PM-APP │ FunctionalTestSuite │ 1.0.0 │ app- FunctionalTestSuite_1_0_0 │ │ │ │ │ │ ├──────────┼──────────────────────────────┼──────────┼───────────────── ───────────────────────┤ │ PM-APP │ ionic1 │ 1.0 │ app- ionic1_1_0 │ │ │ │ │ │ ├──────────┼──────────────────────────────┼──────────┼───────────────── ───────────────────────┤ │ PM-APP │ Sample1 │ 1.0 │ app- Sample1_1_0 │ │ │ │ │ roler- user │ │ │ │ │ role- user │ │ │ │ │ │ └──────────┴──────────────────────────────┴──────────┴───────────────── ───────────────────────┘ Include the -w parameter to list web apps deployed with your defined Predix Mobile apps. For example: $ pm apps -w ┌──────────┬──────────────────────────────┬──────────┬───────────────── ───────────────────────┐ │ Type │ Name │ Version │ Channel │ ├──────────┼──────────────────────────────┼──────────┼───────────────── ───────────────────────┤ │ PM-APP │ FunctionalTestSuite │ 1.0.0 │ app- FunctionalTestSuite_1_0_0 │ │ │ │ │ │ ├──────────┼──────────────────────────────┼──────────┼───────────────── 4 © 2020 General Electric Company
───────────────────────┤ │ WEB-APP │ e2e-app-test │ 0.0.1 │ webapp-e2e-app- test_0_0_1 │ ├──────────┼──────────────────────────────┼──────────┼───────────────── ───────────────────────┤ │ │ │ │ │ ├──────────┼──────────────────────────────┼──────────┼───────────────── ───────────────────────┤ │ PM-APP │ ionic1 │ 1.0 │ app- ionic1_1_0 │ │ │ │ │ │ ├──────────┼──────────────────────────────┼──────────┼───────────────── ───────────────────────┤ │ WEB-APP │ ionic_sidemenu │ 0.0.1 │ webapp- ionic_sidemenu_0_0_1 │ ├──────────┼──────────────────────────────┼──────────┼───────────────── ───────────────────────┤ │ │ │ │ │ ├──────────┼──────────────────────────────┼──────────┼───────────────── ───────────────────────┤ │ PM-APP │ Sample1 │ 1.0 │ app- Sample1_1_0 │ │ │ │ │ roler- user │ │ │ │ │ role- user │ │ │ │ │ │ ├──────────┼──────────────────────────────┼──────────┼───────────────── ───────────────────────┤ │ WEB-APP │ sample-webapp │ 0.0.1 │ webapp-sample- webapp_0_0_1 │ ├──────────┼──────────────────────────────┼──────────┼───────────────── ───────────────────────┤ │ │ │ │ │ └──────────┴──────────────────────────────┴──────────┴───────────────── ───────────────────────┘ pm auth Use this command to authenticate a user against the currently targeted Predix Mobile API Gateway host. Use the user name and password for an account that has been set up with UAA with the following command: $ pm auth user.name@ge.com password: info: API endpoint: https://d7dfcca0- c774-4f24-80b3-6c0c20106c8b.predix-uaa-staging.grc-apps.svc.ice.ge.com info: Authenticating... OK © 2020 General Electric Company 5
pm channels Use this command to manage the readable channels assigned to each user. For more information about channels, see . the Couchbase documentation. Options Option Description -c, --channel [channel_name...] Specify one or more channels. -D, --debug Set logging level to debug (returns more traces than verbose) -f, --format Format output in a tabular form. -l, --list List channels. -p, --purge Purge documents from all channels. The app.json definition file is ignored. -r, --role Assign a role to a user and assign multiple channels. --skip-ssl-validation Ignore transport layer security (TLS) certificate validation errors. u, --user [username...] Specify one or more users. -v, --verbose Set logging level to verbose. -h, --help List pm cli tool options. Examples Display user channel document: $ pm channels -u test@ge.com -l Assign a channel to a user: $ pm channels -u test@ge.com -c test_channel Delete (purge) a channel from user document: $ pm channels -u test@ge.com -c test_channel -p Assign a role to a user: $ pm channels -u test@ge.com -r role-test 6 © 2020 General Electric Company
Work with multiple users or channels: $ pm channels -u test1@ge.com -u test2@ge.com -c test_channel1 -c test_channel2 $ pm channels -u test1@ge.com,test2@ge.com -c test_channel1,test_channel2 Note: Do not insert a space before or after a comma when you enter multiple users or channels with the -u and -c options. pm conflicts Use this command to search for conflicted documents. Conflicts arise when multiple users edit a single document. You can use the conflicts command to search and replace the conflicted document with latest document on the server. The following example shows conflicted revisions : $ pm conflicts No id rev count conflicted revisions 1 workorders 2 {"rev":"387-ab2e035219fb9f1da416b190e84ebd89"} {"rev":"354-ab1d3b590bc6258c5cd0e54c2007a720"} Total conflicted revisions 2 OK pm data-delete Use this command to remove data from your Predix Mobile service. The pm data-delete command takes the same parameters as the pm import command, the -- data parameter that specifies the location of a raw JSON data file. It also takes an --app parameter that specifies the path to the app.json file defining the target app for the data deletion. This command does the inverse of the import command, disassociating each document from the main web app defined in the given app.json. pm define Use this command to define a Predix Mobile application as a collection of one or more web apps. The pm define command accepts an --app parameter that specifies the path to an app.json file. This app.json file defines the application as a collection of one or more web apps. © 2020 General Electric Company 7
pm grant Use this command to grant access to a Predix Mobile app for a specified user account. The pm grant command requires a single parameter specifying a Predix Mobile app by name or a path to an app.json file. By default it operates on the current authenticated user. However, it also takes a -- user parameter specifying a different user for an access grant. pm import Use this command to import data into your Predix Mobile service. The pm import command takes a --data parameter specifying the location of a raw JSON data file. It also takes an -–app parameter specifying the path to an app.json file that defines the data import's target app. The tool imports the data and associates it with the main web app defined in the specified app.json file. pm invalidate-session Use this command to invalidate active sessions for a user. Admin can use this command to invalidate a user's active sessions and block the user from replicating data. Option Description -D, --debug Set logging level to debug (returns more traces than verbose) -h, --help List pm CLI tool options. -v, --verbose Set logging level to verbose. u, --user [username...] Specify one or more users. Example Invalidate session(s) for a user: $ pm invalidate-session -u test@ge.com pm logs Use this command to display access or error logs. Use the pm logs command to show logs for a specified and , where: • is client-gateway Represents the primary public access point of a Predix Mobile service instance. All public traffic to and from a Predix Mobile service instance passes through this API Gateway. • is access or error ◦ error 8 © 2020 General Electric Company
Represents the error log of the service. The log contains exceptional events, including unrecoverable server exceptions. To retrieve error logs of the client-gateway service: $ pm logs client-gateway error ◦ access Represents the access log of the service. The log contains normal server HTTP/HTTPS access events. To retrieve access logs of the client-gateway service: $ pm logs client-gateway access pm oauth-token Use this command to display the OAuth token for the currently authenticated user account. The pm oath-token command dumps the raw token data to your standard output device. This can be used for debugging purposes when making authenticated requests from another tool such as cURL or POSTman. In this case, run the command without parameters, copy the entire token, and add it as the value of the Authentication header field in a raw HTTP request. $ pm oauth-token info: Getting OAuth token... info: OK bearer eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiJlOTZkZTUzMC0wYjU1LTRkZDEtOGRkZi1iODc1Zj gyOTAzZDkiLCJzdWIiOiJmZmRhYzcyYS1jYWQwLTRlZGUtOThlNi0xOTRmMDQyZDA1Y2IiL CJzY29wZSI6WyJwbS5hZG1pbiIsIm9wZW5pZCJdLCJjbGllbnRfaWQiOiJwbSIsImNpZCI6 InBtIiwiYXpwIjoicG0iLCJncmFudF90eXBlIjoicGFzc3dvcmQiLCJ1c2VyX2lkIjoiZmZ kYWM3MmEtY2FkMC00ZWRlLTk4ZTYtMTk0ZjA0MmQwNWNiIiwib3JpZ2luIjoidWFhIiwidX Nlcl9uYW1lIjoiY2xpZnRvbi5jcmFpZ0BnZS5jb20iLCJlbWFpbCI6ImNsaWZ0b24uY3Jha WdAZ2UuY29tIiwiYXV0aF90aW1lIjoxNDU2NDIwMzg4LCJyZXZfc2lnIjoiNGNhOGRkNjUi LCJpYXQiOjE0NTY0MjAzODgsImV4cCI6MTQ1NjQ2MzU4OCwiaXNzIjoiaHR0cHM6Ly8xYTg xY2QxMy02MGI2LTQ1ZjgtYjJiYi1lZjQ5MTdkMzg4OTMucHJlZGl4LXVhYS5ydW4uYXdzLX VzdzAyLXByLmljZS5wcmVkaXguaW8vb2F1dGgvdG9rZW4iLCJ6aWQiOiIxYTgxY2QxMy02M GI2LTQ1ZjgtYjJiYi1lZjQ5MTdkMzg4OTMiLCJhdWQiOlsicG0iLCJvcGVuaWQiXX0.vEEX Ux85u7NZ8owTduYOGteNOmDBnS5P_d5uhoSWgdypty0pVfcl4CWzoTkJ8AhDBP4jDZc3hhH 6_yfJ-8uFdRklwOKlx5- DPWlCzs2DquJpiNCt1JiOpnQbM7aT1CvTXUUnmpZhRy80_fLSyHalrvfFSJp2UxJxkmNBUC KTA- M1bmQyuY4g0DJedW1GGi4CpGQrWk4teeulHK2AM4TQoWzq3Hlzq8sEm11p2nI9lqy_rGKU1 rgyqxS5gs4leNrho1T65QHXBDLyI3gC3l8oaNJSIyTL389yE3EzQYabZcHsy7QPgrfTKyK_ LEE-_z_4F_4YCeJpWt4QIpddMQI3Qw pm publish Use this command to upload a Predix Mobile web app to your Predix Mobile service instance. The pm publish command takes a –webapp parameter that specifies the path to a webapp.json file. This file defines the web application to be published. The publish command grants access permission to the current authenticated user so you can load the app initially with the user account used for publishing. See the pm grant command for information on granting access to additional users. © 2020 General Electric Company 9
pm revoke Use this command to revoke access to a Predix Mobile app for a specified user account. The pm revoke command requires a single parameter specifying a Predix Mobile app by name or a path to an app.json file. By default it operates on the current authenticated user. However, it also takes a -- user parameter where you can specify a different user for access revocation. pm routes Use this command to list all defined routes that the Predix Command Router is aware of. These routes are used to route commands to individual command processors, which are microservices that you deploy using Cloud Foundry cf tools. Any document created from your Predix Mobile web app with a type equal to command can be routed to a command processor and processed. A command router is a microservice that is tasked with routing pending command documents to configured command processors. A command document is a JSON document with a type field value as command and a status field. The command document format is similar to an HTTP request, with a request and response section contained in the same document. The Command Router manages the state of a given command from the time the document arrives on the server until the router writes the result from an invoked Command Processor to the response section of the document. The Command Router translates a command document into an equivalent HTTP request to a Command Processor. The HTTP response from the Command Processor is serialized and placed in the response section of the originating command document. Related Reference pm add-route on page 10 Use this command to associate an HTTP URL with a named Predix Mobile command route. pm remove-route on page 11 Use this command to remove an HTTP URL associated with a named Predix Mobile command route. pm add-route Use this command to associate an HTTP URL with a named Predix Mobile command route. For instance, a route named /search can be associated with the URL http://predix-mysearch- webapp.run.aws-usw02-pr.ice.predix.io. Any command discovered by the command router containing this name is then be sent to the web service running at http://predix-mysearch-webapp.run.aws-usw02- pr.ice.predix.io to be processed. Related Reference pm routes on page 10 Use this command to list all defined routes that the Predix Command Router is aware of. pm remove-route on page 11 10 © 2020 General Electric Company
Use this command to remove an HTTP URL associated with a named Predix Mobile command route. pm remove-route Use this command to remove an HTTP URL associated with a named Predix Mobile command route. To remove a route named /legacy-addition-service, issue the following command: $ pm remove-route /legacy-addition-service Related Reference pm routes on page 10 Use this command to list all defined routes that the Predix Command Router is aware of. pm add-route on page 10 Use this command to associate an HTTP URL with a named Predix Mobile command route. pm version Use this command to retrieve version and device information. Method: GET URL: http://pmapi/version Output: Status code 200, data in JSON dictionary form with the following keys: Key Description SDK supported predix_mobile_sdk_versi Version number of the Predix Mobile SDK iOS, MacOS, Android, JavaSDK on predix_mobile_sdk_build Build version number of the Predix Mobile iOS, MacOS, Android, JavaSDK _version SDK application_version Version number of the current container iOS, MacOS app application_build_versi Build version number of the current iOS, MacOS on container app application_bundle_id Bundle ID of the iOS container app iOS, MacOS server_hostname Configured server hostname iOS, MacOS, Android, JavaSDK device_model Hardware description or device type iOS, MacOS, Android device_OS Operating system name iOS, MacOS, Android, JavaSDK device_OS_version Operating system version number iOS, MacOS, Android, JavaSDK database_version Database version number iOS, MacOS, Android, JavaSDK locale Current running locale iOS, MacOS, Android, JavaSDK © 2020 General Electric Company 11
Key Description SDK supported PredixMobileVersion Matches This key provided for compatibility. May predix_mobile_sdk_build be deprecated in the future. _version ContainerVersion Matches This key provided for compatibility. May application_build_versi be deprecated in the future. on SyncGateway Matches server_hostname This key provided for compatibility. May be deprecated in the future. Platform Differences Due to differences in platforms, not all keys are supported on all platforms. The iOS client will not include the following key: • java_version The Android SDK will not include these keys: • java_version • application_version • application_bundle_id • application_build_version Platforms built with Java SDK will not include these keys by default: • application_version • application_bundle_id • application_build_version • device_model Example Response { "locale":"en_US", "PredixMobileVersion":"1.7.361", "SyncGateway":"abc1234.run.aws-usw02-pr.ice.predix.io", "server_hostname":"abc1234.run.aws-usw02-pr.ice.predix.io", "ContainerVersion":"1.7", "database_version":"1.2.1 (unofficial)", "device_model":"iPhone", "application_bundle_id":"com.ge.ent.PredixMobileReferenceApp", "predix_mobile_sdk_version":"1.7", "device_OS":"iPhone OS", "device_OS_version":"9.3", "application_build_version":"1.7", "predix_mobile_sdk_build_version":"1.7.361", "application_version":"1.7" } 12 © 2020 General Electric Company
pm webapps Use this command to list all web apps uploaded to your Predix Mobile service instance. For example: $ pm webapps Name Version Channel pm-minimal-app 0.0.1 webapp-pm-minimal- app_0_0_1 OK pm workspace Use this command to create a workspace for your project. pm workspace -c You can also clone any of the examples found at https://github.com/PredixDev/PredixMobileSDK and then use the pm workspace command from within the example's root folder. © 2020 General Electric Company 13
Predix Mobile Client Core Services Framework Predix Mobile Client Core Services Framework The Predix Mobile Client SDK provides REST API-based services that add functionality to hybrid and native mobile applications. The Client SDK consumer application, the Predix Mobile app container, can interact with these local services following this general URL structure: http://pmapi//. The Predix mobile app container interprets URL requests and delegates them to the services in the Predix Mobile Client Core Services framework , which return a JSON payload describing the result of the call. Predix Mobile Authentication Service The Authentication service facilitates tasks such as login, logout, and management and validation of offline authentication credentials. The offline authentication web app example shows how to call the service. Reference documents: https://github.com/PredixDev/PredixMobileSDK/wiki/Authentication Method/URL Description POST http://pmapi/auth Start the authentication process, displaying an offline or online authentication page. POST http://pmapi/auth/setup Start the offline authentication setup process, displaying the offline authentication setup page. PUT http://pmapi/auth//setup Set up a user's offline password by returning a token to the authentication setup page. POST http://pmapi/auth/update Start the offline authentication management process, displaying the offline management setup page where a user can change the account password. PUT http://pmapi/auth// Authenticate a user's offline password. authenticate PUT http://pmapi/auth// Update a user's offline password. update DELETE http://pmapi/auth Cancel a current in-process login or setup, resetting the authentication service to allow a new POST request. GET http://pmapi/auth Retrieve the status of the login process using HTTP Status codes Predix Mobile Boot Service Use the Boot service to start the app-initialization process in the Predix Mobile Client SDK environment, or to restart an app. The offline authentication web app example shows how to use the Boot service to initiate an app restart. Reference documents: https://github.com/PredixDev/PredixMobileSDK/wiki/Boot 14 © 2020 General Electric Company
Method/URL Description POST http://pmapi/boot/start Starts the app initialization process. If the user is not authenticated, the service calls the User Authentication service. If online, the service starts Couchbase replication. POST http://pmapi/boot/restart Reinitializes the app. The service shuts down the current running Predix Mobile app. It also logs off the user, shuts down Couchbase, and recalls the boot start process. Predix Mobile Command Service Use the Command service to create, modify, and manage commands. Commands are specific instructions sent to the Predix Mobile service, the Command Processor in the Predix Mobile service pick up these specific instructions for processing. Reference documents: https://github.com/PredixDev/PredixMobileSDK/wiki/Command Method/URL Description POST http://pmapi/command Create a command with a dictionary of name/value pairs encompassing the command for the Command Processor. PUT http://pmapi/{commandId} Update a command. GET http://pmapi/{commandId} Retrieve a command. GET http://pmapi/command Retrieve all commands. Predix Mobile Connectivity Service Use the Connectivity service to retrieve a device's current connectivity state. The Mobile Offline Login web app example shows how to use the service to make the call. Reference documents: https://github.com/PredixDev/PredixMobileSDK/wiki/Connectivity Method/URL Description GET http://pmapi/connectivity Retrieves state of network connectivity and authentication for the device. Predix Mobile Data Access Services The Predix Mobile Core Services Framework includes a high-level data access service and a low-level data access service. Use the high-level data access service (DB) to start replication, query the status of replication, add and retrieve attachments from storage, and to close the database. It also supports basic document retrieval and query by type. The low-level data acess service (CDB) provides the ability to read and write documents and is directly connected to the actual storage engine. Typically, you use the high-level service for overall storage engine operations and you use the low-level service for direct CRUD operations to the storage service. © 2020 General Electric Company 15
DB (Data Access High-level) Service The DB Data Access high-level service provides local database management services. In addition, it provides an abstraction layer to simplify data-access interactions such as saving and retrieving documents. The Predix Mobile Sample App shows how to use a Data Access High-level service function to retrieve a document and its details. Reference documents: https://github.com/PredixDev/PredixMobileSDK/wiki/Data-Access-High-level Method/URL Description POST http://pmapi/db/databaseName/ Start replication and continue as long as the device has replication connectivity and is authenticated. GET http://pmapi/db/databaseName/ Retrieve the replication status. replication GET http://pmapi/db/databaseName/ Retrieve the document. document/documentId POST http://pmapi/db/close Close CB database. CDB (Data Access Low-level) Service Use the CDB service to perform basic data-retrieval and updates for the local document database This service provides create/read/write/delete document operations and query views. The CDB service supports database-level commands rather than server-level commands. The Predix Mobile Sample App shows how to use the Data Access Low-level service to retrieve documents. URL Description http://pmapi/cdb/databasename/... See the Couchbase Lite REST API documentation for an overview of the available resources. Predix Mobile Logging Service Use the Logging service to send log output to the device’s logging system. You send a log message inside a JSON object using a PUT request to this service. The JSON object should include a log property containing the actual log message, and a log level classification property. The Predix Mobile Offline Login web app example shows how to use the service to send a log message. Reference documents: https://github.com/PredixDev/PredixMobileSDK/wiki/Logging Method/URL Description PUT http://pmapi/log Send log output to the logging system. 16 © 2020 General Electric Company
Predix Mobile OpenURL Service Use the OpenURL service to open a URL on a device that is external to your app. Reference documents: https://github.com/PredixDev/PredixMobileSDK/wiki/OpenURL Method/URL Description POST http://pmapi/openurl Opens a URL on a device that is external to your app. Example JSON Input Open the mail app, and start a new message: { "url": "mailto://someone@example.com?Subject=Hello%20again" } Initiate a phone call: { "url": "tel:1-800-555-1212" } Open Facebook: { "url": "fb://feed" } Open Page in Safari: { "url": "https://www.google.com" } Predix Mobile Notify Service Use the Notify service to relay event notifications from the client device to the web app, or to alert the user at a specific time if the container app is not running. For example, this service can run a JavaScript function in the current web app when the following conditions are met: • A specific database document changes. • The application is about to go into the background. © 2020 General Electric Company 17
• The device's connectivity state has changed. • The device is currently replicating data with the server. • A specific time has been reached. The Mobile Send Command web app example shows how to send a POST request to the Notify service for a specific event, DocumentChangedNotification, with a document ID. This event is triggered when a specific document in the data store changes. In the example, the id of the source document is included in the URL. In this example, gotChanges defines a JavaScript function that is invoked when the notification occurs. This function is passed as the POST body. Reference documents: https://github.com/PredixDev/PredixMobileSDK/wiki/Notify Event Notifications Method/URL Description POST http://pmapi/notify/events/ Subscribe to a notification. • ReachabilityWatcherNotification Posted when the Reachability Watcher detects a connectivity state change. • DatabaseDownloadNotification Describes current download state. • DocumentChangedNotification/ Describes document changes. • InitialReplicationCompleteNotific ation Posted when the local database has completed its first replication. After this point, the database is considered up- to-date and it is safe to store and retrieve data. This notification is only useful for Container observers, not web apps. By the time a web app starts, this notification has already occurred. See https://github.com/PredixDev/PredixMobileSDK/wiki/ Posted-Notifications. DELETE http://pmapi/notify/events Unsubscribe from all subscribed notifications. DELETE http://pmapi/notify/events/ Unsubscribe from . GET http://pmapi/notify/events Retrieve all currently subscribed notifications. GET http://pmapi/notify/events/ Retrieve a specific notification. Predix Mobile User Information Service Use the User Information service to retrieve a logged-in user and display that user's assigned data elements (such as a work item). The Mobile Sample App shows how to use the User Information service to retrieve user details. 18 © 2020 General Electric Company
Reference documents: https://github.com/PredixDev/PredixMobileSDK/wiki/User-Information Method/URL Description GET http://pmapi/user Retrieve user information. GET http://pmapi/user/data-element Retrieve a specified data element for the user. POST http://pmapi/user Write the user information. Predix Mobile User Settings Service Use the User Settings service to facilitate unencrypted data storage and retrieval on a given device. Use this service to define user preferences, or to define information that needs to persist when the application stops running, but is not security-sensitive or required to be stored in the local database. Method/URL Description GET http://pmapi/usersettings/ Retrieve the user settings based on a setting key. settingkey GET http://pmapi/usersettings Retrieve all user settings. POST http://pmapi/usersettings/ Set the user settings based on the setting key. settingkey POST http://pmapi/usersettings Store user settings. DELETE http://pmapi/usersettings/ Delete a specified user's settings based on a setting key. settingkey Predix Mobile Version Service Use the Version service to retrieve version and device information. Reference documents: https://github.com/PredixDev/PredixMobileSDK/wiki/Version © 2020 General Electric Company 19
Method/URL Description GET http://pmapi/version Status code 200, data in JSON dictionary form with the following keys: • predix_mobile_sdk_version: Version number of the Predix Mobile SDK • predix_mobile_sdk_build_version: Build version number of the Predix Mobile SDK • application_version: Version number of the current container app • application_build_version: Build version number of the current container app • application_bundle_id: Bundle Id of the iOS container app • java_version: Version number of Java • server_hostname: Configured server hostname • device_model: Hardware description or device type • device_OS: Operating system name • device_OS_version: Operating system version number • database_version: Couchbase Lite version number • locale: Current running locale These keys are provided for compatibility. May be deprecated in the future. • PredixMobileVersion: Matches predix_mobile_sdk_build_version • ContainerVersion: Matches application_build_version • SyncGateway: Matches server_hostname Sample Output { "locale":"en_US", "PredixMobileVersion":"1.7.361", "SyncGateway":"abc1234.run.aws-usw02-pr.ice.predix.io", "server_hostname":"abc1234.run.aws-usw02-pr.ice.predix.io", "ContainerVersion":"1.7", "database_version":"1.2.1 (unofficial)", "device_model":"iPhone", "application_bundle_id":"com.ge.ent.PredixMobileReferenceApp", "predix_mobile_sdk_version":"1.7", "device_OS":"iPhone OS", "device_OS_version":"9.3", "application_build_version":"1.7", "predix_mobile_sdk_build_version":"1.7.361", "application_version":"1.7" } Platform Differences The iOS and MacOS client do not include this key: • java_version 20 © 2020 General Electric Company
Predix Mobile Window Service Use the Window service to manage the display of web apps in the container user interface. Reference documents: https://github.com/PredixDev/PredixMobileSDK/wiki/Window Method/URL Description POST http://pmapi/window/pane? Load a specified web app by appname. webapp=appname If using appname for the API call, your app.json file's dependencies must contain your web app name and version. For example: { "name": "FunctionalTestSuite", "version": "1.0.0", "starter": "e2e-app-test", "dependencies": { "e2e-app-test": "0.0.1", "webapp-pm-minimal-app": "0.0.1" } } POST http://pmapi/window/pane? Load a specified web app by appnameID. Use the pm webapp=appnameID webapps command to obtain the ID. For example: $ pm webapps Name Version Channel pm-minimal- app 0.0.1 webapp-pm-minimal- app_0_0_1 OK POST http://pmapi/window/ Show an error dialog.“” showseriouserrorpage POST http://pmapi/window/spinner Set the spinner. GET http://pmapi/window/spinner Retrieve the current state of the spinner. Predix Mobile Client Advanced Services These advanced services are available only on the iOS platform. © 2020 General Electric Company 21
Predix Mobile Local Notifications Service Use the Local Notifications service to set, retrieve, and delete notifications that are local to a device. Reference documents: https://github.com/PredixDev/PredixMobileSDK/wiki/Notify#local-notifications. Platforms supported: iOS Method/URL Description POST http://pmapi/notify/attime Set notification based on local attributes. GET http://pmapi/notify/attime Get a specific local notification. DELETE http://pmapi/notify/attime Delete all local notifications. DELETE http://pmapi/notify/attime/ Delete a specific local notification. notificationId Predix Mobile Secure Storage Service Use the Secure Storage service to facilitate storage and retrieval of data that is persistent in an encrypted state, possibly requiring authentication to retrieve. Reference documents: https://github.com/PredixDev/PredixMobileSDK/wiki/Secure-Storage Method/URL Description iOS POST http://pmapi/ Post data to storage that is persistent in Yes secstorage an encrypted state. GET http://pmapi/ Retrieve data from storage that is Yes secstorage/key? persistent in an encrypted state. prompt=override+prompt Predix Mobile TouchId Service Use the TouchId service to determine if a device supports biometric fingerprint identification, and if the current owner is the device owner. Reference documents: https://github.com/PredixDev/PredixMobileSDK/wiki/TouchId This service is available only on the iOS platform. It is only supported on devices that support TouchID. Method/URL Description GET http://pmapi/touchid Determine if the device supports biometric identification. GET http://pmapi/touchid/validate? Determine if the current owner is the device owner. prompt=promptstring 22 © 2020 General Electric Company
Configuration Preferences and Properties Configuration Preferences and Properties The Predix Mobile SDK has two types of on-device configuration storage: Preferences and Properties. Application users can change Preferences on a device, whereas a developer sets Properties at compile- time. Preferences Preferences consist of developer-set defaults, user-changeable current values, and a user interface to change those values. For iOS, the Preferences defaults are stored in the Mobile applications root.plist file in Xcode. The Preferences defaults are used to populate the iOS and the macOS’s standard UserDefaults object. In iOS, the user can manipulate those values using the standard iOS Settings app. For macOS, since there is no standard Settings app, the reference app container includes a Preferences user interface that you can mimic to construct your own UI for these values, and then that UI can update those values in the UserDefaults object. For Android, the default values are stored in assets/preference_defaults.properties file in the application's Android Studio project, and the storage implementation uses the Android SharedPreferences object, along with a sample UI provided in the reference app container. By default, the server endpoint and default logging level is stored in Preferences, however again, this can be changed using the PredixMobileConfiguration class. The defaults are shown in the table below. Properties Because properties are set by the developer at compile-time, they are read-only configuration elements for users, and are not expected to change. In the iOS and macOS implementations of the Predix Mobile SDK, Properties are stored in the application project’s info.plist file. For Android, properties are expected to be in the resources/config.properties file; although this filename can be changed by updating the configurationPropertiesFilename property of the PredixMobileConfiguration class. By default the pm-app name and version configuration is stored in Properties on the iOS, macOS, and the Android implementations of the Predix Mobile SDK. However, this can be changed by updating the appropriate properties in the PredixMobileConfiguration object. The defaults are shown in the table below. © 2020 General Electric Company 23
Configuration Defaults This table identifies the default key name properties and location properties in the configuration control class. Configuration element Key Name Property Location Property Predix Mobile app name pmappDocumentNameKey pmappDocumentNameConfig Location Predix Mobile app version pmappDocumentVersionKey pmappDocumentVersionCon figLocation Server endpoint serverEndpointConfigKey ServerEndpointConfigLoc ation Logging level loggingLevelConfigKey loggingLevelConfigLocat ion Other values may be stored in Preferences and Properties as needed, depending on the platform implementation. Refer to the exposed properties of the platform’s configuration control class. Example Configuration Changes Change App Document Name Key To change the key used to extract the Predix Mobile app name from configuration from the default pmapp_name toPredixMobileAppName: iOS/MacOS PredixMobilityConfiguration.pmappDocumentNameKey = "PredixMobileAppName" Android/Java PredixMobileConfiguration.pmappDocumentNameKey = "PredixMobileAppName"; Change App Name Configuration Location To change the location used to retrieve the Predix Mobile app name from the default Properties configuration to the Preferences configuration: iOS/MacOS PredixMobilityConfiguration.pmappDocumentNameConfigLocation = ConfigurationLocation.settings Android/Java PredixMobileConfiguration.pmappDocumentNameConfigLocation = PredixMobileConfiguration.ConfigurationLocation.PREFERENCES; 24 © 2020 General Electric Company
Troubleshooting Predix Sync and SDK for Hybrid Troubleshooting UAA Service The following are general troubleshooting tips and issues you may experience when using Security services. • Troubleshooting UAA Command Line Interface (UAAC) Installation Issues • Troubleshooting Oauth2 Issues Troubleshooting UAA Command Line Interface (UAAC) Installation Issues There are a number of ways you can install UAAC. The procedure lists recommended installation steps for Windows and Linux users. Windows 1. Install Ruby from http://rubyinstaller.org/downloads. Use the stable version of Ruby (version 2.1.x). Note: The 64-bit versions of Ruby are relatively new and not all the packages have been updated to be compatible with it. To use the 64-bit version you will require compiler knowledge, and you will need to be prepared to solve dependency issues. 2. Install the Ruby development kit. Follow the installation steps at https://github.com/oneclick/rubyinstaller/wiki/Development-Kit. 3. Download Gem for UAAC, cf-uaac*.gem, from https://rubygems.org/gems/cf-uaac. 4. Install the cf-uaac*.gem gem. gem install cf-uaac*.gem 5. Test if the installation was successful. uaac help Linux Installation of UAAC on Linux or Mac is easier if you use the bundler gem to install all the required dependencies for cf-uaac gem install. 1. Verify that the Ruby version of Ruby is a stable version (version 2.1.x). ruby --version 2. Download Gem for Bundler, bundler.gem, from https://rubygems.org/gems/bundler. 3. Install the bundler gem. gem install bundler 4. Generate a Gemfile with the default rubygems.org source. bundle init The Gemfile is created in the same location as the bundler gem. © 2020 General Electric Company 25
5. Edit the new Gemfile to include the gems you want to include in the bundle. # A sample Gemfile source "https://rubygems.org" # gem "rails" gem 'nokogiri' gem 'rack', '~>1.1' gem 'rspec', :require => 'spec' gem 'cf-uaac' 6. Install all of the required gems from your specified sources. bundle install 7. Install the cf-uaac gem. gem install cf-uaac 8. Test to see if the installation was successful. uaac help Troubleshooting Oauth2 Issues Predix platform services use OAuth2 for authentication. Errors related to OAuth2 include the HTTP 401 Authorization error. To troubleshoot an OAuth2 issue, check the claims in a user or application token. For example, if you receive an HTTP 401 authorization error, you need to make sure that the token was issued from the correct UAA (iss claim) with the required scopes (scope). Caution: Using online tools to decode tokens comes with several risks. If a token is stolen, it can be used by anyone to access protected resources without any other credentials. Even after a token expires, its claims information exposes internal details about Predix applications and systems, which can be used to help in other attacks. Use the following tools to decode tokens on your local machine: • UAAC Use the following command to decode a token: uaac token decode Example: uaac token decode eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovLzEyMzQxMzQz MTI 0MTMubXktZG9tYWluLmNvbS9vYXV0aC90b2tlbiIsInNjb3BlIjoidGVzdCIsInN1YiI6 Imp vZUBleGFtcGxlLmNvbSJ9.KGzJ12fOqBF2sxi9F3oFG3FDWBmNES9TU2j7yc_XyP0 Note: no key given to validate token signature iss: https://1234134312413.my-domain.com/oauth/token scope: test sub: joe@example.com 26 © 2020 General Electric Company
Note: As indicated in the UAAC output message, you can provide a public key to validate the issuer of the token. • Base64 The JWT claims are Base64-encoded JSON. If you do not need to validate the JWT issuer, use a tool that can decode the token claims section. A JWT token uses the following format: base64encoded_header.base64encoded_claims.signature Use the following command to list the claims: echo | cut -f 2 -d . | base64 --decode Example: ~/dev$ echo 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovLzEyMzQxM zQzMTI0MTMubXktZG9tYWluLmNvbS9vYXV0aC90b2tlbiIsInNjb3BlIjoidGVzdCIsIn N1Y iI6ImpvZUBleGFtcGxlLmNvbSJ9.KGzJ12fOqBF2sxi9F3oFG3FDWBmNES9TU2j7yc_Xy P0' | cut -f 2 -d . | base64 --decode {"iss":"https://1234134312413.my-domain.com/oauth/ token","scope":"test","sub":"joe@example.com"} ~/dev$ SSLException while targeting a UAA instance using UAAC When targeting multiple UAA instances using UAAC, the client is able to authenticate some UAA instances successfully, but for others it generates an SSLException. Cause One probable cause of this issue is your proxy settings. Additionally the versions of UAAC, Ruby, and OpenSSL that you are using do not support a new GE certificate and you need to be able to accept TLS1.2 connections. Solution As a workaround, you can use the --skip-ssl-validation flag. Use the following command to check the SSL certificate: openssl ciphers -v | awk '{print $2}' | sort | uniq Use the latest versions of UAAC, Ruby and OpenSSL. © 2020 General Electric Company 27
UAA User Account not Found System cannot find account while setting up user access to your app. Condition When adding a user to authenticate as part of granting rights to use your app using the pm grant command, you receive a message that user account is not found. Cause The username is not valid. Solution When you grant access using the pm grant command, the user name entered must match the user account set up in a corresponding UAA instance. For more information on creating a user in UAA, see Creating Users in a UAA Instance. User Token Invalid - Expired When adding a user to use a Predix Mobile app, you receive a message that the user token has expired. Condition When adding a user to authenticate as part of granting rights to use your app, you receive a message that the user token is expired: { "error": "invalid_token", "error_description": "Invalid access token (expired): ... expired at Sat Nov 14 15:51:53 UTC 2015" } Cause The user has been added, but the token ID (id.url) for the user has expired. Solution Use the following pm-cli command to fetch the correct token for the user (where "admin" is the example user you are trying to add): uaac token client get admin -s PredixMobile The command returns the target and context for the user. The following sample shows a successful response: Successfully fetched token via client credentials grant. Target: https://894c559b-430a-4d10-83e8-b6ded9e46ced.
here> .com Context: admin, from client admin Authentication Not Valid when Creating User Condition When you run the pm-add-developer script to create a developer user on the UAA server and grants them access to the pm.admin group, you get an authentication error. Cause The user has been added, but the token ID (id.url) for the user has expired. Solution Try re-logging into the UAA server, using the standard uaac commands, and then execute the user creation operation again: $> uaac target --skip-ssl-validation $> uaac token client get (enter UAA admin password when prompted) Running pm CLI in Debug Mode Use debug mode to troubleshoot pm CLI commands that produce error messages. Condition When running a pm command, you receive an error message. Solution Run the command in debug mode. The following example shows the syntax for running the pm auth command in debug mode: pm auth --debug user password You should see output similar to the following: HTTP-Util: GetResource: request options: { "method": "GET", "url": "617421.grc-apps.svc.ice.ge.com/login", "headers": { "User-Agent": "pm-cli 1.0", "Accept": "application/json", "Content-Type": "application/json" }, "json": true} © 2020 General Electric Company 29
In the example above, if you were certain that your credentials were OK, you would check to make sure the URL matches the URL bound to your pm-service. 30 © 2020 General Electric Company
Developing Apps for Apple Devices Developing Apps for Apple Devices Build an App with Native iOS Components Use this sample code as a model for creating a native iOS app. This example shows how to create a native iOS app that is similar to the hybrid issues-tracking Sample app. It uses a native UI instead of a hybrid one. Native apps can be used to create entire iOS apps, or components of larger native or hybrid apps that require a particular native look and feed, or for performance reasons, and so on. This example demonstrates a number of techniques, including creating database views, calling services from native Swift code, and using properties from the web app document to determine what native components to load. To learn how to create a non-hybrid, native iOS app with the Mobile SDK see https://github.com/ PredixDev/MobileExample-iOS-NativeIssuesListApp. Submitting a Predix Mobile Container to the Apple App Store Use the Apple Enterprise license program to publish apps for general consumption. About This Task Many companies that develop mobile software use internal IT groups and procedures to publish apps in the Apple App Store. If your app’s audience is exclusively composed of company employees, your company may qualify for the Apple Enterprise license program. This program allows you to internally publish apps without going through the App Store and making your app available to the general public. Because an app distributed through the Enterprise license program does not get published to the App Store, the app is not subject to the strict review requirements that public App Store apps must pass. See the Apple developer site for more details: https://developer.apple.com/programs/enterprise/. If your app is intended for a larger audience than company employees, then it must be published in the App Store for distribution. Software development for devices must meet specific Apple iOS requirements. The App Store Distribution Tutorial is a key starting point in the Apple content repository. Follow these general steps to register your app in the App Store: Procedure 1. Register as an Apple Developer: https://developer.apple.com/programs/. 2. Create your app’s bundle ID, App Store distribution certificate, and provisioning profile on the Apple Developer site. 3. Build and sign your app in XCode. 4. Create the app entry in iTunesConnect, including your screenshots, description, keywords, support URL, and any other required information. 5. Upload your app binary files to iTunesConnect. © 2020 General Electric Company 31
Apple reviews your app, generally within two weeks. New apps are automatically published after approval. If Apple rejects your app, the rejection email includes details. You can then address the problem and resubmit. 32 © 2020 General Electric Company
Release Notes Release Notes Related Reference Predix Sync and SDK for Hybrid on page 33 Predix Sync and SDK for Hybrid Q3 2017 Release iOS/MacOS Use the zip files for the iOS/macOS framework (v3.5 and v3.4) to create your own container application. The iOS framework is the same as the integrated iOS SDK framework in the PredixMobileiOS project. The macOS framework is the same as the integrated Mac SDK framework in the PredixMobileMacOS project. • Introduced hybrid UI database that allows web applications to load faster. Hybrid UI database is an additional database that contains the hybrid UI pmapp and webapp documents and attachments. These documents and attachments are independently synchronized, and/or stored in the application bundle. • Enhanced security for web apps that need to call the bridge using SSL encryption (secure HTTP support). • 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 to use this SDK, see the PredixMobileJavaSampleApplication Note: The Predix Mobile Java SDK is not meant to be used with or as a replacement for the Android SDK. 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 an additional 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 HTTP support). • 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 an additional database that contains the hybrid UI pmapp and webapp documents and attachments. These documents and attachments are independently synchronized, and/or stored in the asset folder. • Enhanced security for web apps that need to call the bridge using SSL encryption (secure HTTP support). • Command Service is added. © 2020 General Electric Company 33
You can also read