├── public ├── img │ ├── favicon.ico │ └── screenshot.png └── css │ └── main.css ├── .gitignore ├── views ├── error.pug ├── login.pug ├── layout.pug └── emailSender.pug ├── utils ├── config.js ├── graphHelper.js └── emailHelper.js ├── package.json ├── nodejs-connect-sample.yml ├── LICENSE ├── README.md ├── app.js └── CONTRIBUTING.md /public/img/favicon.ico: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/microsoftgraph/nodejs-connect-sample/HEAD/public/img/favicon.ico -------------------------------------------------------------------------------- /public/img/screenshot.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/microsoftgraph/nodejs-connect-sample/HEAD/public/img/screenshot.png -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | lib-cov 2 | *.seed 3 | *.log 4 | *.csv 5 | *.dat 6 | *.out 7 | *.pid 8 | *.gz 9 | .DS_Store 10 | .vscode 11 | 12 | pids 13 | logs 14 | results 15 | 16 | npm-debug.log 17 | node_modules 18 | -------------------------------------------------------------------------------- /views/error.pug: -------------------------------------------------------------------------------- 1 | 2 | //- Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. 3 | //- See LICENSE in the project root for license information. 4 | 5 | extends layout 6 | 7 | block content 8 | h1 #{message} 9 | h2 #{error.status} 10 | pre. 11 | \n#{error.stack} -------------------------------------------------------------------------------- /views/login.pug: -------------------------------------------------------------------------------- 1 | 2 | //- Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. 3 | //- See LICENSE in the project root for license information. 4 | 5 | extends layout 6 | 7 | block content 8 | .ms-Grid 9 | .ms-Grid-row 10 | .ms-NavBar 11 | ul.ms-NavBar-items 12 | li.navbar-header Microsoft Graph sample 13 | .ms-Grid-col.ms-u-mdPush1.ms-u-md9.ms-u-lgPush1.ms-u-lg6 14 | div 15 | p.ms-font-xl Use the button below to connect to Microsoft Graph. 16 | button#connect_button.ms-Button(onclick="window.location.href='login'") 17 | span.ms-Button-label Connect to Microsoft Graph 18 | -------------------------------------------------------------------------------- /utils/config.js: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. 3 | * See LICENSE in the project root for license information. 4 | */ 5 | 6 | module.exports = { 7 | creds: { 8 | redirectUrl: 'http://localhost:3000/token', 9 | clientID: '', 10 | clientSecret: '', 11 | identityMetadata: 'https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration', 12 | skipUserProfile: true, 13 | responseType: 'code', 14 | validateIssuer: false, 15 | responseMode: 'query', 16 | scope: ['User.Read', 'Mail.Send', 'profile'], 17 | allowHttpForRedirectUrl: true 18 | } 19 | }; -------------------------------------------------------------------------------- /views/layout.pug: -------------------------------------------------------------------------------- 1 | 2 | //- Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. 3 | //- See LICENSE in the project root for license information. 4 | 5 | doctype html 6 | html 7 | head 8 | title Microsoft Graph Node.js Connect Sample 9 | meta(charset='utf-8') 10 | meta(name='viewport', content='width=device-width, initial-scale=1') 11 | link(rel='stylesheet', href='https://appsforoffice.microsoft.com/fabric/1.0/fabric.css') 12 | link(rel='stylesheet', href='https://appsforoffice.microsoft.com/fabric/1.0/fabric.components.css') 13 | link(rel='stylesheet', href='/css/main.css') 14 | 15 | script(src='//ajax.aspnetcdn.com/ajax/jQuery/jquery-2.0.3.min.js') 16 | 17 | body.ms-Grid 18 | block content -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "msgraph-nodejs-connect-sample", 3 | "version": "1.0.0", 4 | "description": "A NodeJS connect sample utilizing the Graph JavaScript SDK", 5 | "main": "app.js", 6 | "scripts": { 7 | "start": "node app.js" 8 | }, 9 | "keywords": [ 10 | "graph", 11 | "microsoft", 12 | "nodejs", 13 | "unified" 14 | ], 15 | "author": "Beth Pan", 16 | "dependencies": { 17 | "@microsoft/microsoft-graph-client": "^1.0.0", 18 | "body-parser": "^1.15.2", 19 | "cookie-parser": "^1.4.3", 20 | "csurf": "^1.9.0", 21 | "express": "^4.13.4", 22 | "express-session": "^1.14.0", 23 | "http": "0.0.0", 24 | "method-override": "^2.3.6", 25 | "morgan": "^1.7.0", 26 | "passport-azure-ad": "^3.0.12", 27 | "pug": "^2.0.3" 28 | } 29 | } 30 | -------------------------------------------------------------------------------- /nodejs-connect-sample.yml: -------------------------------------------------------------------------------- 1 | ### YamlMime:Sample 2 | sample: 3 | - name: Microsoft Graph Connect Sample for Node.js 4 | path: '' 5 | description: This sample shows how to connect a Node.js app to a Microsoft work or school (Azure Active Directory) or personal (Microsoft) account using the Microsoft Graph API and the Graph JavaScript SDK to send an email. In addition, the sample uses the Office Fabric UI for styling and formatting the user experience. 6 | readme: '' 7 | generateZip: FALSE 8 | isLive: TRUE 9 | technologies: 10 | - Microsoft Graph 11 | - Azure AD 12 | - Office UI Fabric 13 | azureDeploy: '' 14 | author: jamescro 15 | platforms: [] 16 | languages: 17 | - node.js 18 | - JavaScript 19 | extensions: 20 | products: 21 | - Office 365 22 | scenarios: [] 23 | -------------------------------------------------------------------------------- /public/css/main.css: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. 3 | * See LICENSE in the project root for license information. 4 | */ 5 | 6 | .navbar-header { 7 | box-sizing: border-box; 8 | display: block; 9 | height: 40px; 10 | line-height: 40px; 11 | font-family: 'Segoe UI Semilight WestEuropean', 'Segoe UI Semilight', 'Segoe WP Semilight', 'Segoe UI', 'Segoe WP', Tahoma, Arial, sans-serif; 12 | font-size: 17px; 13 | padding-left: 20px; 14 | position: relative; 15 | font-weight: bold; 16 | } 17 | 18 | @media (min-width: 480px) { 19 | .navbar-header { 20 | float: left; 21 | margin-right: 20px; 22 | font-size: 20px; 23 | padding: 0; 24 | } 25 | } 26 | 27 | .ms-TextField { 28 | width: 300px; 29 | display: inline-block; 30 | } 31 | 32 | .icon-holder { 33 | display: inline-block; 34 | width: 30px; 35 | } 36 | 37 | .big-icon { 38 | font-size: 30px; 39 | top: 5px; 40 | position: relative; 41 | } -------------------------------------------------------------------------------- /utils/graphHelper.js: -------------------------------------------------------------------------------- 1 | const graph = require('@microsoft/microsoft-graph-client'); 2 | 3 | module.exports = { 4 | getUserEmail: (user, done) => { 5 | var client = graph.Client.init({ 6 | defaultVersion: 'v1.0', 7 | debugLogging: true, 8 | authProvider: function(authDone) { 9 | authDone(null, user.accessToken); 10 | } 11 | }); 12 | 13 | client.api('/me').select(['mail', 'userPrincipalName']).get( 14 | (err, me) => { 15 | if (err) { 16 | return done(err); 17 | } 18 | 19 | return done(null, me.mail ? me.mail : me.userPrincipalName); 20 | } 21 | ); 22 | }, 23 | 24 | sendEmail: (user, message, done) => { 25 | var client = graph.Client.init({ 26 | defaultVersion: 'v1.0', 27 | debugLogging: true, 28 | authProvider: function(authDone) { 29 | authDone(null, user.accessToken); 30 | } 31 | }); 32 | 33 | client.api('/me/sendmail').post(message, 34 | (err) => { 35 | return done(err); 36 | } 37 | ); 38 | } 39 | }; -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2016 Microsoft Corporation 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /views/emailSender.pug: -------------------------------------------------------------------------------- 1 | 2 | //- Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. 3 | //- See LICENSE in the project root for license information. 4 | 5 | extends layout 6 | 7 | block content 8 | .ms-Grid-row 9 | .ms-NavBar 10 | ul.ms-NavBar-items 11 | li.navbar-header Microsoft Graph Connect sample 12 | li#disconnect_link.ms-NavBar-item.ms-NavBar-item--right(onclick="window.location.href='logout'") 13 | i.ms-Icon.ms-Icon--x 14 | | Disconnect 15 | form(action='/emailSender', method='post') 16 | .ms-Grid-col.ms-u-mdPush1.ms-u-md9.ms-u-lgPush1.ms-u-lg6 17 | div 18 | h2.ms-font-xxl.ms-fontWeight-semibold Hi, #{user.displayName}! 19 | p.ms-font-xl 20 | | You're now connected to Microsoft Graph. Click the button below to send a message from your account using the Microsoft Graph. 21 | .ms-TextField 22 | input.ms-TextField-field(name='input_email', value=email) 23 | button#send_mail_button.ms-Button 24 | span.ms-Button-label Send mail 25 | if status == "success" 26 | div 27 | p.ms-font-m.ms-fontColor-green Successfully sent an email! -------------------------------------------------------------------------------- /utils/emailHelper.js: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. 3 | * See LICENSE in the project root for license information. 4 | */ 5 | 6 | 'use strict'; 7 | // The contents of the outbound email message that will be sent to the user 8 | const emailContent = '

Congratulations {{name}},

This is a message from the Microsoft Graph Connect Sample. You are well on your way to incorporating Microsoft Graph endpoints in your apps.

What’s next?

Give us feedback

If you have any trouble running this sample, please log an issue.

For general questions about the Microsoft Graph API, post to Stack Overflow. Make sure that your questions or comments are tagged with [microsoftgraph].

Thanks and happy coding!
Your Microsoft Graph samples development team

See on GitHub Suggest on UserVoice Share on Twitter
'; 9 | 10 | var getEmailContent = (name) => { 11 | return emailContent.replace('{{name}}', name) 12 | }; 13 | 14 | var wrapEmail = (content, recipient) => { 15 | var emailAsPayload = { 16 | Message: { 17 | Subject: 'Welcome to Microsoft Graph development with Node.js and the Connect sample', 18 | Body: { 19 | ContentType: 'HTML', 20 | Content: content 21 | }, 22 | ToRecipients: [{ 23 | EmailAddress: { 24 | Address: recipient 25 | } 26 | }] 27 | }, 28 | SaveToSentItems: true 29 | }; 30 | 31 | return emailAsPayload; 32 | }; 33 | 34 | module.exports = { 35 | generateMailBody: (name, recipient) => { 36 | return wrapEmail(getEmailContent(name), recipient); 37 | } 38 | }; 39 | 40 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # [ARCHIVED] Microsoft Graph Connect Sample for Node.js 2 | 3 | ## IMPORTANT 4 | 5 | **This project is being archived and replaced with the [Build Node.js Express apps with Microsoft Graph](https://github.com/microsoftgraph/msgraph-training-nodeexpressapp). As part of the archival process, we're closing all open issues and pull requests.** 6 | 7 | **You can continue to use this sample "as-is", but it won't be maintained moving forward. We apologize for any inconvenience.** 8 | 9 | This sample shows how to connect a Node.js app to a Microsoft work or school (Azure Active Directory) or personal (Microsoft) account using the Microsoft Graph API and [the Graph JavaScript SDK](https://github.com/microsoftgraph/msgraph-sdk-javascript) to send an email. In addition, the sample uses the Office Fabric UI for styling and formatting the user experience. 10 | 11 | ![Microsoft Graph Connect Sample for Node.js screenshot](./public/img/screenshot.png) 12 | 13 | ## Prerequisites 14 | 15 | To use the Microsoft Graph Connect Sample for Node.js, you need the following: 16 | 17 | - [Node.js](https://nodejs.org/) version 4 or 5. 18 | - Either a [Microsoft account](https://www.outlook.com/) or a [work or school account](http://dev.office.com/devprogram) 19 | 20 | ## Register the application 21 | 22 | 1. Sign into the [App Registration Portal](https://apps.dev.microsoft.com/) using either your personal or work or school account. 23 | 1. Choose **Add an app**. 24 | 1. Enter a name for the app, and choose **Create application**. The registration page displays, listing the properties of your app. 25 | 1. Copy the **Application Id**. This is the unique identifier for your app. 26 | 1. Under **Application Secrets**, choose **Generate New Password**. Copy the password from the **New password generated** dialog. You'll use the application ID and password (secret) to configure the sample app in the next section. 27 | 1. Under **Platforms**, choose **Add Platform**. 28 | 1. Choose **Web**. 29 | 1. Enter `http://localhost:3000/token` as the **Redirect URI**. 30 | 1. Choose **Save**. 31 | 32 | ## Build and run the sample 33 | 34 | 1. Download or clone the Microsoft Graph Connect Sample for Node.js. 35 | 1. Using your favorite IDE, open **./utils/config.js**. 36 | 1. Replace the **clientId** and **clientSecret** placeholder values with the application ID and password that you copied during app registration. 37 | 1. In a command prompt, run the following command in the root directory. This installs the project dependencies. 38 | 39 | ```Shell 40 | npm install 41 | ``` 42 | 43 | 1. Run the following command to start the development server. 44 | 45 | ```Shell 46 | npm start 47 | ``` 48 | 49 | 1. Navigate to `http://localhost:3000/` in your web browser. 50 | 1. Click the **Connect to Microsoft Graph** button. 51 | 1. Sign in with your personal or work or school account and grant the requested permissions. 52 | 1. Optionally edit the recipient's email address, and then choose the **Send mail** button. When the mail is sent, a success message is displayed below the button. 53 | 54 | ## Questions and comments 55 | 56 | We'd love to get your feedback about the Microsoft Graph Connect Sample for Node.js using the Graph JavaScript SDK. You can send your questions and suggestions in the [Issues](https://github.com/microsoftgraph/nodejs-connect-sample/issues) section of this repository. 57 | 58 | Questions about Microsoft Graph development in general should be posted to [Stack Overflow](http://stackoverflow.com/questions/tagged/microsoftgraph). Make sure that your questions or comments are tagged with [microsoftgraph]. 59 | 60 | ## Contributing 61 | 62 | If you'd like to contribute to this sample, see [CONTRIBUTING.MD](/CONTRIBUTING.md). 63 | 64 | This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. 65 | 66 | ## Additional resources 67 | 68 | - [Other Microsoft Graph Connect samples](https://github.com/MicrosoftGraph?utf8=%E2%9C%93&query=-Connect) 69 | - [Microsoft Graph](http://developer.microsoft.com/graph) 70 | 71 | ## Copyright 72 | 73 | Copyright (c) 2016 Microsoft. All rights reserved. 74 | -------------------------------------------------------------------------------- /app.js: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. 3 | * See LICENSE in the project root for license information. 4 | */ 5 | 6 | /* 7 | * This sample uses an open source OAuth 2.0 library that is compatible with the Azure AD v2.0 endpoint. 8 | * Microsoft does not provide fixes or direct support for this library. 9 | * Refer to the library’s repository to file issues or for other support. 10 | * For more information about auth libraries see: 11 | * https://azure.microsoft.com/documentation/articles/active-directory-v2-libraries/ 12 | * Library repo: https://github.com/jaredhanson/passport 13 | */ 14 | 15 | 'use strict'; 16 | // set up ====================================================================== 17 | const express = require('express'); 18 | const session = require('express-session'); 19 | const port = process.env.PORT || 3000; 20 | const http = require('http'); 21 | const morgan = require('morgan'); 22 | const bodyParser = require('body-parser'); 23 | const methodOverride = require('method-override'); 24 | const cookieParser = require('cookie-parser'); 25 | const passport = require('passport'); 26 | const OIDCStrategy = require('passport-azure-ad').OIDCStrategy; 27 | const emailHelper = require('./utils/emailHelper.js'); 28 | const config = require('./utils/config.js'); 29 | const graphHelper = require('./utils/graphHelper.js'); 30 | const graph = require('@microsoft/microsoft-graph-client'); 31 | 32 | const app = express(); 33 | const server = http.createServer(app); 34 | 35 | // **IMPORTANT 36 | // Note that you will need to create a self-signed cert and use a secure server. 37 | // Below is an example after you have the key cert pair: 38 | // const https = require('https'); 39 | // const certConfig = { 40 | // key: fs.readFileSync('./utils/cert/server.key', 'utf8'), 41 | // cert: fs.readFileSync('./utils/cert/server.crt', 'utf8') 42 | // }; 43 | // const server = https.createServer(certConfig, app); 44 | 45 | // authentication ================================================================= 46 | var callback = (iss, sub, profile, accessToken, refreshToken, done) => { 47 | if (!profile.oid) { 48 | return done(new Error("No oid found"), null); 49 | } 50 | 51 | findByOid(profile.oid, function(err, user){ 52 | if (err) { 53 | return done(err); 54 | } 55 | 56 | if (!user) { 57 | users.push({profile, accessToken, refreshToken}); 58 | return done(null, profile); 59 | } 60 | 61 | return done(null, user); 62 | }); 63 | }; 64 | 65 | passport.use(new OIDCStrategy(config.creds, callback)); 66 | 67 | const users = []; 68 | 69 | passport.serializeUser((user, done) => { 70 | done(null, user.oid); 71 | }); 72 | 73 | passport.deserializeUser((id, done) => { 74 | findByOid(id, function (err, user) { 75 | done(err, user); 76 | }); 77 | }); 78 | 79 | var findByOid = function(oid, fn) { 80 | for (var i = 0, len = users.length; i < len; i++) { 81 | var user = users[i]; 82 | if (user.profile.oid === oid) { 83 | return fn(null, user); 84 | } 85 | } 86 | return fn(null, null); 87 | }; 88 | 89 | // configuration =============================================================== 90 | app.use(express.static(__dirname + '/public')); 91 | app.use(morgan('dev')); 92 | app.use(bodyParser.urlencoded({'extended':'true'})); 93 | app.use(bodyParser.json()); 94 | app.use(methodOverride()); 95 | app.set('view engine', 'pug'); 96 | app.use(cookieParser()); 97 | app.use(session({ 98 | secret: 'sshhhhhh', 99 | name: 'graphNodeCookie', 100 | resave: false, 101 | saveUninitialized: false 102 | })); 103 | app.use(passport.initialize()); 104 | app.use(passport.session()); 105 | 106 | 107 | // application ================================================================= 108 | app.get('/', function(req, res){ 109 | if (req.isAuthenticated()) { 110 | var userEmail = req.user.email; 111 | if (userEmail === undefined) { 112 | graphHelper.getUserEmail(req.user, function(err, email){ 113 | if (email) 114 | { 115 | userEmail = email; 116 | // Update user in cache 117 | var userIndex = users.findIndex((obj => obj.profile.oid == req.user.profile.oid)); 118 | users[userIndex]["email"] = email; 119 | 120 | res.render('emailSender', { user: req.user.profile, email: userEmail }); 121 | } 122 | }); 123 | } else { 124 | res.render('emailSender', { user: req.user.profile, email: userEmail }); 125 | } 126 | } else { 127 | res.render('login'); 128 | } 129 | }); 130 | 131 | app.get('/login', 132 | function(req, res, next) { 133 | passport.authenticate('azuread-openidconnect', 134 | { 135 | response: res, 136 | failureRedirect: '/' 137 | })(req, res, next); 138 | }, 139 | function (req, res) { 140 | res.redirect('/'); 141 | }); 142 | 143 | app.get('/token', 144 | function(req, res, next) { 145 | passport.authenticate('azuread-openidconnect', 146 | { 147 | response: res, 148 | failureRedirect: '/' 149 | } 150 | )(req, res, next); 151 | }, 152 | function (req, res) { 153 | res.redirect('/'); 154 | }); 155 | 156 | app.post('/emailSender', 157 | ensureAuthenticated, 158 | (req, res) => { 159 | const mailBody = emailHelper.generateMailBody(req.user.profile.displayName, req.body.input_email); 160 | 161 | graphHelper.sendEmail(req.user, mailBody, function(err) { 162 | if (err) { 163 | renderError(res, err); 164 | return; 165 | } 166 | 167 | console.log("Sent an email"); 168 | res.render('emailSender', { user: req.user.profile, status: "success"}); 169 | }); 170 | }); 171 | 172 | app.get('/logout', (req, res) => { 173 | // Remove user from cache 174 | users.splice( 175 | users.findIndex((obj => obj.profile.oid == req.user.profile.oid)), 1); 176 | req.session.destroy( (err) => { 177 | req.logOut(); 178 | res.clearCookie('graphNodeCookie'); 179 | res.status(200); 180 | res.redirect('http://localhost:' + port); 181 | }); 182 | }); 183 | 184 | // listen (start app with node app.js) ====================================== 185 | server.listen(port); 186 | console.log("Magic happens here: http://localhost:" + port); 187 | 188 | function ensureAuthenticated (req, res, next) { 189 | if (req.isAuthenticated()) { return next(); } 190 | 191 | res.render('/login'); 192 | }; 193 | 194 | // error handling =========================================================== 195 | function renderError (res, e) { 196 | res.render('error', { 197 | message: e.message, 198 | error: e 199 | }); 200 | console.error(e); 201 | }; 202 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | Contribute to this documentation 2 | 3 | Thank you for your interest in our documentation! 4 | 5 | * [Ways to contribute](#ways-to-contribute) 6 | * [Contribute using GitHub](#contribute-using-github) 7 | * [Contribute using Git](#contribute-using-git) 8 | * [How to use Markdown to format your topic](#how-to-use-markdown-to-format-your-topic) 9 | * [FAQ](#faq) 10 | * [More resources](#more-resources) 11 | 12 | ## Ways to contribute 13 | 14 | Here are some ways you can contribute to this documentation: 15 | 16 | * To make small changes to an article, [Contribute using GitHub](#contribute-using-github). 17 | * To make large changes, or changes that involve code, [Contribute using Git](#contribute-using-git). 18 | * Report documentation bugs via GitHub Issues 19 | * Request new documentation at the [Office Developer Platform UserVoice](http://officespdev.uservoice.com) site. 20 | 21 | ## Contribute using GitHub 22 | 23 | Use GitHub to contribute to this documentation without having to clone the repo to your desktop. This is the easiest way to create a pull request in this repository. Use this method to make a minor change that doesn't involve code changes. 24 | 25 | **Note** Using this method allows you to contribute to one article at a time. 26 | 27 | ### To Contribute using GitHub 28 | 29 | 1. Find the article you want to contribute to on GitHub. 30 | 31 | If the article is in MSDN, choose the **suggest and submit changes** link in the **Contribute to this content** section and you'll be taken to the same article on GitHub. 32 | 2. Once you are on the article in GitHub, sign in to GitHub (get a free account [Join GitHub](https://github.com/join). 33 | 3. Choose the **pencil icon** (edit the file in your fork of this project) and make your changes in the **<>Edit file** window. 34 | 4. Scroll to the bottom and enter a description. 35 | 5. Choose **Propose file change**>**Create pull request**. 36 | 37 | You now have successfully submitted a pull request. Pull requests are typically reviewed within 10 business days. 38 | 39 | 40 | ## Contribute using Git 41 | 42 | Use Git to contribute substantive changes, such as: 43 | 44 | * Contributing code. 45 | * Contributing changes that affect meaning. 46 | * Contributing large changes to text. 47 | * Adding new topics. 48 | 49 | ### To Contribute using Git 50 | 51 | 1. If you don't have a GitHub account, set one up at [GitHub](https://github.com/join). 52 | 2. After you have an account, install Git on your computer. Follow the steps in [Setting up Git Tutorial](https://help.github.com/articles/set-up-git/). 53 | 3. To submit a pull request using Git, follow the steps in [Use GitHub, Git, and this repository](#use-github-git-and-this-repository). 54 | 4. You will be asked to sign the Contributor's License Agreement if you are: 55 | 56 | * A member of the Microsoft Open Technologies group. 57 | * A contributors who doesn't work for Microsoft. 58 | 59 | As a community member, you must sign the Contribution License Agreement (CLA) before you can contribute large submissions to a project. You only need to complete and submit the documentation once. Carefully review the document. You may be required to have your employer sign the document. 60 | 61 | Signing the CLA does not grant you rights to commit to the main repository, but it does mean that the Office Developer and Office Developer Content Publishing teams will be able to review and approve your contributions. You will be credited for your submissions. 62 | 63 | Pull requests are typically reviewed within 10 business days. 64 | 65 | ## Use GitHub, Git, and this repository 66 | 67 | **Note:** Most of the information in this section can be found in [GitHub Help] articles. If you're familiar with Git and GitHub, skip to the **Contribute and edit content** section for the specifics of the code/content flow of this repository. 68 | 69 | ### To set up your fork of the repository 70 | 71 | 1. Set up a GitHub account so you can contribute to this project. If you haven't done this, go to [GitHub](https://github.com/join) and do it now. 72 | 2. Install Git on your computer. Follow the steps in the [Setting up Git Tutorial] [Set Up Git]. 73 | 3. Create your own fork of this repository. To do this, at the top of the page, choose the **Fork** button. 74 | 4. Copy your fork to your computer. To do this, open Git Bash. At the command prompt enter: 75 | 76 | git clone https://github.com//.git 77 | 78 | Next, create a reference to the root repository by entering these commands: 79 | 80 | cd 81 | git remote add upstream https://github.com/microsoftgraph/.git 82 | git fetch upstream 83 | 84 | Congratulations! You've now set up your repository. You won't need to repeat these steps again. 85 | 86 | ### Contribute and edit content 87 | 88 | To make the contribution process as seamless as possible, follow these steps. 89 | 90 | #### To contribute and edit content 91 | 92 | 1. Create a new branch. 93 | 2. Add new content or edit existing content. 94 | 3. Submit a pull request to the main repository. 95 | 4. Delete the branch. 96 | 97 | **Important** Limit each branch to a single concept/article to streamline the work flow and reduce the chance of merge conflicts. Content appropriate for a new branch includes: 98 | 99 | * A new article. 100 | * Spelling and grammar edits. 101 | * Applying a single formatting change across a large set of articles (for example, applying a new copyright footer). 102 | 103 | #### To create a new branch 104 | 105 | 1. Open Git Bash. 106 | 2. At the Git Bash command prompt, type `git pull upstream master:`. This creates a new branch locally that is copied from the latest MicrosoftGraph master branch. 107 | 3. At the Git Bash command prompt, type `git push origin `. This alerts GitHub to the new branch. You should now see the new branch in your fork of the repository on GitHub. 108 | 4. At the Git Bash command prompt, type `git checkout ` to switch to your new branch. 109 | 110 | #### Add new content or edit existing content 111 | 112 | You navigate to the repository on your computer by using File Explorer. The repository files are in `C:\Users\\`. 113 | 114 | To edit files, open them in an editor of your choice and modify them. To create a new file, use the editor of your choice and save the new file in the appropriate location in your local copy of the repository. While working, save your work frequently. 115 | 116 | The files in `C:\Users\\` are a working copy of the new branch that you created in your local repository. Changing anything in this folder doesn't affect the local repository until you commit a change. To commit a change to the local repository, type the following commands in GitBash: 117 | 118 | git add . 119 | git commit -v -a -m "" 120 | 121 | The `add` command adds your changes to a staging area in preparation for committing them to the repository. The period after the `add` command specifies that you want to stage all of the files that you added or modified, checking subfolders recursively. (If you don't want to commit all of the changes, you can add specific files. You can also undo a commit. For help, type `git add -help` or `git status`.) 122 | 123 | The `commit` command applies the staged changes to the repository. The switch `-m` means you are providing the commit comment in the command line. The -v and -a switches can be omitted. The -v switch is for verbose output from the command, and -a does what you already did with the add command. 124 | 125 | You can commit multiple times while you are doing your work, or you can commit once when you're done. 126 | 127 | #### Submit a pull request to the main repository 128 | 129 | When you're finished with your work and are ready to have it merged into the main repository, follow these steps. 130 | 131 | #### To submit a pull request to the main repository 132 | 133 | 1. In the Git Bash command prompt, type `git push origin `. In your local repository, `origin` refers to your GitHub repository that you cloned the local repository from. This command pushes the current state of your new branch, including all commits made in the previous steps, to your GitHub fork. 134 | 2. On the GitHub site, navigate in your fork to the new branch. 135 | 3. Choose the **Pull Request** button at the top of the page. 136 | 4. Verify the Base branch is `microsoftgraph/@master` and the Head branch is `/@`. 137 | 5. Choose the **Update Commit Range** button. 138 | 6. Add a title to your pull request, and describe all the changes you're making. 139 | 7. Submit the pull request. 140 | 141 | One of the site administrators will process your pull request. Your pull request will surface on the microsoftgraph/ site under Issues. When the pull request is accepted, the issue will be resolved. 142 | 143 | #### Create a new branch after merge 144 | 145 | After a branch is successfully merged (that is, your pull request is accepted), don't continue working in that local branch. This can lead to merge conflicts if you submit another pull request. To do another update, create a new local branch from the successfully merged upstream branch, and then delete your initial local branch. 146 | 147 | For example, if your local branch X was successfully merged into the OfficeDev/microsoft-graph-docs master branch and you want to make additional updates to the content that was merged. Create a new local branch, X2, from the OfficeDev/microsoft-graph-docs master branch. To do this, open GitBash and execute the following commands: 148 | 149 | cd microsoft-graph-docs 150 | git pull upstream master:X2 151 | git push origin X2 152 | 153 | You now have local copies (in a new local branch) of the work that you submitted in branch X. The X2 branch also contains all the work other writers have merged, so if your work depends on others' work (for example, shared images), it is available in the new branch. You can verify that your previous work (and others' work) is in the branch by checking out the new branch... 154 | 155 | git checkout X2 156 | 157 | ...and verifying the content. (The `checkout` command updates the files in `C:\Users\\microsoft-graph-docs` to the current state of the X2 branch.) Once you check out the new branch, you can make updates to the content and commit them as usual. However, to avoid working in the merged branch (X) by mistake, it's best to delete it (see the following **Delete a branch** section). 158 | 159 | #### Delete a branch 160 | 161 | Once your changes are successfully merged into the main repository, delete the branch you used because you no longer need it. Any additional work should be done in a new branch. 162 | 163 | #### To delete a branch 164 | 165 | 1. In the Git Bash command prompt, type `git checkout master`. This ensures that you aren't in the branch to be deleted (which isn't allowed). 166 | 2. Next, at the command prompt, type `git branch -d `. This deletes the branch on your computer only if it has been successfully merged to the upstream repository. (You can override this behavior with the `–D` flag, but first be sure you want to do this.) 167 | 3. Finally, type `git push origin :` at the command prompt (a space before the colon and no space after it). This will delete the branch on your github fork. 168 | 169 | Congratulations, you have successfully contributed to the project! 170 | 171 | ## How to use Markdown to format your topic 172 | 173 | ### Article template 174 | 175 | The [markdown template](/articles/0-markdown-template-for-new-articles.md) contains the basic Markdown for a topic that includes a table of contents, sections with subheadings, links to other Office developer topics, links to other sites, bold text, italic text, numbered and bulleted lists, code snippets, and images. 176 | 177 | 178 | ### Standard Markdown 179 | 180 | All of the articles in this repository use Markdown. A complete introduction (and listing of all the syntax) can be found at [Markdown Home] []. 181 | 182 | ## FAQ 183 | 184 | ### How do I get a GitHub account? 185 | 186 | Fill out the form at [Join GitHub](https://github.com/join) to open a free GitHub account. 187 | 188 | ### Where do I get a Contributor's License Agreement? 189 | 190 | You will automatically be sent a notice that you need to sign the Contributor's License Agreement (CLA) if your pull request requires one. 191 | 192 | As a community member, **you must sign the Contribution License Agreement (CLA) before you can contribute large submissions to this project**. You only need complete and submit the documentation once. Carefully review the document. You may be required to have your employer sign the document. 193 | 194 | ### What happens with my contributions? 195 | 196 | When you submit your changes, via a pull request, our team will be notified and will review your pull request. You will receive notifications about your pull request from GitHub; you may also be notified by someone from our team if we need more information. We reserve the right to edit your submission for legal, style, clarity, or other issues. 197 | 198 | ### Can I become an approver for this repository's GitHub pull requests? 199 | 200 | Currently, we are not allowing external contributors to approve pull requests in this repository. 201 | 202 | ### How soon will I get a response about my change request or issue? 203 | 204 | We typically review pull requests and respond to issues within 10 business days. 205 | 206 | ## More resources 207 | 208 | * To learn more about Markdown, go to the Git creator's site [Daring Fireball]. 209 | * To learn more about using Git and GitHub, first check out the [GitHub Help section] [GitHub Help]. 210 | 211 | [GitHub Home]: http://github.com 212 | [GitHub Help]: http://help.github.com/ 213 | [Set Up Git]: http://help.github.com/win-set-up-git/ 214 | [Markdown Home]: http://daringfireball.net/projects/markdown/ 215 | [Daring Fireball]: http://daringfireball.net/ --------------------------------------------------------------------------------