169 | {item.note}
170 |
173 |
174 | )
175 | const searchResults = [].concat(this.state.searchResults)
176 | .map((item,i)=>
177 |
178 | {item.note}
179 |
180 | )
181 | return (
182 |
183 |
184 |
186 |
187 |
211 |
221 | );
222 | }
223 | }
224 | export default withAuthenticator(App, { includeGreetings: true });
225 | ```
226 | So, what did we just change? well, their isn't that many lines of code that we've added:
227 | * Lines 62-69 Contain a new const for "searchNote". This is just another GraphQL query like the others.
228 | * Lines 77, 80 and 81 add some additional variables for our scope handling.
229 | * Line 86 add the handle for our search binding.
230 | * Lines 118-127 is the new async handle for our search
231 | * Lines 133, 139, 146-151, 154, 155 and 184-189 Handle the display of the notes
232 | * Lines 61, 165 and 166 add the search button to our form.
233 |
234 | 4. And we're ready to test. Like before, we can test our new code by using the Amplify CLI.
235 | ```bash
236 | amplify serve
237 | ```
238 |
239 | You can now log in create some sample notes and then try to search for it.
240 | 
241 | 
242 |
243 | ## Deploy search function
244 | By following the steps outlined in the [Application Development](ApplicaitonDevelopment.md) part of the workshop you should be able to commit your code back to your "dev" branch.
245 |
246 | Once you've done that, create a pull request to the "test" branch as outlined in [Trigger Deployment](TriggerDeployment.md) and once you approve it, the new Elasticsearch functionality will be deployed into "test".
247 |
248 | Finally, you can perform the same tasks to move it into Production.
249 |
250 | ## What to from here?
251 | And that's it, you now have a fully working Multi-Tenant Notes Application with the beginnings of an automated deployment pipeline. But where can you go from here? well, their are a number of things that could be done to expand the functionality of the solution and some are listed below for reference:
252 |
253 | * Customize the login screen and functions - https://aws-amplify.github.io/docs/js/authentication#customize-your-own-components
254 | * Add Federation to allow social logins - https://aws-amplify.github.io/docs/js/authentication#identity-pool-federation
255 | * Enable MFA - https://aws-amplify.github.io/docs/js/authentication#enabling-mfa
256 | * Leverage Amazon Pinpoint for application analytics - https://aws-amplify.github.io/docs/js/analytics#analytics
257 | * Add a service worker to support offline experiences - https://aws-amplify.github.io/docs/js/service-workers#service-workers
258 |
259 |
--------------------------------------------------------------------------------
/ApplicationDevelopment.md:
--------------------------------------------------------------------------------
1 | # Application Development #
2 |
3 | ## Overview
4 | By now, we have:
5 | * Our Cloud9 IDE with the required packages installed and ready for use.
6 | * Our bootstrapped application committed to our Git repository with our "master" and "test" branches configured
7 | * Two Amplify Deploy pipelines configured and had the complete their initial deployments.
8 |
9 | In this part of the workshop, we will start building out our applications functionality by adding in some basic authentication and a GraphQL endpoint that will be responsible for providing access to our users notes.
10 |
11 | ## Configuring Dev Branch
12 | The first thing we need to do is setup our new "dev" branch as point to our "dev" Amplify environment.
13 |
14 | 1. Firstly, browse back to your Cloud9 IDE and make sure that your bash session is in the right folder.
15 | 
16 |
17 | 2. here we can see that we are currently in our "test" branch (as indicated by the (test) immediately before the $ symbol). We first need to create ourselves a new branch called "dev" so that we can develop our new functionality before merging it back into our test environment.
18 | ```bash
19 | git checkout -b dev
20 | ```
21 | you should now have (dev) immediately before the $ rather than (test) as shown below/
22 | 
23 |
24 | 3. The next thing we need to do is tell Amplify that we want to be using our "dev" environment that we created earlier. This is pretty simple and is just a single command.
25 | ```bash
26 | amplify env checkout dev
27 | ```
28 | 
29 |
30 | We are now ready to start editing our application.
31 |
32 | ## Adding Authentication
33 | The next thing we are going to do is add some authentication to our application. To do this we will use the "amplify auth" feature that will automatically add in a cognito user pool for us to use. We can then make a few simple changes to our React application to leverage this feature.
34 |
35 | 4. To add Authentication, we firstly need to tell Amplify to add the required components to our applications codebase. To do this, we simply run the "amplify add" command from the bash terminal.
36 | ```bash
37 | amplify add auth
38 | ```
39 | The Amplify CLI will then go through a series of questions to define how our solution is configured. For our example we can simply accept the defaults, however it's important to note that when working on a production application, these setting can not be changed once deployed.... So some thought might need to go into their answers.
40 | 
41 |
42 | 5. Now that we've added authentication to our code base, we need to tell Amplify to deploy the required backend resources so that we can leverage them (in this case Amazon Cognito). As stated in the console, this easiest way to do this is to perform an "amplify push" which will use cloudformation templates to deploy the required resources.
43 | ```bash
44 | amplify push
45 | ```
46 | We immediately get presented with information saying that Amplify is going to need to "Create" the resources required for our "Auth" component and it will do this in our "dev" environment. this is what we want, so we can simply hit enter to proceed. As soon as you hit Enter, the cloudformation deployment will start and take a couple of minutes to complete.
47 |
48 | 
49 |
50 | 6. We have our configuration defined, CloudFormation deployed... Time to leverage it in our React application. to do this is as easy as adding the following lines to our /src/App.js file (Do not do anything yet, the below is for illustration purposes).
51 | ```js
52 | import { withAuthenticator } from 'aws-amplify-react'; // or 'aws-amplify-react-native';
53 | import Amplify from 'aws-amplify';
54 | // Get the aws resources configuration parameters
55 | import awsconfig from './aws-exports'; // if you are using Amplify CLI
56 |
57 | Amplify.configure(awsconfig);
58 |
59 | // ...
60 |
61 | export default withAuthenticator(App);
62 | ```
63 |
64 | to make life easy, open the /src/App.js file and replace it with the below code.
65 | ```js
66 | import React from 'react';
67 | import { withAuthenticator } from 'aws-amplify-react'; // or 'aws-amplify-react-native';
68 | import Amplify from 'aws-amplify';
69 | import logo from './logo.svg';
70 | import './App.css';
71 | // Get the aws resources configuration parameters
72 | import awsconfig from './aws-exports'; // if you are using Amplify CLI
73 |
74 | Amplify.configure(awsconfig);
75 |
76 | function App() {
77 | return (
78 | Notes App
185 |187 |
188 | {this.state.displayAdd ?
189 |
198 | : null }
199 | {this.state.displayUpdate ?
200 |
208 | : null }
209 |
210 | 211 |
212 | {searchResults}
213 | {this.state.displaySearch ?
214 |
217 | : null }
218 | {data}
219 |
220 |
79 |
80 | 
81 |
93 |
94 | );
95 | }
96 |
97 | export default withAuthenticator(App, { includeGreetings: true });
98 | ```
99 | don't forget to save the file once your done.
100 |
101 | 7. Time to test it. The quickest and easiest way to do this is to just run "Amplify serve" which will start a local development instance that you can use.
102 | ```bash
103 | amplify serve
104 | ```
105 | 
106 |
107 | But Argh! how do we get to local host when we are developing on a remote Cloud9 instance? The easiest way is to click on the "Preview" dropdown at the top of the page, and select "Preview Running Application". This will open up a new tab with your site. If you'd like to view it in a full window, click the button on the far right of it's address bar.
108 | .
109 |
110 | Once you've open the preview page you should be presented with a login screen.
111 | 
112 |
113 | Go ahead and click "Create account" and go through the process. The default configuration requires a verification code to be confirmed via email before a user can login so pick an email address you have access to. You can also test out the "Reset Password" flow as that should also be working at this point.
114 |
115 | Once you've verified an account you should be able to login using a newly created username and password and be presented with our application once again. Only this time, their is a Menubar at the top displaying your username and a "SIGN OUT" Button (the menu bar came from the "includeGreeting: true" parameter we passed in the last line of our /src/App.js file).
116 | 
117 |
118 | ## Adding a GraphQL API
119 | So, we have an application that has fully working authentication (ok, it's not the prettiest login screen ... but it works) but doesn't do much other than that. Now would be a good time to actually add some functionality to our application and we'll do that by adding in a GraphQL endpoint which will store our notes in a dynamoDB table. We'll also need to add some basic UI bootstrap to present the notes back to the user.
120 |
121 | 1. To add an API, we do much the same thing we did when we added authentication. We simply run the "amplify add" command from the bash terminal.
122 | ```bash
123 | amplify add api
124 | ```
125 |
126 | The Amplify CLI will then go through a series of questions to define how our solution is configured. For our example, we will only deviate from the defaults for out authorization, where we will select "Amazon Cognito User Pool" rather than "API Key".
127 | 
128 |
129 | Once you get to the "Do you want to edit the schema now?" question, it will prompt you to edit the schema file it has created. Simply click on the link it provides and select "Open". Then replace everything in the file with the below. Don't forget to save the file before returning to the terminal.
130 | ```
131 | type Note @model @auth(rules: [{allow: owner}]){
132 | id: ID!
133 | note: String!
134 | }
135 | ```
136 |
137 | press "Enter" to complete the configuration process.
138 | 
139 |
140 | 2. Now that we've added an API to our code base, we need to tell Amplify to deploy the required backend resources so that we can leverage it. As stated in the console, this easiest way to do this is to perform an "amplify push" which will use cloudformation templates to deploy the required resources.
141 | ```bash
142 | amplify push
143 | ```
144 | We immediately get presented with similar information to what we did last time, however now it shows that we will be creating our API, while making no changes to our Auth resources. Press "Enter" to continue.
145 |
146 | 
147 |
148 | The next question asks us if we want to generate code for our newly created GraphQL API. For our example we will be writing our own so answer "n" to this question. After that, the Amplify CLI will again go and deploy a series of CloudFormation templates responsible for our API. Note that this does take a couple of minutes, but make sure it completes before proceeding to the next step.
149 |
150 | 3. Before we go ahead and add some more code to our /src/App.js file, lets make sure that our new API endpoint is working correctly. To do this, go ahead and open up a new tab and browse to https://console.aws.amazon.com/appsync/home?region=us-east-1 and open up your new API.
151 | 
152 |
153 | 4. Click on "Queries" from the Left hand menu, and then click the "Login with User Pools" button.
154 | 
155 |
156 | We need to provide AppSync with three pieces of information before we can start making queries against our API:
157 | * ClientID this can be found in the /src/aws-exports.js file of our project. It's the "aws_user_pools_web_client_id" value.
158 | * Username is simply the username of the test user we created earlier
159 | * Password and it's password.
160 | Enter the information and click "Login". At this point you should be back at the "Queries" page.
161 | 
162 |
163 | 5. Firstly, lets try and create a new note. To do this, enter the below query into the window (feel free to delete the code that's already their) and click the play button.
164 | ```
165 | mutation createNote {
166 | createNote(input: {
167 | note: "Test Note Number 1"
168 | }) {
169 | id note
170 | }
171 | }
172 | ```
173 |
174 | if everything is working correctly, you should get a response confirming the creation of your new note as shown below.
175 | 
176 |
177 | go ahead and create a few more notes using the below queries. Make sure to run each query separately!
178 | ```
179 | mutation createNote {
180 | createNote(input: {
181 | note: "Test Note Number 2"
182 | }) {
183 | id note
184 | }
185 | }
186 | ```
187 | ```
188 | mutation createNote {
189 | createNote(input: {
190 | note: "Test Note Number 3"
191 | }) {
192 | id note
193 | }
194 | }
195 | ```
196 |
197 | we can also test retrieving notes by running a query request.
198 | ```
199 | query listNotes {
200 | listNotes {
201 | items {
202 | note
203 | }
204 | }
205 | }
206 | ```
207 | this should return a list of all of our notes without the id field.
208 | 
209 |
210 | 6. Now that we know our API is working correctly, It's time to update our application. Back in our Cloud9 IDE,replace the contents of your /src/App.js file with the code below and don't forget to save it:
211 | ```js
212 | import React, {Component} from 'react';
213 | import { withAuthenticator } from 'aws-amplify-react'; // or 'aws-amplify-react-native';
214 | import Amplify, {API,graphqlOperation} from 'aws-amplify';
215 | // Get the aws resources configuration parameters
216 | import awsconfig from './aws-exports'; // if you are using Amplify CLI
217 | import 'bootstrap/dist/css/bootstrap.min.css';
218 |
219 | Amplify.configure(awsconfig);
220 |
221 | const headerStyle = {
222 | 'background-color': '#282c34',
223 | 'min-height': '10vh',
224 | display: 'flex',
225 | 'flex-direction': 'column',
226 | 'align-items': 'center',
227 | 'justify-content': 'center',
228 | 'font-size': 'calc(10px + 2vmin)',
229 | color: 'white'
230 | };
231 |
232 | const createNote = `mutation createNote($note: String!){
233 | createNote(input:{
234 | note: $note
235 | }){
236 | __typename
237 | id
238 | note
239 | }
240 | }`;
241 |
242 | const readNote = `query listNotes{
243 | listNotes{
244 | items{
245 | __typename
246 | id
247 | note
248 | }
249 | }
250 | }`;
251 |
252 | const updateNote = `mutation updateNote($id: ID!,$note: String){
253 | updateNote(input:{
254 | id: $id
255 | note: $note
256 | }){
257 | __typename
258 | id
259 | note
260 | }
261 | }`;
262 |
263 | const deleteNote = `mutation deleteNote($id: ID!){
264 | deleteNote(input:{
265 | id: $id
266 | }){
267 | __typename
268 | id
269 | note
270 | }
271 | }`;
272 |
273 | class App extends Component {
274 | constructor(props){
275 | super(props);
276 | this.state={
277 | id:"",
278 | notes:[],
279 | value:"",
280 | displayAdd:true,
281 | displayUpdate:false
282 | };
283 | this.handleChange = this.handleChange.bind(this);
284 | this.handleSubmit = this.handleSubmit.bind(this);
285 | this.handleUpdate = this.handleUpdate.bind(this);
286 | }
287 |
288 | async componentDidMount(){
289 | const notes = await API.graphql(graphqlOperation(readNote));
290 | this.setState({notes:notes.data.listNotes.items});
291 | }
292 |
293 | handleChange(event) {
294 | this.setState({value:event.target.value});
295 | }
296 | async handleSubmit(event) {
297 | event.preventDefault();
298 | event.stopPropagation();
299 | const note = {"note":this.state.value}
300 | await API.graphql(graphqlOperation(createNote, note));
301 | this.listNotes();
302 | this.setState({value:""});
303 | }
304 | async handleDelete(id) {
305 | const noteId = {"id":id};
306 | await API.graphql(graphqlOperation(deleteNote, noteId));
307 | this.listNotes();
308 | }
309 | async handleUpdate(event) {
310 | event.preventDefault();
311 | event.stopPropagation();
312 | const note = {"id":this.state.id,"note":this.state.value};
313 | await API.graphql(graphqlOperation(updateNote, note));
314 | this.listNotes();
315 | this.setState({displayAdd:true,displayUpdate:false,value:""});
316 | }
317 | selectNote(note){
318 | this.setState({id:note.id,value:note.note,displayAdd:false,displayUpdate:true});
319 | }
320 | async listNotes(){
321 | const notes = await API.graphql(graphqlOperation(readNote));
322 | this.setState({notes:notes.data.listNotes.items});
323 | }
324 |
325 | render() {
326 | const data = [].concat(this.state.notes)
327 | .map((item,i)=>
328 |
82 | Edit src/App.js and save to reload.
83 |
329 | {item.note}
330 |
333 |
334 | )
335 | return (
336 |
337 |
338 |
340 |
341 |
364 |
368 | );
369 | }
370 | }
371 | export default withAuthenticator(App, { includeGreetings: true });
372 | ```
373 | Theirs a lot going on here so lets break down the changes we just made:
374 | * Lines 1-5 we've added a couple of extra parts we need brought in from the Amplify libraries.
375 | * line 6 we've added our bootstrap.css to add some pretty to our application.
376 | * lines 10-19 is just a CSS block to clean up the menu. We've also removed the reference to our App.css.
377 | * lines 21-60 are the GraphQL queries that we are going to need. These are the same as the queries we ran in the previous steps.
378 | * lines 63-112 adds some GraphQL logic and state handling. This is mainly to refresh the page and notes are added/updated or removed.
379 | * lines 115-156 is just HTML used to display the page.
380 |
381 | And that's it, we've just added all of the code we need to interact with our GraphQL API.
382 |
383 | 7. Time to test it. Like earlier, all we need to do is to just run "Amplify serve" which will start a local development instance that you can use.
384 | ```bash
385 | amplify serve
386 | ```
387 | 
388 |
389 | either follow the same process we used before to open the preview window, or refresh it if it's still open. Once you've logged in, you should be presented with a list of the notes we created using AppSync.
390 | 
391 |
392 | 8. To finish off this section, lets make sure that nobody else can access our notes. Click the "SIGN OUT" button at the top of the application and create a second user account using the same process we followed earlier. When you sign in, you should be presented with no notes.
393 | 
394 |
395 | But where did we define this? Well, back in our GraphQL schema, we defined the "allow: owner" parameter as shown below
396 | ```
397 | type Note @model @auth(rules: [{allow: owner}]){
398 | id: ID!
399 | note: String!
400 | }
401 | ```
402 | This automatically ensures that users can only see the notes that they created. What's not clear from our schema file is that AppSync is adding an "owner" field to every record it creates and this is what's it's checking as a part of the authentication against the API. We can confirm this by taking a look at the records, AppSync has written to the DynamoDB table.
403 | 
404 |
405 | ## Committing our Code
406 | The final step is to commit our dev branch back to our repository.
407 |
408 | 1. we can simply go a "git add ." to stage all of the files we've created ready for a commit.
409 | ```bash
410 | git add .
411 | ```
412 |
413 | 2. Next we can commit our code to the branch
414 | ```bash
415 | git commit -m "Added Authentication and API"
416 | ```
417 |
418 | 3. And then a git push, to upload it back to our repository. Note that we'll need to set the up stream endpoint.
419 | ```bash
420 | git push -u origin dev
421 | ```
422 | Our branch has now been uploaded back to our git repository ready for use.
423 |
424 | 
425 |
426 | ## Next Steps
427 | And there we go. We've added some authentication to our application and integrated a GraphQL endpoint to it. We are now ready to move onto the next step [here](/TriggerDeployment.md) where we will merge the code back to our "test" branch and trigger the automated deployment.
428 |
--------------------------------------------------------------------------------
Notes App
339 |341 |
342 | {this.state.displayAdd ?
343 |
351 | : null }
352 | {this.state.displayUpdate ?
353 |
361 | : null }
362 |
363 | 364 |
365 | {data}
366 |
367 |