Boot Camp Guide V3
User Manual: Pdf
Open the PDF directly: View PDF 
.
Page Count: 258
| Download | |
| Open PDF In Browser | View PDF |
Predix Developer Boot Camp Student Lab Guide March 2016 GE Digital Predix © 2016 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 GE, GE Global Research, GE Digital, 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. GE Digital Page i Predix Developer Boot Camp Getting Started This guide provides step-by-step instructions for lab exercises. Each lab corresponds to a topic covered in class and provides students with hands-on experience developing UI components on the Predix platform. Course Prerequisites: Courses are intended to introduce developers to using the Predix Platform. It is assumed that students have familiarity with: Development platforms and frameworks Java, HTML, JavaScript, CSS, Angular, Polymer and Sass Log into the Hosted Environment You received an email prior to the start of class with your access code. Use that access code to log into https://predix.instructorled.training Tip: You do not need to provide a password. Click the Lab Link and click Connect to the lab Click the Log in button (you do not need to change the Login or Password here) Click the Yes button to resize the desktop to your screen You will see a message that the desktop is being resized and you are connected to the remote session. Note: All lab exercises will be completed in this hosted environment on the DevBox. Page ii Predix Training Programs How to Copy and Paste in your Environment In a Terminal window Copy using Ctrl + Shift + C Paste using Ctrl + Shift + V All other applications Copy using Ctrl + C Paste using Ctrl + V GE Digital Page iii Predix Developer Boot Camp Page iv Predix Training Programs Lab 1: Getting Started with Cloud Foundry Lab 1: Getting Started with Cloud Foundry Learning Objectives By the end of the lab, you will be able to: Log into Cloud Foundry Explore the Predix Service Catalog/Marketplace Create a service instance Lab Exercises Logging into Cloud Foundry, page 2 Creating a Service Instance, page 5 Cloud Foundry Commands Command Description cf login Login to cloud foundry cf marketplace Display all services in the catalog cf create-service Create a new service instance cf apps Display all applications in your space cf push Deploy an application cf services Display all service instances in your space GE Digital Page 1 Predix Developer Boot Camp Exercise 1: Logging into Cloud Foundry Overview In this exercise you will practice logging in to Cloud Foundry. Steps 1. Log into Cloud Foundry. Double-click the Terminal window icon on your desktop to open a Terminal window Enter this command to log into Cloud Foundry: cf login -a https://api.system.aws-usw02-pr.ice.predix.io Note: This command logs you into GE's API endpoint for Cloud Foundry. Page 2 Predix Training Programs Lab 1: Getting Started with Cloud Foundry 2. Enter your Cloud Foundry credentials. You are prompted to enter your email Type in your student account (your instructor will provide this) You are prompted to enter your password (your instructor will provide this) Press Enter Tip: Your password will not appear on the screen as you are typing. 3. Select a space. You are prompted to select a space Enter the number of the targeted space that your instructor provides GE Digital Page 3 Predix Developer Boot Camp The terminal displays the API endpoint, user, and organization and space which you are logged into. Tip ~To change your space: In the terminal, run this command: cf target -sYou are now logged in. Page 4 Predix Training Programs Lab 1: Getting Started with Cloud Foundry Exercise 2: Creating a Service Instance Overview In this exercise, you will use Cloud Foundry commands to display all services in the marketplace and create an instance of the postgres service in your Cloud Foundry space. Steps 1. Display marketplace services. In the Terminal, run this command: cf marketplace All available services appear. You will be creating an instance of the postgres service. GE Digital Page 5 Predix Developer Boot Camp 2. Create a new postgres service instance in your space. Enter the command to create your own service instance with the following syntax: cf create-service Example: 3. Display all services instances in your space. In the Terminal, run the cf services command The service instances in your space are listed. Page 6 Predix Training Programs Lab 2: Deploying and Monitoring Applications Lab 2: Deploying and Monitoring Applications Learning Objectives By the end of the lab, you will be able to use the Cloud Foundry CLI (Command Line Interface) tool to: Add a service Monitor a service Lab Exercises Deploying an Application, page 8 Using a Manifest File to Deploy an Application, page 11 Managing your Environment, page 14 Monitoring your Application, page 15 Directions Complete the exercises that follow. GE Digital Page 7 Predix Developer Boot Camp Exercise 1: Deploying an Application Overview In this exercise, you will deploy an application to Cloud Foundry from the command line interface (CLI). Steps 1. Change to the spring-music directory in the Terminal window. To determine your current directory, enter pwd and press Enter If you are not in the home directory (/predix), run the command: cd and then pwd again to confirm you are in the root directory Change to the spring-music directory by entering the command below: Run the command cf push to publish the application instance of the web application The command fails because you have not provided the parameters it needs. Page 8 Predix Training Programs Lab 2: Deploying and Monitoring Applications . Run the command cf push -h and read through the information presented Tip: -h is for help. Any command used with -h tells the CLI to return help information for the command. You will see the command definition, its syntax, and its options (parameters). Run the cf push command with the following syntax to correctly publish your application: cf push -p Note: You should be in the spring-music directory, which contains the pre-built sub-directory with the Web application ARchive (.war), or wrapper file with all of the application files required for deployment. Your application should successfully publish to Cloud Foundry. GE Digital Page 9 Predix Developer Boot Camp 1. Test your application in a web browser Enter the command cf a to find the URL of your application Copy your application URL (located in the URL column of the output) Open the Firefox Web browser, and paste your application URL The Spring Music application displays in your browser. . Page 10 Predix Training Programs Lab 2: Deploying and Monitoring Applications Exercise 2: Using a Manifest File to Deploy an Application Overview In this exercise you will edit a manifest file and use it to deploy your application instance. The manifest file includes a list of parameters that indicate how the solution should be deployed. Some of the parameters are required, and some are optional. You can also provide these parameters in the command line, but a manifest file is usually used to reduce the complexity of the command, and to save the information for later reuse. Steps 1. Add deployment parameters to the manifest file. Open the gedit text editor from the Applications menu at the top left of the DevBox From the Applications menu, select Accessories>gedit Text Editor Enter Ctrl + O and browse to the manifest.yml file in the following folder predix/PredixApps/training_labs/CloudFoundryLabs/cf-spring-mvc-demo GE Digital Page 11 Predix Developer Boot Camp Edit the manifest file as follows Change the application name to the name of the application (microservice) you created in the previous exercise – To verify the correct name, enter cf a command and locate your application (microservice) name Change the path to pre-built/spring-music.war Change the service listed to (keep the hyphen and space in the file) - This binds the postgresSQL service to your application (microservice) To find your service name, enter cf s (services) in the CLI and look for your postgresSQL service Save the file to the following folder predix/PredixApps/training_labs/CloudFoundryLabs/spring-music Tip: You are saving the manifest file into the same folder from which you deployed the spring-music application earlier so that you can use it to re-deploy the application without entering the parameters into the command line. Page 12 Predix Training Programs Lab 2: Deploying and Monitoring Applications Your file should read as follows (but with your individual service and application names) 2. Deploy the application to Cloud Foundry and confirm it is running. From the spring-music directory, deploy your spring-music service using the cf push command Navigate to the spring-music directory in the CLI (you can check your directory by using the pwd command) Run the cf push command (no parameters listed) Copy the application URL into the web browser Run the cf a command to see the application URL GE Digital Page 13 Predix Developer Boot Camp Exercise 3: Managing your Environment Overview In this exercise you will scale, stop, and delete your application instance. Steps 1. Stop the application in Cloud Foundry. In the Terminal, run cf stop Example: cf stop student55-spring-music The application stops 2. Scale your application up to 3 instances. Run cf scale -i 3 Enter the command to scale your application back down to 1 instance Tip: The command to delete an application is shown below. Do not delete this application as you will use it in later labs. cf delete -r Note: This deletes the application and any orphaned routes from Cloud Foundry. Page 14 Predix Training Programs Lab 2: Deploying and Monitoring Applications Exercise 4: Monitoring your Application Overview In this exercise you will create and bind a logging service instance to the spring-music application. You will also create an instance of the Kibana logging service (web application) and bind that to the logging service instance. Together, these three will provide a web-interface in which you can view spring-music application logs. The relationship is shown below. GE Digital Page 15 Predix Developer Boot Camp Steps 1. Create a Logstash service instance and bind it to your spring-music application. Run the following commands in the Terminal cf create-service logstash-5 free your_name-logstash Replace your_name with your first name. This creates a Logstash service instance. cf bind-service your_name-spring-music your_name-logstash Use your spring-music application name and the name of the Logstash service instance you just created . Page 16 Predix Training Programs Lab 2: Deploying and Monitoring Applications 2. Restage your application and clone the Kibana logging application. cf restage your_name-spring-music This command re-deploys your application from the Cloud Foundry database. Clone the Kibana application from GitHub git clone https://github.com/cloudfoundry-community/kibana-me-logs.git This copies the Kibana logging application to your space 3. Deploy the Kibana UI to Cloud Foundry. Use this command to change to the kibana-me-logs directory cd kibana-me-logs Run this command to deploy the Kibana UI application (change your_name to your first name) cf push kibana-your_name --no-start --random-route -b https://github.com/heroku/heroku-buildpack-go.git GE Digital Page 17 Predix Developer Boot Camp 4. Bind the Kibana application to your Logstash service instance and start the application. Run this command to bind the Kibana application to your Logstash service instance cf bind-service Run this command to start the Kibana application cf start 5. Test the application. Use the URL of the Kibana application you just deployed and started in your Web browser to test the application Page 18 Predix Training Programs Lab 2: Deploying and Monitoring Applications Your application shows logging information from your spring-music application. GE Digital Page 19 Predix Developer Boot Camp Page 20 Predix Training Programs Predix Developer Boot Camp Lab 3: Lab 3: Building a Microservice Building a Microservice Learning Objectives By the end of the lab, you will be able to: Use the manifest file to deploy an application Build and deploy a Java microservice to the Predix Cloud Provide a UI for the microservice Lab Exercises Adding a Maven Archetype, page 22 Adding an Additional API Endpoint to a Microservice, page 32 Directions As part of this lab, you will be building an Alarm Service microservice using a maven archetype. The service exposes two endpoints; one fetches data from the alarm table and the other fetch data from the hospital table. GE Digital Page 21 Predix Developer Boot Camp Lab 3: Building a Microservice Exercise 1: Adding a Maven Archetype Overview In this exercise you will build a Java microservice (application) and deploy it to the Predix Cloud. In this lab we’re testing an application locally before deploying it. To test locally, we’re starting a local postgreSQL instance. Once the application is deployed to the Predix Cloud, the local database service is no longer needed. Steps 1. Start the PostgreSQL service. In the terminal, run this command: sudo /etc/init.d/postgresql-9.3 start A notice that postgresql has started appears. Note: Every time you restart the DevBox, the local postgres service is shut down. The local postgres service is started because it is required to build the alarmservice project in the Eclipse-STS tool (your next task). This is not the same as the service instance of postgres that you created in Cloud Foundry.. GE Digital Page 22 Predix Developer Boot Camp Lab 3: Building a Microservice 2. Create a new maven project Open Eclipse-STS by double clicking the icon on the desktop From the File menu, select New > Maven Project Accept all defaults on the screen and click Next GE Digital Page 23 Predix Developer Boot Camp Lab 3: Building a Microservice In the Select an Archetype window, enter alarm in the Filter field Select predix-hospital-alarm-service-archetype (the text highlights in blue) Click Next Enter the archetype parameter as shown below: Click Finish GE Digital Page 24 Predix Developer Boot Camp Lab 3: Building a Microservice The new alarm service project appears in the Package Explorer. In Package Explorer, right click on the project root (alarmservice) and select Run As > Maven Install At the bottom of the console in the center, the message, “BUILD SUCCESS” appears. Click the maximize console button to maximize the console window GE Digital Page 25 Predix Developer Boot Camp Lab 3: Building a Microservice Notice that the name of the output JAR file is alarmservice-0.0.1-SNAPSHOT.jar. This is the output of the build that is deployed to Cloud Foundry. GE Digital Page 26 Predix Developer Boot Camp Lab 3: Building a Microservice 3. Update the manifest file. Note: Application manifests provide application deployment parameters to Cloud Foundry (how many instances to create, how much memory to allocate, what services applications should use, and so forth). In Eclipse, double-click the manifest.yml file under the alarmservice project to open it Update the manifest file name: Append your first and last name to the service name (example: alarm-service-FirstNameLastName) path: Make sure the path is: “target/alarmservice-0.0.1-SNAPSHOT.jar” services: Change the services element to use the name of the postgres service instance you created in Lab 1 db_service_name: Change the services element to the name of the postgresql service instance you created in Lab 1 Press + to save the file GE Digital Page 27 Predix Developer Boot Camp Lab 3: Building a Microservice To do this: If you do not remember the name of the service instance you created in Lab 1, follow the steps below to determine the name of your service instance. In the Terminal, run the command cf services Under the name column, find the instance service you created 4. Deploy the microservice to the Predix Cloud. In Eclipse, right click on the project root (alarmservice) Select Properties at the bottom of the menu to open the Properties window Copy the alarmservice location (select the text, right-click, copy) GE Digital Page 28 Predix Developer Boot Camp Lab 3: Building a Microservice In the Terminal, navigate to the alarmservice directory by running this command: cdType cd, then paste the copied path from Eclipse Deploy the microservice by running this command: cf push The Terminal shows the deployment steps of the application. Once it completes, select the URL, right-click and select Copy to copy the URL of your application GE Digital Page 29 Predix Developer Boot Camp Lab 3: Building a Microservice 5. Test your application in a browser. Open the Firefox browser by clicking the Firefox icon at the top of your DevBox Paste the URL you copied from the Terminal into your browser Append “/alarmservice” to the end of your URL and press Enter The content of the alarm table appears GE Digital Page 30 Predix Developer Boot Camp Lab 3: Building a Microservice 6. View the recent microservice logs. In the Terminal, run this command: cf logs --recent Replace with your microservice name Tip: To find your application (microservice) name, follow the instructions below: In the Terminal, type cf a Locate your application name under the name column Each log line contains these four fields: – Time stamp – Log type (origin code) – Channel: either STDOUT or STDERR – Message GE Digital Page 31 Predix Developer Boot Camp Lab 3: Building a Microservice Exercise 2: Adding an Additional API Endpoint to a Microservice Overview In this exercise, you will create another endpoint for the alarmservice microservice. This endpoint will be used to query the hospital table. Steps 1. Create an Entity. In Eclipse, under the “/src/main/java” directory, right click on the package com.ge.predix.solsvc.training.alarmservice.entity Select New-> Class GE Digital Page 32 Predix Developer Boot Camp Lab 3: Building a Microservice In the Name field type HospitalEntity Click Finish The entity is created In gedit, open the file /predix/predixApps/training_labs/fundamentals/Lab2/HospitalEntity.txt Copy all content of the file In Eclipse, replace everything in your HospitalEntity.java class GE Digital Page 33 Predix Developer Boot Camp Lab 3: Building a Microservice Press + + to Organize Imports Press + to save the file 2. Create an interface. In Eclipse, under the “/src/main/java” directory on the package com.ge.predix.solsvc.training.alarmservice.repository Right-click and select New -> Interface GE Digital Page 34 Predix Developer Boot Camp Lab 3: Building a Microservice In the Name field, enter IHospitalEntityRepository, then click Finish In gedit, open the file /predix/predixApps/training_labs/fundamentals/Lab_2/IHospitalEntityRepository.txt Copy all content of the file In Eclipse, replace everything in your IHospitalEntityRepository.java class Press+ + to Organize Imports Press + to save the file GE Digital Page 35 Predix Developer Boot Camp Lab 3: Building a Microservice 3. Add mapping to create the service. In Eclipse, under the package com.ge.predix.solsvc.training.alarmservice, double click HospitalAlarmService.java to edit the file In gedit, open the file /predix/predixApps/training_labs/fundamentals/Lab_2/HospitalAlarmService.txt Copy all content of the file In Eclipse, replace everything in your HospitalAlarmService.java class Press+ to save the file Press+ + to Organize Imports Select java.util.iterator and press Finish, then press + to save the file GE Digital Page 36 Predix Developer Boot Camp Lab 3: Building a Microservice 4. Populate the Alarm Service and Hospital data. In Eclipse, under the package com.ge.predix.solsvc.training.alarmservice.jpa.init, double click InitAlarmServiceData.java to edit the file Uncomment the use of hospitalRepo by removing (/*) and (*/) Uncomment the use of HospitalEntity by removing (/*) and (*/) Press+ + to Organize Imports Press + to save the file 5. Compile and deploy the microservice. In the Terminal, from the alarmservice directory, run this command: mvn clean install The message “BUILD SUCCESS” indicates the microservice was built successfully GE Digital Page 37 Predix Developer Boot Camp Lab 3: Building a Microservice From the same directory in the Terminal, run this command: cf push The message “App started” verifies that the application was successfully deployed. 6. Test your Alarm Service application (microservice). In Firefox, replace “alarmservice” at the end of the URL with “hospital” and refresh the browser Tip - If you do not remember the URL of your alarmservice follow the steps below: In the terminal run this command: cf a Locate your microservice name under the “name” column and find the URL to the right under the “urls” column Your data appears GE Digital Page 38 Predix Developer Boot Camp Lab 3: Building a Microservice Exercise 3: Updating the Microservice UI Overview In this exercise you will create a UI microservice to display the data fetched by the alarm service. You will use the dashboard seed service pack and modify it to create the UI microservice. Steps 1. Import a table design into the project. In gedit, open the _settings.defaults.scss file from the /PredixApps/training_labs/fundamentals/predix-seed-1.1.3/public/bo wer_components/px-defaults-design/ folder Add the following code to the bottom of the file: $inuit-enable-table--fixed:true; @import “px-tables-design/_base.tables.scss”; Press+ to save the file GE Digital Page 39 Predix Developer Boot Camp Lab 3: Building a Microservice 2. Edit an existing card to display alarm data. Open the temperature-template.txt file from the /predix/PredixApps/training_labs/fundamentals/Lab_4/ folder Copy all contents of the file In gedit, open the temperature-card.html file in the /PredixApps/training_labs/fundamentals/predix-seed-1.1.3/public/bo wer_components/px-sample-cards/ folder In your temperature-card.html file, replace the tags and everything within the tags with the content you just copied Open the temperature-script.txt file under in the /predix/PredixApps/training_labs/fundamentals/Lab_4 folder Copy all contents of the file GE Digital Page 40 Predix Developer Boot Camp Lab 3: Building a Microservice In your temperature-card.html file, replace the tag and everything within the tag with the content you just copied Press+ to save the file Note: The highlighted “hospitalurl” will be used later to get data into the card and display it. GE Digital Page 41 Predix Developer Boot Camp Lab 3: Building a Microservice 3. Edit an existing card to display hospital data. Open the fetch-data-card-template.txt file from /predix/PredixApps/training_labs/fundamentals/Lab_4 and copy all the contents In gedit, open the fetch-data-card.html file from the /PredixApps/training_labs/fundamentals/predix-seed-1.1.3/public/bo wer_components/px-sample-cards folder In your fetch-data-card.html file, replace the tags and everything within the tags with the content you just copied GE Digital Page 42 Predix Developer Boot Camp Lab 3: Building a Microservice Open the fetch-data-card-script.txt file in the /predix/PredixApps/training_labs/fundamentals/Lab_4 folder Copy all contents of the file In your fetch-data-card.html file, replace the tag and everything within the tag with the content you just copied Press+ to save the file GE Digital Page 43 Predix Developer Boot Camp Lab 3: Building a Microservice 4. Connect the UI to the microservice. Open the scope.txt file from the /predix/PredixApps/training_labs/fundamentals/Lab4 folder Copy all contents of the file In gedit, open the data-control.js file from the /PredixApps/training_labs/fundamentals/predix-seed-1.1.3/public/sc ripts/controllers folder Replace the entire content of the file with the text you just copied Replace the alarm service URL with the URL of your alarm service and save the file Tip: Be sure to leave “http://” at the beginning and the /alarmservice and /hospital at the end when you paste in your replacements. Tip: To determine the URL of your alarm service, run the cf a command in the terminal. Locate your microservice name and find the URL to the right. GE Digital Page 44 Predix Developer Boot Camp Lab 3: Building a Microservice 5. Test your microservice locally. To start your local server, run the grunt serve command from the predix-seed-1.1.3 folder: Your browser opens the Predix seed application. On the left navigation pane select Cards, then select Data Control Verify that the Hospital and Alarm data appear In the terminal, press+ to stop running your local server Note: The grunt commands allows you to test your microservice locally before deploying it to Cloud Foundry. GE Digital Page 45 Predix Developer Boot Camp Lab 3: Building a Microservice 6. Deploy the microservice to Cloud Foundry. Create a package for deployment In your Terminal, run this command: grunt dist This packages the file. Update the manifest file In gedit, open the file PredixApps/training_labs/fundamentals/predix-seed-1.1.3/manifest.yml Append your name to the microservice name Press + to save the file Deploy the microservice to Cloud Foundry In your Terminal run the cf push command and verify that the service has started GE Digital Page 46 Predix Developer Boot Camp Lab 3: Building a Microservice 7. Test your application (microservice). In Firefox, input your Predix-seed microservice URL into the address bar Tip: If you do not remember your microservice URL, follow the steps below: In your terminal run this command: cf a Locate your microservice name under the “name” column and find the URL to the right under the “urls” column On the left navigation pane select Cards, then select Data Control The Hospital and Alarm data appears. You have successfully modified the two cards to display the hospital and alarm data. GE Digital Page 47 Lab 4: Implementing Security in Predix Lab 4: Implementing Security in Predix Learning Objectives By the end of the lab, you will be able to: Create a UAA Service Instance and bind it to an application Add a new OAuth2 client Create a user Create an ACS instance and bind it to an application Update an OAuth2 client to work with ACS Manage ACS User Access Lab Exercises Create a UAA Service Instance, page 49 Fetch a UAA Token, page 52 Adding a Client and Users to UAA, page 56 Create an ACS Instance, page 64 Bind your Application to the ACS instance, page 66 Update an OAuth2 Client to Work with ACS, page 68 Manage ACS User Access, page 72 GE Digital Page 48 Predix Developer Boot Camp Exercise 1: Create a UAA Service Instance Overview In this exercise you will create an UAA service instance and bind your Spring-Music application to that instance. UAA is the Cloud Foundry service that manages users and OAuth2 clients. It is primarily an OAuth2 provider and issues Java web tokens for client applications to use when the applications act on behalf of users. The UAA instance serves as the trusted issuer of tokens and all access to services is provided by authenticating through this trusted issuer. Steps 1. Verify the UAA service is available in the marketplace. In the Terminal run the command: cf marketplace The predix-uaa-training* service is listed along with its Plan name and description *For training only. In production, you will use the predix-uaa service Page 49 Predix Training Programs Lab 4: Implementing Security in Predix 2. Create a UAA service instance. When you create a UAA service instance, you create the administrative user (client) with its password. The name of this client is “admin”. In the Terminal, create a UAA service instance with the following syntax: cf create-service predix-uaa-training-c '{“adminClientSecret”:” ”}' Replace with the plan name Note: Use the “Free” plan type to ensure all labs function properly. Replace with an instance name of your choice Replace with a password of your choice Verify a status of OK is returned Example: Write down the admin password as you will use it in later labs: _________________ WARNING: There is no way to determine this password later on; do not rely on your memory! 3. Bind your previously-created Spring-Music application to your UAA service instance. In the Terminal run the command: cf bind-service Replace with your Spring-Music application name Replace with name of your instance GE Digital Page 50 Predix Developer Boot Camp A return status of OK indicates the application was successfully bound Page 51 Predix Training Programs Lab 4: Implementing Security in Predix Exercise 2: Fetch a UAA Token Overview In this exercise you will use the UAA Command Line Interface (UAAC) to fetch a token from the UAA service instance created in the previous lab. The UAAC has been installed on your DevBox. Steps 1. Find your sample application name in the space. In the Terminal run the command: cf a Locate your application in the list and verify it has started 2. Retrieve your UAA instance details from the VCAP_SERVICES environment variable. When you bind your app to the UAA instance, the connection details for your UAA instance are populated in VCAP_SVCS environment variables. In the Terminal, run the command: cf env In the VCAP_SERVICES variable, locate the entry for your UAA service instance Copy the UAA environment variables to a new file in your text editor for later use Note: Look for the name of your service instance (example: cf-uaa) GE Digital Page 52 Predix Developer Boot Camp Under the credentials section, copy the uri value for your service instance (copy the string between the quotes) Page 53 Predix Training Programs Lab 4: Implementing Security in Predix 3. Specify your UAA instance as the intended target. Note: You must first point the uaac CLI tool to your UAA service instance in order to view the UAA instance details. In the Terminal run the command: uaac target Replace with the uri of your UAA instance 4. Fetch a UAA token from your UAA instance. In the Terminal run the command to log in using the administrative client: uaac token client get admin -s Note: The admin client is the default client id that has all permissions Replace with the password you created when creating the service instance A successful fetch notice indicates you have retrieved the token You are now logged in as the administrative client GE Digital Page 54 Predix Developer Boot Camp 5. Decrypt the token to view its contents. In the Terminal run the command: uaac token decode The token contains basic information including scope - a list of authorities for the admin client client_id - unique name to the system for the client id Authorization grant type - mode of authorization Page 55 Predix Training Programs Lab 4: Implementing Security in Predix Exercise 3: Adding a Client and Users to UAA Overview In this exercise you will create an OAuth2 client you use to create users for in your UAA instance. When you create a UAA service instance, a default administrator account (admin client) is automatically generated that contains all permissions. As a best practice, you create an Oauth2 client and define the scopes instead of using the admin client to create users. For service-to-service security, the generally-recommended grant type is “client_credentials”. for web applications, the recommended grant type is “authorization_code” Steps 1. Create an OAuth2 client with a subset of admin permissions. In the Terminal, run the command: uaac client add -h This displays all parameters available to create a new OAuth client To create the OAuth 2 client, the command line syntax is: uaac client add -s --authorized_grant_types “ ” --autoapprove openid --authorities “ ” Replace
with your client name and write it here _______________ Replace with your chosen password and write it here_________ Replace with authorization_code client_credentials refresh_token Replace with clients.read clients.write scim.read scim.write GE Digital Page 56 Predix Developer Boot Camp Example: Page 57 Predix Training Programs Lab 4: Implementing Security in Predix 2. Fetch a token for the new OAuth2 client. In the Terminal, run the command: uaac token client get
-s Replace with the name of your new oauth2 client Replace with the password you created when creating the uaa client Verify the token was fetched successfully - you are now logged in as the new client Alternatively, you can exclude the -s portion of the command, and you will be prompted to enter the client secret. This is more secure since the password is not displayed as you login as the new client. GE Digital Page 58 Predix Developer Boot Camp 3. Add a user to your UAA service instance. Analysis: For applications accessing your UAA instance, you can create additional users with required scopes. You must be logged in as a client with the necessary authorities. In the Terminal, run the command: uaac user add -h This displays all parameters available for creating a new user In the Terminal run the command: uaac user add --emails -p Replace with a value of your choice, preferably the email Replace with the email of the user (e.g. user1@test.com) Replace with a value of your choice Write down the user name: _____________________________________ Write down the email: __________________________________________ Write down the user password: __________________________________ You will use these later on in the lab. Page 59 Predix Training Programs Lab 4: Implementing Security in Predix 4. Create the groups in your UAA instance. Give your user read and write privileges (group names are scim.read and scim.write - the user token (permission) must have the same name as the group). uaac group add scim.read uaac group add scim.write Sample code: 5. Add the new user to the required groups. uaac member add scim.read uaac member add scim.write GE Digital Page 60 Predix Developer Boot Camp 6. View user details.uaa To view all users, run the command: uaac users The user now has access to the UAA zone Page 61 Predix Training Programs Lab 4: Implementing Security in Predix 7. View the UAA login page. To view the page your user should see when they try to log into an application, paste the uri of your UAA instance into a browser and append /login at the end At the Predix login screen, enter the user name (not email) and user password Click Sign in The login is successful, but an error message is displayed GE Digital Page 62 Predix Developer Boot Camp Note: When creating the new client, we did not specify a redirect attribute. You can add the redirect by updating the client. If the redirect_uri had been set you would have been directed to your application. Page 63 Predix Training Programs Lab 4: Implementing Security in Predix Exercise 4: Create an ACS Instance Overview In this exercise you will create an ACS instance, and bind your application to the instance. Steps 1. Verify that the UAA service is available in the marketplace. In the Terminal run the command: cf marketplace The predix-acs-training service is listed along with its Plan name and description GE Digital Page 64 Predix Developer Boot Camp 2. Create an ACS service instance. Note: You will use the training version of ACS for this exercise rather than the production version. In the Terminal run the command to create a service instance with the following syntax: cf create-service predix-acs-training -c '{“trustedIssuerIds”:” ”}' Replace with the plan name (e.g. Tiered, Basic, Free) Replace with an instance name of your choice Replace is the issuerID (not the uri) of your UAA instance that you saved when you created your UAA instance. Verify a status of OK is returned Example: Page 65 Predix Training Programs Lab 4: Implementing Security in Predix Exercise 5: Bind your Application to the ACS instance Overview You must bind your application to your ACS instance to provision its connection details in the VCAP_SERVICES environment variable. Steps 1. Bind your application to the new ACS instance. In the Terminal execute the command: cf bind-service Replace with your application name Replace with your ACS instance name Example: GE Digital Page 66 Predix Developer Boot Camp Verify the binding: cf env Notice the label is predix-acs-training and the name is cf-acs Copy the ACS information into your text editor file. You need the OAuth scope to configure the OAuth client to work with ACS. Page 67 Predix Training Programs Lab 4: Implementing Security in Predix Exercise 6: Update an OAuth2 Client to Work with ACS Overview To enable applications to manage policies and attributes using ACS, you need to update your OAuth2 client with the required OAuth2 scopes and authorities. In this exercise, you will establish your OAuth2 client to handle Policy Management Services. This will handle tokens sent by the application or client. Steps 1. Update your Client to work with ACS Login as admin to make these changes. Run the command: uaac token client get admin Specify the admin password ( ) when prompted . GE Digital Page 68 Predix Developer Boot Camp Run the command: uaac clients Note the client authorities in both the admin client and the client you will use for your application (cf-client in this case). Page 69 Predix Training Programs Lab 4: Implementing Security in Predix Build the uaac client update --authorities command so that the OAuth client has the appropriate authorities to work with your ACS service instance Open a new file in your gedit text editor and enter the update command Enter a space and double quote after the --authorities flag List all the authorities (single space in between), including those that the client already has – Original list, from your client environment variables (see prior page graphic): clients.read clients.write scim.write scim.read – Enter a space, then enter the zones. .admin variable listed under the admin authorities (see prior page graphic) – Enter a space, then enter the required ACS scopes: acs.policies.read acs.policies.write acs.attributes.read acs.attributes.write (from the application environment variable for ACS) End your command with a double quote Example: When prompted, enter the client name you created GE Digital Page 70 Predix Developer Boot Camp Sample results for updating the OAuth2 client: Page 71 Predix Training Programs Lab 4: Implementing Security in Predix Exercise 7: Manage ACS User Access Overview Your client will manage the resources for Attribute Management Services, and the account and permissions will need to be set up. You created a user in a previous lab. When your user logs in and creates a report, the user will need read permissions. GE Digital Page 72 Predix Developer Boot Camp Steps 1. Create the groups required for ACS in UAA. You can use Admin to create groups, although as a best practice, you should use your application client to manage policies and attributes in your application. You updated your application client in Exercise 3 to enable that client to manage ACS attributes and policies. Ensure your UAA instance is the intended target uaac target Logon as the administrative client uaac token client get Specify the when prompted Create the groups required for ACS in UAA: uaac group add acs.policies.read uaac group add acs.policies.write uaac group add acs.attributes.read uaac group add acs.attributes.write uaac group add Where is the ACS oauth‐scope environment variable Page 73 Predix Training Programs Lab 4: Implementing Security in Predix 2. To use the Policy Management service the user/client must authenticate using a JSON Web Token (JWT) bearer token that includes the acs.policies.read scope for reading the policies or the acs.policies.write scope for writing the policies. To use the Attribute Management service, the user/client must authenticate using a JWT that includes the acs.attributes.read and the acs.attributes.write scopes. User the uaac users command to find the user created previously Assign membership to the required scope: uaac uaac uaac uaac uaac member member member member member add add add add add acs.policies.read acs.policies.write acs.attributes.read acs.attributes.write You will see a message indicating you have succeeded assigning membership to your user. The user is now able to authenticate through ACS Policy Management, Attribute Management, and Policy Evaluation services. GE Digital Page 74 Predix Developer Boot Camp Page 75 Predix Training Programs Lab 5: UI Basics Lab 5: UI Basics Learning Objectives By the end of the lab, students will be able to: Add a link and route for the Patients page to the Predix Starter Pack Show data in a table Customize the px-theme component to style the application Customize a reusable Predix web component Use the customized component in your application Fetch data from a Polymer web component Lab Exercises Adding a Route using Angular JS, page 77 Creating a Controller, page 82 Changing the View and Model, page 84 Styling Your Application, page 87 Creating a View to Display a Web Component, page 93 Creating a Web Component, page 96 Connecting a Microservice, page 102 Directions Complete the exercises that follow. Note: The code for these exercises is found in the UILab.txt file. Your instructor will provide you with the path to this file. GE Digital Page 76 Predix Developer Boot Camp Exercise 1: Adding a Route using Angular JS Overview In this exercise you will start up the predix seed web application and add a new page to the application, using the Predix Angular UI-router. (This is not the built-in router Angular JS ships with.) You will add a new Angular controller and use it to add data to the page. Steps Note: The Predix seed application is already installed, along with its required npm and bower installations. Normally, you would run npm install and bower installs after saving the seed application files to your directory. 1. Test the application locally. In the Terminal, use the following command to navigate to the predix seed app: cd ~/PredixApps/training_labs/fundamentals/predix-seed-1.1.3 Run the following command to start the local web server grunt serve The command line interface (CLI) responds with several lines, ending as follows. Page 77 Predix Training Programs Lab 5: UI Basics The web browser opens and loads the predix starter web application Note: Press + when you need to do something else in your Terminal. This stops the watch task of the grunt serve command. Leave the grunt watch running in your Terminal. To run additional commands in the Terminal, open a new window using the File menu (File>Open Tab). GE Digital Page 78 Predix Developer Boot Camp 2. Add a new navigation link (route). On the left side of the web page, there is an existing navigation component. You will add a new link called Patients The code provided adds an Angular UI route which is used to associate a view and a controller with a URL. The routes.js file contains all of the routes for the application and you will add a new state in this file. Note: The paths noted in the lab instructions assume you are starting in the predix-seed-1.1.3 directory unless otherwise directed. As noted previously, to copy and paste code into your application files, open the UILab.txt file in the gedit text editor and refer to it for the duration of the lab. This file is in the predix/PredixApps/training_labs/fundamentals folder. Page 79 Predix Training Programs Lab 5: UI Basics In your text editor, navigate to the public/scripts directory (under the predix-seed-1.1.3 directory) Open the routes.js file Add a new state to the file – Remove the semicolon after the components statement – Paste in the code provided at the end of the $StateProvider section just after /components.html Ensure that your code reads exactly as below: Save the file ( ) 3. Create a new link (tab) in the navigation and add some data for display in the view. Create a new link In your text editor, navigate to the public/scripts directory Open the app.js file Add a comma after label: ’Data Control’} Add the code provided to the tabs array This code defines router paths and is where the name of the route is matched to the controller and view template. Your code should read as follows: GE Digital Page 80 Predix Developer Boot Camp 4. Store some dummy data for display in the view. In the same file, store some dummy data for display in the view Locate this line in the file: predixApp.controller('MainCtrl', ['$scope', '$rootScope',function,... After this line, paste the code provided into the root scope Your code should read as follows: Save the file Page 81 Predix Training Programs Lab 5: UI Basics Exercise 2: Creating a Controller Overview In this exercise, you add the Patients controller to the application. Steps 1. Create the new patients controller in the patients.js file. In your text editor, navigate to the public/scripts/controllers directory in the seed application Create a file called patients.js and paste the code provided into the file Your code should read as follows: Save the file This code defines the Patients controller (PatientsCtrl), the add.Patient function, and the form (model) GE Digital Page 82 Predix Developer Boot Camp 2. Add a reference to the new controller. In your text editor, navigate to the /public/scripts/controllers directory Open the file main.js file Paste the code provided into the file, replacing all code This reference ensures that the new controller is loaded into the browser. Save the file 3. Create a new view to display a table of patient data. Create a new directory called patient in the public/views folder Create a new file in the patient folder called index.html In your text editor, navigate to the public/views/patient directory Open the index.html file Paste the code provided into the file Save the file This view uses the Angular ng-repeat directive to iterate over the list of patients in scope. Refresh the browser and the application appears with the new navigation link and the patient data Page 83 Predix Training Programs Lab 5: UI Basics Exercise 3: Changing the View and Model Overview In this exercise, you will add a form (with two name fields) that allows the user to dynamically change the view and the model (data) on the web page. You will add First Name and Last Name input fields and an Add Patient button to allow users to add patient data to the table. Finally, you will add a search field to provide filtering. Steps 1. Add Name entry fields and an Add Patient button. In your text editor, navigate to the views/patient directory Open the index.html file Enter the code provided after the tag Your code should read as follows: Save the file Refresh your browser GE Digital Page 84 Predix Developer Boot Camp Your web page should look similar to the one below: Add some patient First and Last Names to test your page The Add Patient button should submit the names to your list. 2. Add a search field to filter the patient data on the page. In your text editor, navigate to the public/views/patient directory Open the index.html file Add the code provided after the
tag 3. Iterate over the patient table. Find the following line in the same file:Replace the line with the code provided Page 85 Predix Training Programs Lab 5: UI Basics Save the file Refresh the browser Navigate to the Patients page and test the search/filter functionality The application allows you to add multiple patient names and filter on them. GE Digital Page 86 Predix Developer Boot Camp Exercise 4: Styling Your Application Overview In the last lab, you created a Patient Input Form without any styling. In this lab, you’ll use Predix styles to give the form a nice look and feel. Normally, you use the GitHub repository to copy Predix projects (web parts, components, elements) to your laptop. We have already staged the px-theme, px-library-design, px-forms-design, and the generator-px-comp projects on your DevBox. All of the projects’ dependencies have also been installed using npm install and bower install. To see the actual steps for this, see the Installing Px Theme Components from GitHub section in the Appendix at the end of this guide. Steps. 1. Generate the CSS files and add the px-forms-design component. From the predix/PredixApps/training_labs/fundamentals/px-theme directory in the Terminal, run the grunt command The Sass pre-processor generates the CSS files, including the px-forms-design component. Tip: Grunt is a command line tool that runs tasks for JavaScript. Here it assures that the Sass files generate the appropriate CSS. In the next step, the grunt watch command ensures that CSS files are updated as changes are made to .scss files. This allows you to immediately see your code changes in the web application. Open a new Terminal window by selecting Open Tab from the File menu Run the grunt watch command from the/px-theme/sass directory In your text editor, navigate to the px-theme/sass directory Open the px-page-theme.scss file Page 87 Predix Training Programs Lab 5: UI Basics Insert the code provided just above the //App line so your code appears as follows: Run the following commands in the Terminal: From the /predix/PredixApps/training_labs/fundamentals/px-theme directory, run the bower link command From the predix-seed-1.1.3 directory, run bower link px-theme These commands link your px-theme project to the predix-seed-1.1.3 project directly. Reload the “Patients” page in your browser Tip: You may need to run the grunt serve command in the predix-seed-1.1.3 directory again. GE Digital Page 88 Predix Developer Boot Camp Your Patients page appears as below: Page 89 Predix Training Programs Lab 5: UI Basics 2. Add classes to the HTML. In your text editor, navigate to the predix-seed-1.1.3/public/views/patient directory Open the index.html file, and replace all of the HTML from and including the