adding more content for site design

Author: davidchesnut

docs/declarative-customization/get-started-create-site-design.md

@@ -1,8 +1,17 @@
+---
+title: Get started creating SharePoint site designs and site scripts
+description: Get started creating SharePoint site designs and site scripts for users to create their own sites from.
+ms.date: 12/14/2017
+---
+
 # Get started creating site designs and site scripts
 
+> [!NOTE]
+> Site designs and site scripts are currently in preview and are subject to change. They are not currently supported for us in production environments.
+
 Build site designs to provide reusable lists, themes, layouts, pages, or custom actions so that your users can quickly build new SharePoint sites with the features they need. In this article you'll build a simple site design that adds a SharePoint list for tracking customer orders. Then you'll use the site design to create a new SharePoint site with the custom list.
 
-This article shows how to use SharePoint PowerShell cmdlets to create site scripts and site designs. You can also use CSOM and REST APIs to perform the same actions. The corresponding CSOM and REST calls are shown for reference in each step.
+This article shows how to use SharePoint PowerShell cmdlets to create site scripts and site designs. You can also use REST APIs to perform the same actions. The corresponding REST calls are shown for reference in each step.
 
 ## Create the site script in JSON
 
@@ -14,9 +23,6 @@ Each action is specified by the "verb" value in the JSON scipt. Also, actions ca
 1. Follow the instructions at [Connect to SharePoint Online PowerShell](https://technet.microsoft.com/en-us/library/fp161372.aspx) to connect to your SharePoint tenant.
 1. Create and assign the JSON that descripts the new script to a variable as shown in the PowerShell code below.
 
-> ![NOTE]
->  You can also specify the script in a CSV format. (TBD link to more info on CSV example)
-
 ```powershell
 $site_script = @'
 {
@@ -71,31 +77,31 @@ The previous script will create a new SharePoint list named Customer Tracking. I
 
 ## Add the site script
 
-Each site script must be registered in SharePoint so that it is available to. Add a new site design by using the **Add-SPOSiteScript** command. The following example shows how to add the JSON script described previously.
+Each site script must be registered in SharePoint so that it is available to. Add a new site design by using the **Add-SPOSiteScript** cmdlet. The following example shows how to add the JSON script described previously.
 
 ```powershell
 C:\> Add-SPOSiteScript -Title "Create customer tracking list" -Content $site_script -Description "Creates list for tracking customer contact information"
 ```
 
-After running the command you will get a result that lists the site script **ID** of the added script. Keep track of this ID somewhere because you will need it later when you create the site design.
+After running the cmdlet you will get a result that lists the site script **ID** of the added script. Keep track of this ID somewhere because you will need it later when you create the site design.
 
-The REST API to add a new site script is **CreateSiteScript**. (TBD add CSOM link)
+The REST API to add a new site script is **CreateSiteScript**.
 
 ## Create the site design
 
 Next you need to create the site design. The site design will appear in a drop down list when someone creates a new site from one of the templates. It can run one or more site scripts that have already been added.
 
-- Run the following command to add a new site design. Replace \<ID\> with the site script ID from when you added the site script.
+- Run the following cmdlet to add a new site design. Replace \<ID\> with the site script ID from when you added the site script.
 
 ```powershell
 C:\> Add-SPOSiteDesign -Title "Contoso customer tracking" -WebTemplate "64" -SiteScripts "<ID>" -Description "Tracks key customer data in a list"
 ```
 
-The previous command creates a new site design named Contoso customer tracking. The -WebTemplate value selects which base template to associate with. The value "64" indicates Team site template, and the value "68" indicates the communication site template.
+The previous cmdlet creates a new site design named Contoso customer tracking. The -WebTemplate value selects which base template to associate with. The value "64" indicates Team site template, and the value "68" indicates the communication site template.
 
-The JSON response will display the **ID** of the new site design. You can use in subsequent commands to update or modify the site design.
+The JSON response will display the **ID** of the new site design. You can use in subsequent cmdlets to update or modify the site design.
 
-The REST API to add a new site design is **CreateSiteDesign**. (TBD add CSOM link)
+The REST API to add a new site design is **CreateSiteDesign**.
 
 ## Use the new site design
 

docs/declarative-customization/site-design-apply-default-template.md

@@ -0,0 +1,10 @@
+---
+title: Applying a site design to a default SharePoint template
+description: Customize the SharePoint team site or communications site template by applying a site design
+ms.date: 12/14/2017
+---
+
+# Applying a site design to a default SharePoint template
+
+> [!NOTE]
+> Site designs and site scripts are currently in preview and are subject to change. They are not currently supported for us in production environments.

docs/declarative-customization/site-design-json-schema.md

@@ -1,12 +1,14 @@
 ---
-# Mandatory fields. See more on aka.ms/skyeye/meta.
 title: Site design JSON schema
 description: JSON schema reference for building site designs for SharePoint.
-ms.date: 11/19/2017
+ms.date: 12/14/2017
 ---
 
 # Site design JSON schema
 
+> [!NOTE]
+> Site designs and site scripts are currently in preview and are subject to change. They are not currently supported for us in production environments.
+
 The site design is a list of actions. For more complex actions, such as creating a list, there are also subactions. Each action is specified by a "verb" value. Verb actions are run in the order they appear in the JSON script.
 
 The overall JSON structure is specified as follows:
@@ -210,13 +212,16 @@ JSON value:
 
 Example:
 
+<!-- TBD: add link to Doug's Blue Yonder theme with note you need to create it first -->
+
 ```json
 {
    "verb": "applyTheme",
    "themeName": "Blue Yonder"
 }
 ```
 
+<!-- 
 ## Create a page
 
 Use the **createPage** verb to create a new page on the site.
@@ -247,6 +252,7 @@ Example:
     "setAsHomePage": true
 }
 ```
+-->
 
 ## Set a site logo
 
@@ -267,7 +273,7 @@ Example:
 
 ## Join a hub site
 
-Use the **joinHubSite** verb to join the site to a hub. <TBD provide link to more information on hubs and how to get the id>
+Use the **joinHubSite** verb to join the site to a hub. <!-- TBD provide link to more information on hubs and how to get the id -->
 
 JSON value:
 
@@ -285,6 +291,7 @@ Example:
 ## Trigger a flow
 
 Use the **triggerFlow** verb to kick off a custom flow.
+<!-- update this with example from trigger workflow topic -->
 
 JSON values:
 

docs/declarative-customization/site-design-overview.md

@@ -1,11 +1,14 @@
 ---
 title: SharePoint site design and site script overview
-description: Use site scripts and site designs to automate provisioning new SharePoint sites with custom configurations.
-ms.date: 11/19/2017
+description: Use SharePoint site scripts and site designs to automate provisioning new SharePoint sites with custom configurations.
+ms.date: 12/14/2017
 ---
 
 # SharePoint site design and site script overview
 
+> [!NOTE]
+> Site designs and site scripts are currently in preview and are subject to change. They are not currently supported for us in production environments.
+
 Use site designs and site scripts to automate provisioning new SharePoint sites using your own custom configurations. When people in your organization create new SharePoint sites, you often need to ensure some level of consistency. For example, you may need proper branding and theming applied to each new site. You may also have detailed site provisioning scripts, such as using the PnP provisioning engine, that need to be applied each time a new site is created. This article describes how you can use site designs and site scripts to provide custom configurations to apply when new sites are created.
 
 ## How site designs work
@@ -18,15 +21,24 @@ Once a site design is selected, SharePoint creates the new site, and then runs a
 
 ![Progress pane listing completed actions from a site design](images/progress-pane.png)
 
-You can create a site design by using PowerShell, CSOM, or the REST API. Here's an example of creating a new site design for the purpose of applying company branding.
+You can create a site design by using PowerShell, or the REST API. Here's an example that creates a new site design that creates a customer list and applies a theme.
 
+```powershell
+C:\> Add-SPOSiteDesign `
+  -Title "Contoso customer tracking" `
+  -WebTemplate "64" `
+  -SiteScripts ("607aed52-6d61-490a-b692-c0f58a6981a1","5d4756e9-e1f5-42f7-afa7-5fa5aac170aa") `
+  -Description "Creates customer list and applies standard theme" `
 ```
-TBD Powershell example of creating site design for brand (show isdefault)
+
+```javascript
+RestRequest("/_api/Microsoft.Sharepoint.Utilities.WebTemplateExtensions.SiteScriptUtility.CreateSiteDesign", {info:{Title:"Contoso customer tracking", Description:"Creates customer list and applies standard theme", SiteScriptIds:["607aed52-6d61-490a-b692-c0f58a6981a1","5d4756e9-e1f5-42f7-afa7-5fa5aac170aa"],  WebTemplate:"64"}});
 ```
 
-You can also make a site design the default for the team or communication site template. Then when someone chooses only the template, you can still apply a custom design. This is done by setting the **IsDefault** property to true as shown previously.
+In the previous example, the **SiteScripts** parameter contains the ID of two scripts that detail each action to run. We'll look at the site script contents in more detail later. The scripts will run in the order listed. The **WebTemplate** parameter value 64 indicates to register this site design with the team site template. The **Title** and **Description** parameters will be displayed when a user views site designs as they create a new team site. For more information on creating a site design, see [Get started creating site designs](get-started-create-site-design.md)
 
-For more information, see [Get started creating site designs](get-started-create-site-design.md)
+> [!NOTE]
+> You can also make a site design the default for the team or communication site template. In this way you can modify the out-of-the-box base templates. For more information, see [Applying a site design to a default SharePoint template](site-design-apply-default-template.md).
 
 ## Anatomy of a site script
 
@@ -86,7 +98,7 @@ Site scripts are JSON files that specify an ordered list of actions to run when
 
 Each action in a site script is specified by a **verb** value in the JSON. In the previous script the first action is specified by the **applyTheme** verb. Then the **createSPList** verb creates the list. Notice that the **createSPList** verb contains its own set of verbs which run additional actions on just the list.
 
-Actions include:
+Available actions include:
 
 - Creating a new list
 - Applying a theme
@@ -95,7 +107,7 @@ Actions include:
 - Adding navigation
 - Triggering a Microsoft flow
 
-You can create site scripts by using PowerShell, CSOM, or the REST API. Here's an example of how to create a site script that applies the Blue Yonder theme.
+You can create site scripts by using PowerShell or the REST API. Here's an example of how to create a site script that applies the Blue Yonder theme.
 
 ```
 TBD PowerShell example create a script for blue yonder theme
@@ -120,16 +132,25 @@ The process works as follows:
 1. The message triggers a call to an Azure function that you have configured.
 1. The Azure function runs your custom script, such as the PnP provisioning engine, to apply your custom configurations.
 
-For a step-by-step tutorial on how to configure your own Microsoft flow with PnP provisioning, see [Build a complete site design using the PnP provisioning engine](site-design-pnp-provisioning)
+For a step-by-step tutorial on how to configure your own Microsoft flow with PnP provisioning, see [Build a complete site design using the PnP provisioning engine](site-design-pnp-provisioning.md)
 
 ## Scoping
 
 You can configure site designs to only appear for specific groups or people in your organization. This is useful to ensure that people only see the site designs intended for them. For example, you may want the accounting department to only see site designs specific for them. And the accounting site designs may not make sense to show to anyone else.
 
-Scopes are applied when you register a site design. You can specify the scope by user, Office 365 group, or a mail-enabled security group. Here is an example of registering a site design for only the accounting Office 365 group:
+Scopes are applied when you register a site design. You can specify the scope by user, or a mail-enabled security group. Here is an example of registering a site design for only the accounting Office 365 group:
 
+Here's an example of how to scope an existing site design so that only Nestor (a user at the fictional Contoso site) can view and use the site design.
+
+```powershell
+Grant-SPOSiteDesignRights `
+  -Identity 44252d09-62c4-4913-9eb0-a2a8b8d7f863 `
+  -Principals "[email protected]" `
+  -Rights View
 ```
-TBD: PowerShell example register a scoped site design
+
+```javascript
+RestRequest("/_api/Microsoft.Sharepoint.Utilities.WebTemplateExtensions.SiteScriptUtility.GrantSiteDesignRights", {id:"44252d09-62c4-4913-9eb0-a2a8b8d7f863", principalNames:["[email protected]”], grantedRights:1});
 ```
 
 For more information, see [Apply a scope to your site design](site-design-scopes.md).

docs/declarative-customization/site-design-pnp-provisioning.md

@@ -1,12 +1,14 @@
 ---
-# Mandatory fields. See more on aka.ms/skyeye/meta.
-title: Build a complete site design using the PnP provisioning engine
-description: Build a complete site design using the PnP provisioning engine
-ms.date: 11/19/2017
+title: Build a complete SharePoint site design using the PnP provisioning engine
+description: Build a complete SharePoint site design using the PnP provisioning engine
+ms.date: 12/14/2017
 ---
 
 # Calling the PnP Provisioning Engine from a Site Script
 
+> [!NOTE]
+> Site designs and site scripts are currently in preview and are subject to change. They are not currently supported for us in production environments.
+
 Site Designs offer a great way to standardize the look and feel of your site collections. But if you want to take this one step further, by for instance adding a footer to every page, you might notice that Site Designs do not offer you that option. With the PnP Provisioning engine you can hover create a template which allows you to provision an application customizer to a site. This application customizer then can register a footer on every page. In this article you will learn how to create a site design that applies a PnP Provisioning Template to a site which in turn will add an application customizer to render a footer.
 
 We use the following components in our setup: