diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index f843f6c1e..67b987f8d 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,5 +1,5 @@ # Contribute to SharePoint developer documentation -Below instructions explain how you can prepare your environment to contribute to SharePoint Developer Documentation. +These instructions explain how you can prepare your environment to contribute to SharePoint Developer Documentation. ## Docs repo structure @@ -7,8 +7,10 @@ Before you decide to contribute, it is important to understand the `sp-dev-docs` ``` sp-dev-docs ---images +--assets --docs +--general-development +--images ``` The `docs` folder contains the key developer topics: @@ -20,7 +22,7 @@ docs ``` At this time, contributions are accepted for: -* SharePoint Framework Developer Preview +* SharePoint Framework * SharePoint Webhooks ### SPFx Folder @@ -30,20 +32,20 @@ The `spfx` folder contains documentation for SharePoint Framework. It is further ``` docs --spfx ----webparts +---web-parts -----basics -----get-started ------developer-guide +-----guidance ``` #### Component folder Every component folder contains the following folders: * basics - * `basics` folder contains concept docs that are helpful in building that particular component, for example: `web parts`. + * `basics` folder contains concept docs that are helpful in building that particular component, for example: `web-parts`. * get-started - * `get-started` folder contains walkthroughs and tutorials on how to get started building that particular component, for example: `web parts`. -* developer-guide - * `developer-guide` folder contains guides, best practices and reference implementations for that particular component, for example: `web parts`. + * `get-started` folder contains walkthroughs and tutorials on how to get started building that particular component, for example: `web-parts`. +* guidance + * `guidance` folder contains guides, best practices and reference implementations for that particular component, for example: `web-parts`. * Any images associated with the docs should be uploaded into the `sp-dev-docs\images` folder. @@ -80,9 +82,10 @@ Now that you have forked the docs repository, to sync this forked repository to ![Clone the forked SharePoint developer docs repository](../images/contribute-docs-clone-options.png) -If you have any Git Desktop or any git source control installed, you can click the `Open is Desktop`, else follow the steps below: +If you have any Git Desktop or any git source control installed, you can click the `Open in Desktop` or follow the steps below: -In the Clone with HTTPs section, click to copy the clone URL for the repository. +In the `Clone with HTTPs` section, click ![](../images/contribute-clone-icon.png) + to copy the clone URL for the repository. * Open your favorite console terminal. @@ -105,14 +108,14 @@ remove: Total 10 (delta 1), reused 10 (delta 1) Unpacking objects: 100% (10/10), done. ``` -## Switch to `staging` branch +## Switch to `main` branch -In order to add your changes, you will need to do those in the `staging` branch. +In order to add your changes, you will need to do those in the `main` branch. -Type the following command in the console to switch to `staging` branch: +Type the following command in the console to switch to `main` branch: ``` -git checkout staging +git checkout main ``` Now, you can update existing docs or add new docs to the docs repo. @@ -128,20 +131,22 @@ Depending on the doc's intent, you can choose to add your doc into `basics` or ## Submit a pull request -Once you have completed adding your changes, you can submit a pull request. +Once you have completed adding your changes, you can submit a pull request. -Navigate to the forked sp-dev-docs repo in your account. Make sure your current branch is `staging` branch. +Navigate to the forked sp-dev-docs repo in your account. Make sure your current branch is `main` branch. -Once you are in the staging branch, you should see a message to `Compare & pull request` +Once you are in the `main` branch, you should see a message stating `This branch is 1 commit ahead of Sharepoint:main` and next to it will be a `Pull request` link. ![Submit a pull request to sp-dev-docs repo](../images/contribute-docs-submit-pr.png) -This will start a new pull request. Make sure you use the following [template]() to fill in your changes. Make sure you are creating this pull request against the `staging` branch. +Click the `Pull request` link to start a new pull request. Make sure you use this [template](PULL_REQUEST_TEMPLATE.md) to fill in your changes. Make sure you are creating this pull request against the `main` branch. + +Once you have all the information, click the `Create pull request` button to submit your pull request. -Once you have all the information, click the `Create pull request` to submit your pull request. +![Create pull request](../images/contribute-docs-create-pr.png) ## Syncing your forked repository to keep it up-to-date with the upstream repository In order to keep your forked sp-dev-docs repo up-to-date with the parent repository, you will need to first [configure a remote that points to upstream repository](https://help.github.com/articles/configuring-a-remote-for-a-fork). -Once you have configured the upstream repository, follow the steps [here](https://help.github.com/articles/configuring-a-remote-for-a-fork) to sync your fork to keep it up-to-date with the upstream repository. +Once you have configured the upstream repository, follow the steps [here](https://help.github.com/en/articles/syncing-a-fork) to sync your fork to keep it up-to-date with the upstream repository. diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md deleted file mode 100644 index ebaff3062..000000000 --- a/.github/ISSUE_TEMPLATE.md +++ /dev/null @@ -1,27 +0,0 @@ -Thank you for reporting an issue or suggesting an enhancement. We appreciate your feedback - to help the team to understand your needs, please complete the below template to ensure we have the necessary details to assist you. - -#### Category -- [ ] Question -- [ ] Typo -- [ ] Bug -- [ ] Enhancement / Suggestion -- [ ] Additional article idea - -#### Expected or Desired Behavior -_If you are reporting a bug, please describe the expected behavior. If you are suggesting an enhancement please describe thoroughly the enhancement, how it can be achieved, and expected benefit._ - -#### Observed Behavior -_If you are reporting a bug, please describe the behavior you expected to occur when performing the action. If you are making a suggestion, you can delete this section._ - -#### Steps to Reproduce -_If you are reporting a bug please describe the steps to reproduce the bug in sufficient detail to allow testing. Only way to fix things properly, is to have sufficient details to reproduce it. If you are making a suggestion, you can delete this section._ - -#### Submission Guidelines -_Delete this section after reading_ -- All suggestions or bugs are welcome, please let us know what's on your mind. -- If you are reporting an issue around any of the documents or articles, please ensure that you have clear reference on the specific file or URL, which should be fixed. -- If you have technical questions about the framework, we’ll be monitoring #spfx, #spfx-webparts, and #spfx-tooling on (SharePoint StackExchange)[http://sharepoint.stackexchange.com/]. You can also alternatively submit your question to (SharePoint Developer group)[https://network.office.com/t5/SharePoint-Developer/bd-p/SharePointDev] at Office Network. -- Remember to include sufficient details and context. -- If you have multiple suggestions or bugs please submit them in separate bugs so we can track resolution. - -Thanks for your contribution! Sharing is caring. diff --git a/.github/ISSUE_TEMPLATE/bug-report.yml b/.github/ISSUE_TEMPLATE/bug-report.yml new file mode 100644 index 000000000..6d3825f0c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug-report.yml @@ -0,0 +1,116 @@ +name: 🐞 Bug or Error Report +description: Submit a bug or error report. +labels: ['Needs: Triage', 'type:bug-suspected'] + +body: +- type: markdown + attributes: + value: | + - [x] Bug + + This is for SharePoint development bugs. If your submission is not about SharePoint development such as out-of-the-box capabilities, SharePoint configuration, please refer to other support options listed on the [new issue chooser page](https://github.com/SharePoint/sp-dev-docs/issues/new/choose). Please provide as much information as possible so we can best address your submission. Thanks! + + - Follow our guidance on [How To Create Good Issues](https://github.com/sharepoint/sp-dev-docs/wiki/How-to-Create-Good-Issues). + - Remember to include sufficient details and context. + - If you have multiple questions, suggestions, or bugs, please submit them in separate issues. + + Please provide the following details about your environment. 🚨 *If this section is ignored, your submission will be flagged as **incomplete** & automatically closed.* + +- type: dropdown + attributes: + label: Target SharePoint environment + options: + - SharePoint Online + - SharePoint Server 2019 (on-premise) + - SharePoint Server 2016 (on-premise) + - other (enter in the "Additional environment details" area below) + validations: + required: true + +- type: dropdown + attributes: + label: What SharePoint development model, framework, SDK or API is this about? + description: | + What tooling, frameworks, SDKs, or official libraries is this related to? Please include the version details in the *"Additional environment details"* field below. + + **This form is only for officially supported Microsoft products**. + + *If your question is about a third-party or another library/SDK/tooling that is not officially supported by Microsoft, please submit your issue to that project's relevant forum.* + + **NOTE**:💥 If you select SharePoint Framework, you must include the following version numbers in the **Additional environment details** section below: 1️⃣ SharePoint Framework & 2️⃣ Node.js (`node -v`). + options: + - 💥 SharePoint Framework + - SharePoint Add-ins + - SharePoint CSOM + - SharePoint REST API + - Site designs & site scripts + - Declarative list formatting + - not applicable + - other (enter in the "Additional environment details" area below) + validations: + required: true + +- type: dropdown + attributes: + label: Developer environment + options: + - Windows + - macOS + - Linux + +- type: checkboxes + attributes: + label: What browser(s) / client(s) have you tested + description: | + Select the browser(s)/clients this submission is relevant to. + + **NOTE**:💥 If you select an item with this icon, you must include the version number of the selection in the **Additional environment details** section below. + options: + - label: 💥 Internet Explorer + - label: 💥 Microsoft Edge + - label: 💥 Google Chrome + - label: 💥 FireFox + - label: 💥 Safari + - label: mobile (iOS/iPadOS) + - label: mobile (Android) + - label: not applicable + - label: other (enter in the "Additional environment details" area below) + +- type: textarea + attributes: + label: Additional environment details + description: Include as much detail about the environment you're targetting. This is required if "other (enter below)" is selected in the previous field. + value: | + - browser version + - SPFx version + - Node.js version + - etc + +- type: markdown + attributes: + value: | + Provide a clear & concise description of what the bug is. Please follow our guidance on [How To Create Good Issues](https://github.com/sharepoint/sp-dev-docs/wiki/How-to-Create-Good-Issues) which explains how to apply formatting, adding references & resources, screenshots, etc. **Do not attach ZIP files** of your code or compiled projects - instead, please publish your code to a public GitHub repo & post a link to it. + +- type: textarea + attributes: + label: Describe the bug / error + validations: + required: true + +- type: textarea + attributes: + label: Steps to reproduce + description: How do you reproduce this? Please provide as much step-by-step detail as possible. + value: | + 1. + 2. + 3. + validations: + required: true + +- type: textarea + attributes: + label: Expected behavior + description: What did you expect to happen when the reproduce steps are followed? + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 000000000..419103265 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,11 @@ +blank_issues_enabled: true +contact_links: + - name: Feature Request / Change Request + url: https://aka.ms/sp-dev-uservoice + about: Feature requests should be submitted to the SharePoint Dev UserVoice site. + - name: SharePoint Developer Documentation + url: https://docs.microsoft.com/sharepoint/dev + about: All developer documentation for SharePoint can be found here. + - name: SharePoint TechCommunity + url: https://techcommunity.microsoft.com/t5/SharePoint/ct-p/SharePoint + about: Please submit non-developer questions/reports to the SharePoint TechCommunity site. This includes anything related to administrator, end-user, or user experience capabilities, questions, and errors. diff --git a/.github/ISSUE_TEMPLATE/question.yml b/.github/ISSUE_TEMPLATE/question.yml new file mode 100644 index 000000000..dbb8092af --- /dev/null +++ b/.github/ISSUE_TEMPLATE/question.yml @@ -0,0 +1,93 @@ +name: 🤔 Question or generic issue +description: Do you have a question? Or is it something else that doesn't fit one of the links below? Select this option! +labels: 'Needs: Triage' + +body: +- type: markdown + attributes: + value: | + This is for SharePoint development topics. If your submission is now about SharePoint development such as out-of-the-box capabilities, SharePoint configuration, please use refer to other support options listed on the [new issue chooser page](https://github.com/SharePoint/sp-dev-docs/issues/new/choose). Please provide as much information as possible so we can best address your submission. Thanks! + + - Follow our guidance on [How To Create Good Issues](https://github.com/sharepoint/sp-dev-docs/wiki/How-to-Create-Good-Issues). + - Remember to include sufficient details and context. + - If you have multiple questions, suggestions, or bugs, please submit them in separate issues. + + Please provide the following details about your environment. 🚨 *If this section is ignored, your submission will be flagged as **incomplete** & automatically closed.* + +- type: dropdown + attributes: + label: What type of issue is this? + options: + - Question + - Documentation issue / typo + - other + validations: + required: true + +- type: dropdown + attributes: + label: What SharePoint development model, framework, SDK or API is this about? + description: | + What tooling, frameworks, SDKs, or official libraries is this related to? Please include the version details in the *"Additional environment details"* field below. + + **This form is only for officially supported Microsoft products**. + + *If your question is about a third-party or another library/SDK/tooling that is not officially supported by Microsoft, please submit your issue to that project's relevant forum.* + + **NOTE**:💥 If you select SharePoint Framework, you must include the following version numbers in the **Additional environment details** section below: 1️⃣ SharePoint Framework & 2️⃣ Node.js (`node -v`). + options: + - 💥 SharePoint Framework + - SharePoint Add-ins + - SharePoint CSOM + - SharePoint REST API + - Site designs & site scripts + - Declarative list formatting + - not applicable + - other (enter in the "Additional environment details" area below) + validations: + required: true + +- type: dropdown + attributes: + label: Target SharePoint environment + options: + - SharePoint Online + - SharePoint Server 2019 (on-premise) + - SharePoint Server 2016 (on-premise) + - other (enter in the "Additional environment details" area below) + validations: + required: true + +- type: checkboxes + attributes: + label: What browser(s) / client(s) have you tested + description: | + Select the browser(s)/clients this submission is relevant to. + + **NOTE**:💥 If you select an item with this icon, you must include the version number of the selection in the **Additional environment details** section below. + options: + - label: 💥 Internet Explorer + - label: 💥 Microsoft Edge + - label: 💥 Google Chrome + - label: 💥 FireFox + - label: 💥 Safari + - label: mobile (iOS/iPadOS) + - label: mobile (Android) + - label: not applicable + - label: other (enter in the "Additional environment details" area below) + +- type: textarea + attributes: + label: Additional environment details + description: Include as much detail about the environment you're targetting. This is required if "other (enter below)" is selected in the previous field. + value: | + - browser version + - SPFx version + - Node.js version + - etc + +- type: textarea + attributes: + label: Issue description + validations: + required: true diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 145b1962e..99aeec9af 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,15 +1,30 @@ -| Q | A -| --------------- | --- -| content fix? | no - yes? -| New article? | no - yes? -| Related issues? | fixes #X, partially #Y, mentioned in #Z +## Category -#### What's in this Pull Request? +- [ ] Content fix +- [ ] New article +- [x] Example checked item (*delete this line*) -Please describe the changes in this PR. Sample description or details around bugs which are being fixed. +> **DELETE THIS LINE BEFORE SUBMITTING** | *For the above list, an empty checkbox is [ ] as in [SPACE]. A checked checkbox is [x] with no space between the brackets. Use the `PREVIEW` tab at the top right to preview the rendering before submitting your issue.* +## Related issues -#### Guidance -*You can delete this section when you are submitting the pull request.* -* *Please update this PR information accordingly. We'll use this as part of our release notes in monthly communications.* -* *Please target your PR to 'staging' branch.* \ No newline at end of file +- fixes #issuenumber +- partially #issuenumber +- mentioned in #issuenumber + +> **DELETE THIS LINE BEFORE SUBMITTING** | *If this fixes (aka: closes) or references an issue, please reference it here. This helps maintaining the issue list as it will (1) link the PR to the issue & (2) automatically close the issue when this PR is merged in.* + +## What's in this Pull Request? + +> **DELETE THIS LINE BEFORE SUBMITTING** | *Please describe the changes in this PR. Sample description or details around bugs which are being fixed.* + +## Submission guidelines + +> - **!!IMPORTANT!!** - All submissions must complete the baseline sections included in this template. Ignoring or deleting this template may result in closing the issue with the label **type:incomplete-submission**. +> - Follow our guidance on [How To Create Good Pull Requests](https://github.com/SharePoint/sp-dev-docs/wiki/How-to-Create-Good-Pull-Requests). +> - Target the `main` branch of this repo. +> - When changing a page, ensure you update the `ms.date` front matter wih the current date in the format `MM/DD/YYYY`. +> - Review all build checks and address the automated errors, warnings, and suggestions. +> - *NOTE: The live site is based on the `live` branch. Site owners periodically refresh `live` branch from the `main` branch so merged PRs won't immediately appear on the live site. Please be patient to see your changes appear on the live site.* +> +> **DELETE THIS SECTION BEFORE SUBMITTING** diff --git a/.github/fabricbot.json b/.github/fabricbot.json new file mode 100644 index 000000000..6dcaf2f39 --- /dev/null +++ b/.github/fabricbot.json @@ -0,0 +1,1149 @@ +{ + "version": "1.0", + "tasks": [ + { + "taskType": "trigger", + "capabilityId": "IssueResponder", + "subCapability": "IssueResponder", + "version": "1.0", + "config": { + "conditions": { + "operator": "and", + "operands": [ + { + "name": "isEvent", + "parameters": { + "eventName": "issues" + } + }, + { + "name": "isAction", + "parameters": { + "action": "opened" + } + }, + { + "operator": "not", + "operands": [ + { + "name": "isAssignedToSomeone", + "parameters": {} + } + ] + } + ] + }, + "taskName": "Auto-label incoming issues as Needs Triage", + "actions": [ + { + "name": "addReply", + "parameters": { + "comment": "Thank you for reporting this issue. We will be triaging your incoming issue as soon as possible." + } + }, + { + "name": "addLabels", + "parameters": { + "labels": [ + "Needs: Triage :mag:" + ] + } + } + ] + }, + "id": "DhSdUvTfU" + }, + { + "taskType": "trigger", + "capabilityId": "IssueResponder", + "subCapability": "IssueResponder", + "version": "1.0", + "config": { + "conditions": { + "operator": "and", + "operands": [ + { + "operator": "not", + "operands": [ + { + "name": "isActivitySender", + "parameters": { + "user": "msft-github-bot" + } + } + ] + }, + { + "operator": "not", + "operands": [ + { + "name": "isAction", + "parameters": { + "action": "closed" + } + } + ] + }, + { + "name": "hasLabel", + "parameters": { + "label": "no-recent-activity" + } + } + ] + }, + "taskName": "Remove no recent activity label", + "actions": [ + { + "name": "removeLabel", + "parameters": { + "label": "no-recent-activity" + } + } + ] + }, + "id": "EuTNKsOAX" + }, + { + "taskType": "trigger", + "capabilityId": "IssueResponder", + "subCapability": "IssueResponder", + "version": "1.0", + "config": { + "conditions": { + "operator": "and", + "operands": [ + { + "name": "isEvent", + "parameters": { + "eventName": "issue_comment" + } + }, + { + "name": "isIssue", + "parameters": {} + }, + { + "name": "isActivitySender", + "parameters": { + "user": { + "type": "author" + } + } + }, + { + "name": "hasLabel", + "parameters": { + "label": "Needs: Author Feedback" + } + } + ] + }, + "taskName": "Add needs attention label to issues", + "actions": [ + { + "name": "addLabels", + "parameters": { + "labels": [ + "Needs: Attention :wave:" + ] + } + } + ] + }, + "id": "4g_ssp7c7" + }, + { + "taskType": "trigger", + "capabilityId": "IssueResponder", + "subCapability": "IssueResponder", + "version": "1.0", + "config": { + "conditions": { + "operator": "and", + "operands": [ + { + "name": "isActivitySender", + "parameters": { + "user": { + "type": "author" + } + } + }, + { + "operator": "not", + "operands": [ + { + "name": "isAction", + "parameters": { + "action": "closed" + } + } + ] + }, + { + "name": "hasLabel", + "parameters": { + "label": "Needs: Author Feedback" + } + } + ] + }, + "taskName": "Remove needs author feedback label from issues and pull requests", + "actions": [ + { + "name": "removeLabel", + "parameters": { + "label": "Needs: Author Feedback" + } + } + ] + }, + "id": "LSpcATOkS" + }, + { + "taskType": "scheduled", + "capabilityId": "ScheduledSearch", + "subCapability": "ScheduledSearch", + "version": "1.1", + "id": "R2LaDi6Kz", + "config": { + "taskName": "Closed answered issues in 3 days", + "frequency": [ + { + "weekDay": 0, + "hours": [ + 0, + 1, + 2, + 3, + 4, + 5, + 6, + 7, + 8, + 9, + 10, + 11, + 12, + 13, + 14, + 15, + 16, + 17, + 18, + 19, + 20, + 21, + 22, + 23 + ] + }, + { + "weekDay": 1, + "hours": [ + 0, + 1, + 2, + 3, + 4, + 5, + 6, + 7, + 8, + 9, + 10, + 11, + 12, + 13, + 14, + 15, + 16, + 17, + 18, + 19, + 20, + 21, + 22, + 23 + ] + }, + { + "weekDay": 2, + "hours": [ + 0, + 1, + 2, + 3, + 4, + 5, + 6, + 7, + 8, + 9, + 10, + 11, + 12, + 13, + 14, + 15, + 16, + 17, + 18, + 19, + 20, + 21, + 22, + 23 + ] + }, + { + "weekDay": 3, + "hours": [ + 0, + 1, + 2, + 3, + 4, + 5, + 6, + 7, + 8, + 9, + 10, + 11, + 12, + 13, + 14, + 15, + 16, + 17, + 18, + 19, + 20, + 21, + 22, + 23 + ] + }, + { + "weekDay": 4, + "hours": [ + 0, + 1, + 2, + 3, + 4, + 5, + 6, + 7, + 8, + 9, + 10, + 11, + 12, + 13, + 14, + 15, + 16, + 17, + 18, + 19, + 20, + 21, + 22, + 23 + ] + }, + { + "weekDay": 5, + "hours": [ + 0, + 1, + 2, + 3, + 4, + 5, + 6, + 7, + 8, + 9, + 10, + 11, + 12, + 13, + 14, + 15, + 16, + 17, + 18, + 19, + 20, + 21, + 22, + 23 + ] + }, + { + "weekDay": 6, + "hours": [ + 0, + 1, + 2, + 3, + 4, + 5, + 6, + 7, + 8, + 9, + 10, + 11, + 12, + 13, + 14, + 15, + 16, + 17, + 18, + 19, + 20, + 21, + 22, + 23 + ] + } + ], + "searchTerms": [ + { + "name": "isIssue", + "parameters": {} + }, + { + "name": "isOpen", + "parameters": {} + }, + { + "name": "hasLabel", + "parameters": { + "label": "status:answered" + } + }, + { + "name": "noActivitySince", + "parameters": { + "days": 3 + } + } + ], + "actions": [ + { + "name": "addReply", + "parameters": { + "comment": "Closing this issue as \"answered\". If you encounter a similar issue(s), please open up a new issue. See our wiki for more details: [Issue-List: Our approach to closed issues](https://github.com/SharePoint/sp-dev-docs/wiki/Issue-List#our-approach-to-closed-issues)" + } + }, + { + "name": "closeIssue", + "parameters": {} + }, + { + "name": "lockIssue", + "parameters": { + "reason": "resolved" + } + } + ] + } + }, + { + "taskType": "scheduled", + "capabilityId": "ScheduledSearch", + "subCapability": "ScheduledSearch", + "version": "1.1", + "id": "ejaaeLe6G", + "config": { + "frequency": [ + { + "weekDay": 0, + "hours": [ + 1, + 5, + 9, + 13, + 17, + 21 + ], + "timezoneOffset": -5 + }, + { + "weekDay": 1, + "hours": [ + 1, + 5, + 9, + 13, + 17, + 21 + ], + "timezoneOffset": -5 + }, + { + "weekDay": 2, + "hours": [ + 1, + 5, + 9, + 13, + 17, + 21 + ], + "timezoneOffset": -5 + }, + { + "weekDay": 3, + "hours": [ + 1, + 5, + 9, + 13, + 17, + 21 + ], + "timezoneOffset": -5 + }, + { + "weekDay": 4, + "hours": [ + 1, + 5, + 9, + 13, + 17, + 21 + ], + "timezoneOffset": -5 + }, + { + "weekDay": 5, + "hours": [ + 1, + 5, + 9, + 13, + 17, + 21 + ], + "timezoneOffset": -5 + }, + { + "weekDay": 6, + "hours": [ + 1, + 5, + 9, + 13, + 17, + 21 + ], + "timezoneOffset": -5 + } + ], + "searchTerms": [ + { + "name": "isIssue", + "parameters": {} + }, + { + "name": "isOpen", + "parameters": {} + }, + { + "name": "hasLabel", + "parameters": { + "label": "Needs: Author Feedback" + } + }, + { + "name": "hasLabel", + "parameters": { + "label": "no-recent-activity" + } + }, + { + "name": "noActivitySince", + "parameters": { + "days": 7 + } + } + ], + "taskName": "Close stale issues", + "actions": [ + { + "name": "closeIssue", + "parameters": {} + }, + { + "name": "addReply", + "parameters": { + "comment": "Closing issue due to no response from the original author. Please refer to our wiki for more details, including how to remediate this action if you feel this was done prematurely or in error: [No response from the original issue author](https://github.com/SharePoint/sp-dev-docs/wiki/Issue-List#no-response-from-the-original-issue-author)" + } + }, + { + "name": "lockIssue", + "parameters": {} + } + ] + }, + "disabled": false + }, + { + "taskType": "trigger", + "capabilityId": "IssueResponder", + "subCapability": "IssuesOnlyResponder", + "version": "1.0", + "id": "JN4EianUp", + "config": { + "conditions": { + "operator": "or", + "operands": [ + { + "name": "labelAdded", + "parameters": { + "label": "type:invalid-not-dev-issue" + } + }, + { + "name": "labelAdded", + "parameters": { + "label": "type:invalid" + } + } + ] + }, + "eventType": "issue", + "eventNames": [ + "issues", + "project_card" + ], + "taskName": "Reply & close issues tagged \"type:invalid-not-dev-issue\"", + "actions": [ + { + "name": "addReply", + "parameters": { + "comment": "Thank you for your submission. As explained in our wiki ([Issue List: What doesn't belong in the issue list](https://github.com/SharePoint/sp-dev-docs/wiki/Issue-List#what-doesnt-belong-in-the-issue-list)), this issue list is for SharePoint developer/development issues. All capability question/discussion questions, or topics related to SharePoint administration & end-user topics should be reported through the support user interface available in the tenant admin settings. You can also have a discussion and ask questions at the [SharePoint TechCommunity](https://techcommunity.microsoft.com/t5/SharePoint/ct-p/SharePoint) forum. You can learn more about this in our wiki: [type:invalid-not-dev-issue](https://github.com/SharePoint/sp-dev-docs/wiki/Issue-List-Labels#typeinvalid-not-dev-issue)" + } + }, + { + "name": "closeIssue", + "parameters": {} + }, + { + "name": "lockIssue", + "parameters": { + "reason": "off-topic" + } + } + ] + } + }, + { + "taskType": "trigger", + "capabilityId": "IssueResponder", + "subCapability": "IssuesOnlyResponder", + "version": "1.0", + "id": "dTcNyMD5a", + "config": { + "conditions": { + "operator": "and", + "operands": [ + { + "name": "labelAdded", + "parameters": { + "label": "type:uservoice-request" + } + } + ] + }, + "eventType": "issue", + "eventNames": [ + "issues", + "project_card" + ], + "actions": [ + { + "name": "addReply", + "parameters": { + "comment": "Thank you for your submission. As explained in our wiki ([Issue List: What doesn't belong in the issue list](https://github.com/SharePoint/sp-dev-docs/wiki/Issue-List#what-doesnt-belong-in-the-issue-list)), all new feature requests and change requests to existing features should be posted to the [SP Dev UserVoice](https://aka.ms/sp-dev-uservoice) site. You can learn more about this in our wiki: [type:uservoice-request](https://github.com/SharePoint/sp-dev-docs/wiki/Issue-List-Labels#typeuservoice-request)" + } + }, + { + "name": "closeIssue", + "parameters": {} + } + ], + "taskName": "Reply & close issues tagged \"type:uservoice-request\"" + } + }, + { + "taskType": "trigger", + "capabilityId": "IssueResponder", + "subCapability": "IssuesOnlyResponder", + "version": "1.0", + "id": "TXAA0OOon", + "config": { + "conditions": { + "operator": "and", + "operands": [ + { + "name": "labelAdded", + "parameters": { + "label": "Needs: Context Detail :question:" + } + } + ] + }, + "eventType": "issue", + "eventNames": [ + "issues", + "project_card" + ], + "taskName": "Reply issues tagged \"Needs: Context Detail\"", + "actions": [ + { + "name": "addReply", + "parameters": { + "comment": "The more context details you can provide, the easier it is to help assist on issues. Any code you can provide and/or screenshots of the issue also help. The easier you can make it to reproduce the issue, the easier and quicker it is for someone to help you. Please refer to [How to Create Good Issues](https://github.com/SharePoint/sp-dev-docs/wiki/How-to-Create-Good-Issues), specifically [How to Create Good Issues: Include context](https://github.com/SharePoint/sp-dev-docs/wiki/How-to-Create-Good-Issues#include-context), in our wiki for more details." + } + }, + { + "name": "addLabel", + "parameters": { + "label": "Needs: Author Feedback" + } + } + ] + } + }, + { + "taskType": "trigger", + "capabilityId": "IssueResponder", + "subCapability": "IssuesOnlyResponder", + "version": "1.0", + "id": "vAHQpj0AT", + "config": { + "conditions": { + "operator": "and", + "operands": [ + { + "name": "labelAdded", + "parameters": { + "label": "status:duplicate" + } + } + ] + }, + "eventType": "issue", + "eventNames": [ + "issues", + "project_card" + ], + "taskName": "Close issues tagged \"status:duplicate\"", + "actions": [ + { + "name": "addReply", + "parameters": { + "comment": "Closing this issue as a dupe. Please refer to our wiki for more details: [Issue List Labels: status:duplicate](https://github.com/SharePoint/sp-dev-docs/wiki/Issue-List-Labels#statusduplicate)" + } + }, + { + "name": "closeIssue", + "parameters": {} + }, + { + "name": "lockIssue", + "parameters": { + "reason": "resolved" + } + } + ] + } + }, + { + "taskType": "scheduled", + "capabilityId": "ScheduledSearch", + "subCapability": "ScheduledSearch", + "version": "1.1", + "id": "Lzyb5Csy_", + "config": { + "frequency": [ + { + "weekDay": 0, + "hours": [ + 0, + 6, + 12, + 18 + ] + }, + { + "weekDay": 1, + "hours": [ + 0, + 6, + 12, + 18 + ] + }, + { + "weekDay": 2, + "hours": [ + 0, + 6, + 12, + 18 + ] + }, + { + "weekDay": 3, + "hours": [ + 0, + 6, + 12, + 18 + ] + }, + { + "weekDay": 4, + "hours": [ + 0, + 6, + 12, + 18 + ] + }, + { + "weekDay": 5, + "hours": [ + 0, + 6, + 12, + 18 + ] + }, + { + "weekDay": 6, + "hours": [ + 0, + 6, + 12, + 18 + ] + } + ], + "searchTerms": [ + { + "name": "isIssue", + "parameters": {} + }, + { + "name": "isClosed", + "parameters": {} + }, + { + "name": "noActivitySince", + "parameters": { + "days": 7 + } + }, + { + "name": "isUnlocked", + "parameters": {} + } + ], + "taskName": "Lock issues if inactive 7d after closing", + "actions": [ + { + "name": "addReply", + "parameters": { + "comment": "Issues that have been closed & had no follow-up activity for at least 7 days are automatically locked. Please refer to our wiki for more details, including how to remediate this action if you feel this was done prematurely or in error: [Issue List: Our approach to locked issues](https://github.com/SharePoint/sp-dev-docs/wiki/Issue-List#our-approach-to-locked-issues)" + } + }, + { + "name": "lockIssue", + "parameters": { + "reason": "resolved" + } + } + ] + } + }, + { + "taskType": "trigger", + "capabilityId": "IssueResponder", + "subCapability": "IssuesOnlyResponder", + "version": "1.0", + "id": "k84udcNf_", + "config": { + "conditions": { + "operator": "and", + "operands": [ + { + "name": "bodyContains", + "parameters": { + "bodyPattern": "Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking." + } + } + ] + }, + "eventType": "issue", + "eventNames": [ + "issues", + "project_card" + ], + "actions": [ + { + "name": "addLabel", + "parameters": { + "label": "area:docs-comment" + } + } + ], + "taskName": "Label new issues created as comment on docs with \"area:docs-comment\"" + } + }, + { + "taskType": "trigger", + "capabilityId": "IssueResponder", + "subCapability": "IssuesOnlyResponder", + "version": "1.0", + "id": "NbeJ2zWgh", + "config": { + "conditions": { + "operator": "and", + "operands": [ + { + "name": "labelAdded", + "parameters": { + "label": "type:incomplete-submission" + } + } + ] + }, + "eventType": "issue", + "eventNames": [ + "issues", + "project_card" + ], + "taskName": "Reply & tag issues tagged with type:incomplete-submission", + "actions": [ + { + "name": "addReply", + "parameters": { + "comment": "Thank you for your submission, but there isn't enough detail in the issue for us to review & move forward. The new issue template includes sections for you to fill out. Please resubmit your issue and complete the provided sections in the new item template so we can move forward on it refer to our wiki for more information: [How to Create Good Issues](https://github.com/SharePoint/sp-dev-docs/wiki/How-to-Create-Good-Issues)" + } + }, + { + "name": "removeLabel", + "parameters": { + "label": "Needs: Triage :mag:" + } + }, + { + "name": "closeIssue", + "parameters": {} + } + ] + } + }, + { + "taskType": "trigger", + "capabilityId": "IssueResponder", + "subCapability": "PullRequestResponder", + "version": "1.0", + "id": "SgmbtMnlk", + "config": { + "conditions": { + "operator": "and", + "operands": [ + { + "name": "labelAdded", + "parameters": { + "label": "type:incomplete-submission" + } + } + ] + }, + "eventType": "pull_request", + "eventNames": [ + "pull_request", + "issues", + "project_card" + ], + "taskName": "Reply & tag PRs tagged with type:incomplete-submission", + "actions": [ + { + "name": "addReply", + "parameters": { + "comment": "Thank you for your submission, but there isn't enough detail in the pull request for us to review & move forward. The new PR template includes sections for you to fill out. Please resubmit your PR and complete the provided sections in the new item template so we can move forward on it refer to our wiki for more information: [How to Create Good Pull Requests]https://github.com/SharePoint/sp-dev-docs/wiki/How-to-Create-Good-Pull-Requests)" + } + }, + { + "name": "closeIssue", + "parameters": {} + } + ] + } + }, + { + "taskType": "scheduled", + "capabilityId": "ScheduledSearch", + "subCapability": "ScheduledSearch", + "version": "1.1", + "id": "ECBdzA7w3Y7R-jcBx0icn", + "config": { + "frequency": [ + { + "weekDay": 0, + "hours": [ + 0, + 6, + 12, + 18 + ] + }, + { + "weekDay": 1, + "hours": [ + 0, + 6, + 12, + 18 + ] + }, + { + "weekDay": 2, + "hours": [ + 0, + 6, + 12, + 18 + ] + }, + { + "weekDay": 3, + "hours": [ + 0, + 6, + 12, + 18 + ] + }, + { + "weekDay": 4, + "hours": [ + 0, + 6, + 12, + 18 + ] + }, + { + "weekDay": 5, + "hours": [ + 0, + 6, + 12, + 18 + ] + }, + { + "weekDay": 6, + "hours": [ + 0, + 6, + 12, + 18 + ] + } + ], + "searchTerms": [ + { + "name": "isIssue", + "parameters": {} + }, + { + "name": "isOpen", + "parameters": {} + }, + { + "name": "hasLabel", + "parameters": { + "label": "Needs: Author Feedback" + } + }, + { + "name": "noActivitySince", + "parameters": { + "days": 7 + } + } + ], + "actions": [ + { + "name": "addLabel", + "parameters": { + "label": "no-recent-activity" + } + }, + { + "name": "addReply", + "parameters": { + "comment": "This issue has been automatically marked as stale because it has marked as requiring author feedback but has not had any activity for **7 days**. It will be closed if no further activity occurs **within the next 7 days of this comment**. Please see our wiki for more information: [Issue List Labels: Needs Author Feedback](https://github.com/SharePoint/sp-dev-docs/wiki/Issue-List-Labels#needs-author-feedback) & [Issue List: No response from the original issue author](https://github.com/SharePoint/sp-dev-docs/wiki/Issue-List#no-response-from-the-original-issue-author)" + } + } + ], + "taskName": "Mark issue with no-recent-activity label if there's no actions in 7 days" + } + }, + { + "taskType": "trigger", + "capabilityId": "IssueResponder", + "subCapability": "IssuesOnlyResponder", + "version": "1.0", + "id": "MdPj2K40N73yDGFnu9REz", + "config": { + "conditions": { + "operator": "and", + "operands": [ + { + "name": "labelAdded", + "parameters": { + "label": "listmaintenance-oldissues" + } + } + ] + }, + "eventType": "issue", + "eventNames": [ + "issues", + "project_card" + ], + "actions": [ + { + "name": "addReply", + "parameters": { + "comment": "This issue is being closed as part of an issue list cleanup project. Issues with no activity in the past 6 months that aren't tracked by engineering as bugs were closed as part of this inititive. If this is still an issue, please [follow the steps outlined to re-open or submit a new issue](https://github.com/sharepoint/sp-dev-docs/wiki/Issue-List#our-approach-to-closed-issues)." + } + }, + { + "name": "closeIssue", + "parameters": {} + } + ], + "taskName": "Close inactive issues based on list maintenance label" + } + } + ], + "userGroups": [] +} diff --git a/.github/label-actions.yml b/.github/label-actions.yml new file mode 100644 index 000000000..80a5bf7aa --- /dev/null +++ b/.github/label-actions.yml @@ -0,0 +1,14 @@ +# Configuration for Label Actions - https://github.com/dessant/label-actions + +# Actions taken when the `type:archive-old-issue` label is added to issues that are being archived. +type:archive-old-issue: + # Post a comment + comment: |+ + Thank you for taking the time to file an issue. We periodically **archive** older or inactive issues as part of our issue management process, which automatically closes them once they are archived. + + If you’d like to understand more about why and how we handle archived (closed) issues, please see [Our approach to closed issues](https://github.com/SharePoint/sp-dev-docs/wiki/Issue-List#our-approach-to-closed-issues). + + We appreciate your contribution and if this is still an active issue with the latest SPFx versions, please do resubmit the details. We needed to perform a cleanup, so that we can start with a **clean table** with a new process. We apologize for the inconvenience this might cause. + + # Close the issue + close: true diff --git a/.github/policies/resourceManagement.yml b/.github/policies/resourceManagement.yml new file mode 100644 index 000000000..43263aa44 --- /dev/null +++ b/.github/policies/resourceManagement.yml @@ -0,0 +1,115 @@ +id: bot-issue-management +name: Issue Management +description: Enable tracking & monitoring of issues +resource: repository +disabled: false +configuration: + resourceManagementConfiguration: + scheduledSearches: + - description: Close answered issues after 3 days of inactivity + frequencies: + - hourly: { hour: 0 } + filters: + - isIssue + - isOpen + - hasLabel: { label: status:answered } + - noActivitySince: { days: 3 } + actions: + - addReply: + reply: > + Closing this issue as "answered". If you encounter a similar issue(s), please open up a new issue. See our wiki for more details: [Issue-List: Our approach to closed issues](https://github.com/SharePoint/sp-dev-docs/wiki/Issue-List#our-approach-to-closed-issues) + - closeIssue + - lockIssue: + reason: resolved + + - description: Close stale issues with no recent author activity after 7 days + frequencies: + - hourly: { hour: 6 } + filters: + - isIssue + - isOpen + - hasLabel: { label: 'Needs: Author Feedback' } + - hasLabel: { label: no-recent-activity } + - noActivitySince: { days: 7 } + actions: + - addReply: + reply: > + Closing issue due to no response from the original author. Please refer to our wiki for more details, including how to remediate this action if you feel this was done prematurely or in error: [No response from the original issue author](https://github.com/SharePoint/sp-dev-docs/wiki/Issue-List#no-response-from-the-original-issue-author) + - closeIssue + - lockIssue + + - description: Mark issues as no recent activity after 7 days + frequencies: + - hourly: { hour: 6 } + filters: + - isIssue + - isOpen + - hasLabel: { label: 'Needs: Author Feedback' } + - noActivitySince: { days: 7 } + actions: + - addLabel: { label: no-recent-activity } + - addReply: + reply: > + This issue has been automatically marked as stale because it has marked as requiring author feedback but has not had any activity for **7 days**. It will be closed if no further activity occurs **within the next 7 days of this comment**. Please see our wiki for more information: [Issue List Labels: Needs Author Feedback](https://github.com/SharePoint/sp-dev-docs/wiki/Issue-List-Labels#needs-author-feedback) & [Issue List: No response from the original issue author](https://github.com/SharePoint/sp-dev-docs/wiki/Issue-List#no-response-from-the-original-issue-author) + + - description: Lock issues inactive 7 days after closing + frequencies: + - hourly: { hour: 6 } + filters: + - isIssue + - isClosed + - noActivitySince: { days: 7 } + - isUnlocked + actions: + - addReply: + reply: > + Issues that have been closed & had no follow-up activity for at least 7 days are automatically locked. Please refer to our wiki for more details, including how to remediate this action if you feel this was done prematurely or in error: [Issue List: Our approach to locked issues](https://github.com/SharePoint/sp-dev-docs/wiki/Issue-List#our-approach-to-locked-issues) + - lockIssue: + reason: resolved + + eventResponderTasks: + - if: + - payloadType: Issues + - isAction: { action: opened } + - not: + isAssignedToSomeone: true + then: + - addReply: + reply: > + Thank you for reporting this issue. We will be triaging your incoming issue as soon as possible. + - addLabel: + label: 'Needs: Triage :mag:' + + - if: + - payloadType: Issue_Comment + - isActivitySender: { issueAuthor: true } + - hasLabel: { label: 'Needs: Author Feedback' } + - isOpen + then: + - addLabel: + label: 'Needs: Attention :wave:' + + - if: + - payloadType: Issues + - isActivitySender: { issueAuthor: true } + - not: + isAction: { action: closed } + - hasLabel: { label: 'Needs: Author Feedback' } + then: + - removeLabel: { label: 'Needs: Author Feedback' } + + - if: + - payloadType: Issues + - not: + isActivitySender: { user: microsoft-github-policy-service } + - not: + isAction: { action: closed } + - hasLabel: { label: no-recent-activity } + then: + - removeLabel: { label: no-recent-activity } + + - if: + - payloadType: Issue_Comment + - hasLabel: { label: no-recent-activity } + then: + - removeLabel: { label: no-recent-activity } diff --git a/.github/workflows/label-actions.yml b/.github/workflows/label-actions.yml new file mode 100644 index 000000000..d2dd0ff59 --- /dev/null +++ b/.github/workflows/label-actions.yml @@ -0,0 +1,18 @@ +name: 'Check for Incomplete Issues' + +on: + issues: + types: [labeled, unlabeled] + +permissions: + issues: write + pull-requests: write + +jobs: + reaction: + runs-on: ubuntu-latest + steps: + - uses: dessant/label-actions@v2 + with: + github-token: ${{ github.token }} + process-only: 'issues' diff --git a/.gitignore b/.gitignore new file mode 100644 index 000000000..6175acdd4 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +.Ds_Store diff --git a/.openpublishing.publish.config.json b/.openpublishing.publish.config.json new file mode 100644 index 000000000..f3522487f --- /dev/null +++ b/.openpublishing.publish.config.json @@ -0,0 +1,83 @@ +{ + "docsets_to_publish": [ + { + "docset_name": "sharepoint-dev", + "build_source_folder": "docs", + "build_output_subfolder": "sharepoint-dev", + "locale": "en-us", + "monikers": [], + "moniker_ranges": [], + "open_to_public_contributors": true, + "type_mapping": { + "Conceptual": "Content", + "ManagedReference": "Content", + "RestApi": "Content" + }, + "build_entry_point": "docs", + "template_folder": "_themes", + "customized_tasks": { + "docset_prebuild": [ + "_dependentPackages/CommonPlugins/tools/JoinTOC.ps1" + ] + } + } + ], + "notification_subscribers": [ + "vesaj@microsoft.com", + "bjansen@microsoft.com" + ], + "sync_notification_subscribers": null, + "branches_to_filter": [], + "git_repository_url_open_to_public_contributors": "https://github.com/SharePoint/sp-dev-docs", + "git_repository_branch_open_to_public_contributors": "main", + "skip_source_output_uploading": false, + "need_preview_pull_request": true, + "contribution_branch_mappings": {}, + "dependent_repositories": [ + { + "path_to_root": "_themes", + "url": "https://github.com/Microsoft/templates.docs.msft", + "branch": "main", + "branch_mapping": {} + }, + { + "path_to_root": "_themes.pdf", + "url": "https://github.com/Microsoft/templates.docs.msft.pdf", + "branch": "main", + "branch_mapping": {} + }, + { + "path_to_root": "sp-dev-modernization", + "url": "https://github.com/SharePoint/sp-dev-modernization.git", + "branch": "dev", + "branch_mapping": {} + } + ], + "branch_target_mapping": { + "live": [ + "Publish", + "Pdf" + ] + }, + "need_generate_pdf_url_template": true, + "Targets": { + "Pdf": { + "template_folder": "_themes.pdf" + } + }, + "JoinTOCPlugin": [ + { + "ConceptualTOC": "/docs/toc.yml", + "ReferenceTOCUrl": "/javascript/api/spfx-toc/toc.json" + } + ], + "dependent_packages": [ + { + "path_to_root": "_dependentPackages/CommonPlugins", + "target_framework": "net45", + "version": "latest", + "id": "Microsoft.OpenPublishing.CommonPlugins", + "nuget_feed": "https://www.myget.org/F/op/api/v2" + } + ] +} diff --git a/.openpublishing.redirection.json b/.openpublishing.redirection.json new file mode 100644 index 000000000..78222f726 --- /dev/null +++ b/.openpublishing.redirection.json @@ -0,0 +1,274 @@ +{ + "redirections": [ + { + "source_path": "docs/apis/rest/complete-basic-operations-using-sharepoint-rest-endpoints.md", + "redirect_url": "/sharepoint/dev/sp-add-ins/complete-basic-operations-using-sharepoint-rest-endpoints", + "redirect_document_id": false + }, + { + "source_path": "docs/apis/rest/determine-sharepoint-rest-service-endpoint-uris.md", + "redirect_url": "/sharepoint/dev/sp-add-ins/determine-sharepoint-rest-service-endpoint-uris", + "redirect_document_id": false + }, + { + "source_path": "docs/apis/rest/get-to-know-the-sharepoint-rest-service.md", + "redirect_url": "/sharepoint/dev/sp-add-ins/get-to-know-the-sharepoint-rest-service", + "redirect_document_id": false + }, + { + "source_path": "docs/apis/rest/make-batch-requests-with-the-rest-apis.md", + "redirect_url": "/sharepoint/dev/sp-add-ins/make-batch-requests-with-the-rest-apis", + "redirect_document_id": false + }, + { + "source_path": "docs/apis/rest/navigate-the-sharepoint-data-structure-represented-in-the-rest-service.md", + "redirect_url": "/sharepoint/dev/sp-add-ins/navigate-the-sharepoint-data-structure-represented-in-the-rest-service", + "redirect_document_id": false + }, + { + "source_path": "docs/apis/rest/set-custom-permissions-on-a-list-by-using-the-rest-interface.md", + "redirect_url": "/sharepoint/dev/sp-add-ins/set-custom-permissions-on-a-list-by-using-the-rest-interface", + "redirect_document_id": false + }, + { + "source_path": "docs/apis/rest/synchronize-sharepoint-items-using-the-rest-service.md", + "redirect_url": "/sharepoint/dev/sp-add-ins/synchronize-sharepoint-items-using-the-rest-service", + "redirect_document_id": false + }, + { + "source_path": "docs/apis/rest/upload-a-file-by-using-the-rest-api-and-jquery.md", + "redirect_url": "/sharepoint/dev/sp-add-ins/upload-a-file-by-using-the-rest-api-and-jquery", + "redirect_document_id": false + }, + { + "source_path": "docs/apis/rest/use-odata-query-operations-in-sharepoint-rest-requests.md", + "redirect_url": "/sharepoint/dev/sp-add-ins/use-odata-query-operations-in-sharepoint-rest-requests", + "redirect_document_id": false + }, + { + "source_path": "docs/apis/rest/working-with-folders-and-files-with-rest.md", + "redirect_url": "/sharepoint/dev/sp-add-ins/working-with-folders-and-files-with-rest", + "redirect_document_id": false + }, + { + "source_path": "docs/apis/rest/working-with-lists-and-list-items-with-rest.md", + "redirect_url": "/sharepoint/dev/sp-add-ins/working-with-lists-and-list-items-with-rest", + "redirect_document_id": false + }, + { + "source_path": "docs/schema/index.md", + "redirect_url": "/sharepoint/dev/schema/upgrade-definition-schema", + "redirect_document_id": false + }, + { + "source_path": "docs/sp-add-ins/add-a-custom-content-type-to-a-sharepoint-hostedsharepoint-add-in.md", + "redirect_url": "/sharepoint/dev/sp-add-ins/add-a-custom-content-type-to-a-sharepoint-hosted-sharepoint-add-in", + "redirect_document_id": false + }, + { + "source_path": "docs/sp-add-ins/add-custom-columns-to-a-sharepoint-hostedsharepoint-add-in.md", + "redirect_url": "/sharepoint/dev/sp-add-ins/add-custom-columns-to-a-sharepoint-hosted-sharepoint-add-in", + "redirect_document_id": false + }, + { + "source_path": "docs/spfx/web-parts/guidance/creating-team-manifest-manually-for-webpart.md", + "redirect_url": "/sharepoint/dev/spfx/deployment-spfx-teams-solutions", + "redirect_document_id": false + }, + { + "source_path": "docs/general-development/office-365-cdn.md", + "redirect_url": "/sharepoint/dev/office365/enterprise/use-office-365-cdn-with-spo", + "redirect_document_id": false + }, + { + "source_path": "docs/spfx/toolchain/scaffolding-projects-using-yeoman-sharepoint-generator.md", + "redirect_url": "/sharepoint/dev/spfx/yeoman-generator-for-spfx-intro", + "redirect_document_id": false + }, + { + "source_path": "docs/spfx/office-addins-create.md", + "redirect_url": "/sharepoint/dev/spfx/release-1.14", + "redirect_document_id": false + }, + { + "source_path": "docs/spfx/web-parts/get-started/office-addins-tutorial.md", + "redirect_url": "/sharepoint/dev/spfx/release-1.14", + "redirect_document_id": false + }, + { + "source_path": "docs/spfx/sharepoint-2019-support.md", + "redirect_url": "/sharepoint/dev/spfx/sharepoint-2019-and-subscription-edition-support", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/mslearn/m01-01-intro.md", + "redirect_url": "/training/modules/sharepoint-embedded-setup/", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/mslearn/m02-01-intro.md", + "redirect_url": "/training/modules/sharepoint-embedded-create-app/", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/adoptions-and-use.md", + "redirect_url": "/sharepoint/dev/embedded/scenarios-and-use-cases", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/concepts/admin-exp/billing.md", + "redirect_url": "/sharepoint/dev/embedded/concepts/admin-exp/billing/billing", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/concepts/admin-exp/cta.md", + "redirect_url": "/sharepoint/dev/embedded/concepts/admin-exp/consuming-tenant-admin/cta", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/concepts/admin-exp/dev-admin.md", + "redirect_url": "/sharepoint/dev/embedded/concepts/admin-exp/developer-admin/dev-admin", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/concepts/app-concepts/terms-and-def.md", + "redirect_url": "/sharepoint/dev/embedded/overview", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/getting-started/enable-sharepoint-embedded.md", + "redirect_url": "/sharepoint/dev/embedded/overview", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/terms-of-service.md", + "redirect_url": "/sharepoint/dev/embedded/overview", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/concepts/admin-exp/adminrole.md", + "redirect_url": "/sharepoint/dev/embedded/administration/adminrole", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/concepts/admin-exp/billing/billing.md", + "redirect_url": "/sharepoint/dev/embedded/administration/billing/billing", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/concepts/admin-exp/billing/billingmanagement.md", + "redirect_url": "/sharepoint/dev/embedded/administration/billing/billingmanagement", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/concepts/admin-exp/billing/meters.md", + "redirect_url": "/sharepoint/dev/embedded/administration/billing/meters", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/concepts/admin-exp/consuming-tenant-admin/cta.md", + "redirect_url": "/sharepoint/dev/embedded/administration/consuming-tenant-admin/cta", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/concepts/admin-exp/consuming-tenant-admin/ctaUX.md", + "redirect_url": "/sharepoint/dev/embedded/administration/consuming-tenant-admin/ctaUX", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/concepts/admin-exp/consuming-tenant-admin/ctapowershell.md ", + "redirect_url": "/sharepoint/dev/embedded/administration/consuming-tenant-admin/ctapowershell", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/concepts/admin-exp/developer-admin/dev-admin.md", + "redirect_url": "/sharepoint/dev/embedded/administration/developer-admin/dev-admin", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/concepts/security-and-compliance.md", + "redirect_url": "/sharepoint/dev/embedded/compliance/security-and-compliance", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/concepts/app-concepts/app-architecture.md", + "redirect_url": "/sharepoint/dev/embedded/development/app-architecture", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/concepts/app-concepts/auth.md", + "redirect_url": "/sharepoint/dev/embedded/development/auth", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/concepts/content-experiences/office-experience.md", + "redirect_url": "/sharepoint/dev/embedded/development/content-experiences/office-experience", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/concepts/content-experiences/search-content.md", + "redirect_url": "/sharepoint/dev/embedded/development/content-experiences/search-content", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/concepts/content-experiences/user-experiences-overview.md", + "redirect_url": "/sharepoint/dev/embedded/development/content-experiences/user-experiences-overview", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/concepts/fluid.md", + "redirect_url": "/sharepoint/dev/embedded/development/fluid", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/concepts/app-concepts/limits-calling.md", + "redirect_url": "/sharepoint/dev/embedded/development/limits-calling", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/concepts/app-concepts/sharing-and-perm.md", + "redirect_url": "/sharepoint/dev/embedded/development/sharing-and-perm", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/tutorials/doc-processing-acs.md", + "redirect_url": "/sharepoint/dev/embedded/development/tutorials/doc-processing-acs", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/tutorials/launch-experience.md", + "redirect_url": "/sharepoint/dev/embedded/development/tutorials/launch-experience", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/tutorials/metadata.md", + "redirect_url": "/sharepoint/dev/embedded/development/tutorials/metadata", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/tutorials/migrate-abs-to-spe.md", + "redirect_url": "/sharepoint/dev/embedded/development/tutorials/migrate-abs-to-spe", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/tutorials/using-file-preview.md", + "redirect_url": "/sharepoint/dev/embedded/development/tutorials/using-file-preview", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/tutorials/using-webhooks.md", + "redirect_url": "/sharepoint/dev/embedded/development/tutorials/using-webhooks", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/concepts/app-concepts/containertypes.md", + "redirect_url": "/sharepoint/dev/embedded/getting-started/containertypes", + "redirect_document_id": false + }, + { + "source_path": "docs/embedded/concepts/app-concepts/register-api-documentation.md", + "redirect_url": "/sharepoint/dev/embedded/getting-started/register-api-documentation", + "redirect_document_id": false + } + ] +} diff --git a/.vs/ProjectSettings.json b/.vs/ProjectSettings.json new file mode 100644 index 000000000..f8b488856 --- /dev/null +++ b/.vs/ProjectSettings.json @@ -0,0 +1,3 @@ +{ + "CurrentProjectSetting": null +} \ No newline at end of file diff --git a/.vs/VSWorkspaceState.json b/.vs/VSWorkspaceState.json new file mode 100644 index 000000000..6b6114114 --- /dev/null +++ b/.vs/VSWorkspaceState.json @@ -0,0 +1,6 @@ +{ + "ExpandedNodes": [ + "" + ], + "PreviewInSolutionExplorer": false +} \ No newline at end of file diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 000000000..ed9462b7e --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,8 @@ +{ + "markdownlint.config": { + "MD028": false, + "MD025": { + "front_matter_title": "" + } + } +} \ No newline at end of file diff --git a/LICENSE b/LICENSE new file mode 100644 index 000000000..e056e7c3e --- /dev/null +++ b/LICENSE @@ -0,0 +1,395 @@ +Attribution 4.0 International + +======================================================================= + +Creative Commons Corporation ("Creative Commons") is not a law firm and +does not provide legal services or legal advice. Distribution of +Creative Commons public licenses does not create a lawyer-client or +other relationship. Creative Commons makes its licenses and related +information available on an "as-is" basis. Creative Commons gives no +warranties regarding its licenses, any material licensed under their +terms and conditions, or any related information. Creative Commons +disclaims all liability for damages resulting from their use to the +fullest extent possible. + +Using Creative Commons Public Licenses + +Creative Commons public licenses provide a standard set of terms and +conditions that creators and other rights holders may use to share +original works of authorship and other material subject to copyright +and certain other rights specified in the public license below. The +following considerations are for informational purposes only, are not +exhaustive, and do not form part of our licenses. + + Considerations for licensors: Our public licenses are + intended for use by those authorized to give the public + permission to use material in ways otherwise restricted by + copyright and certain other rights. Our licenses are + irrevocable. Licensors should read and understand the terms + and conditions of the license they choose before applying it. + Licensors should also secure all rights necessary before + applying our licenses so that the public can reuse the + material as expected. Licensors should clearly mark any + material not subject to the license. This includes other CC- + licensed material, or material used under an exception or + limitation to copyright. More considerations for licensors: + wiki.creativecommons.org/Considerations_for_licensors + + Considerations for the public: By using one of our public + licenses, a licensor grants the public permission to use the + licensed material under specified terms and conditions. If + the licensor's permission is not necessary for any reason--for + example, because of any applicable exception or limitation to + copyright--then that use is not regulated by the license. Our + licenses grant only permissions under copyright and certain + other rights that a licensor has authority to grant. Use of + the licensed material may still be restricted for other + reasons, including because others have copyright or other + rights in the material. A licensor may make special requests, + such as asking that all changes be marked or described. + Although not required by our licenses, you are encouraged to + respect those requests where reasonable. More_considerations + for the public: + wiki.creativecommons.org/Considerations_for_licensees + +======================================================================= + +Creative Commons Attribution 4.0 International Public License + +By exercising the Licensed Rights (defined below), You accept and agree +to be bound by the terms and conditions of this Creative Commons +Attribution 4.0 International Public License ("Public License"). To the +extent this Public License may be interpreted as a contract, You are +granted the Licensed Rights in consideration of Your acceptance of +these terms and conditions, and the Licensor grants You such rights in +consideration of benefits the Licensor receives from making the +Licensed Material available under these terms and conditions. + + +Section 1 -- Definitions. + + a. Adapted Material means material subject to Copyright and Similar + Rights that is derived from or based upon the Licensed Material + and in which the Licensed Material is translated, altered, + arranged, transformed, or otherwise modified in a manner requiring + permission under the Copyright and Similar Rights held by the + Licensor. For purposes of this Public License, where the Licensed + Material is a musical work, performance, or sound recording, + Adapted Material is always produced where the Licensed Material is + synched in timed relation with a moving image. + + b. Adapter's License means the license You apply to Your Copyright + and Similar Rights in Your contributions to Adapted Material in + accordance with the terms and conditions of this Public License. + + c. Copyright and Similar Rights means copyright and/or similar rights + closely related to copyright including, without limitation, + performance, broadcast, sound recording, and Sui Generis Database + Rights, without regard to how the rights are labeled or + categorized. For purposes of this Public License, the rights + specified in Section 2(b)(1)-(2) are not Copyright and Similar + Rights. + + d. Effective Technological Measures means those measures that, in the + absence of proper authority, may not be circumvented under laws + fulfilling obligations under Article 11 of the WIPO Copyright + Treaty adopted on December 20, 1996, and/or similar international + agreements. + + e. Exceptions and Limitations means fair use, fair dealing, and/or + any other exception or limitation to Copyright and Similar Rights + that applies to Your use of the Licensed Material. + + f. Licensed Material means the artistic or literary work, database, + or other material to which the Licensor applied this Public + License. + + g. Licensed Rights means the rights granted to You subject to the + terms and conditions of this Public License, which are limited to + all Copyright and Similar Rights that apply to Your use of the + Licensed Material and that the Licensor has authority to license. + + h. Licensor means the individual(s) or entity(ies) granting rights + under this Public License. + + i. Share means to provide material to the public by any means or + process that requires permission under the Licensed Rights, such + as reproduction, public display, public performance, distribution, + dissemination, communication, or importation, and to make material + available to the public including in ways that members of the + public may access the material from a place and at a time + individually chosen by them. + + j. Sui Generis Database Rights means rights other than copyright + resulting from Directive 96/9/EC of the European Parliament and of + the Council of 11 March 1996 on the legal protection of databases, + as amended and/or succeeded, as well as other essentially + equivalent rights anywhere in the world. + + k. You means the individual or entity exercising the Licensed Rights + under this Public License. Your has a corresponding meaning. + + +Section 2 -- Scope. + + a. License grant. + + 1. Subject to the terms and conditions of this Public License, + the Licensor hereby grants You a worldwide, royalty-free, + non-sublicensable, non-exclusive, irrevocable license to + exercise the Licensed Rights in the Licensed Material to: + + a. reproduce and Share the Licensed Material, in whole or + in part; and + + b. produce, reproduce, and Share Adapted Material. + + 2. Exceptions and Limitations. For the avoidance of doubt, where + Exceptions and Limitations apply to Your use, this Public + License does not apply, and You do not need to comply with + its terms and conditions. + + 3. Term. The term of this Public License is specified in Section + 6(a). + + 4. Media and formats; technical modifications allowed. The + Licensor authorizes You to exercise the Licensed Rights in + all media and formats whether now known or hereafter created, + and to make technical modifications necessary to do so. The + Licensor waives and/or agrees not to assert any right or + authority to forbid You from making technical modifications + necessary to exercise the Licensed Rights, including + technical modifications necessary to circumvent Effective + Technological Measures. For purposes of this Public License, + simply making modifications authorized by this Section 2(a) + (4) never produces Adapted Material. + + 5. Downstream recipients. + + a. Offer from the Licensor -- Licensed Material. Every + recipient of the Licensed Material automatically + receives an offer from the Licensor to exercise the + Licensed Rights under the terms and conditions of this + Public License. + + b. No downstream restrictions. You may not offer or impose + any additional or different terms or conditions on, or + apply any Effective Technological Measures to, the + Licensed Material if doing so restricts exercise of the + Licensed Rights by any recipient of the Licensed + Material. + + 6. No endorsement. Nothing in this Public License constitutes or + may be construed as permission to assert or imply that You + are, or that Your use of the Licensed Material is, connected + with, or sponsored, endorsed, or granted official status by, + the Licensor or others designated to receive attribution as + provided in Section 3(a)(1)(A)(i). + + b. Other rights. + + 1. Moral rights, such as the right of integrity, are not + licensed under this Public License, nor are publicity, + privacy, and/or other similar personality rights; however, to + the extent possible, the Licensor waives and/or agrees not to + assert any such rights held by the Licensor to the limited + extent necessary to allow You to exercise the Licensed + Rights, but not otherwise. + + 2. Patent and trademark rights are not licensed under this + Public License. + + 3. To the extent possible, the Licensor waives any right to + collect royalties from You for the exercise of the Licensed + Rights, whether directly or through a collecting society + under any voluntary or waivable statutory or compulsory + licensing scheme. In all other cases the Licensor expressly + reserves any right to collect such royalties. + + +Section 3 -- License Conditions. + +Your exercise of the Licensed Rights is expressly made subject to the +following conditions. + + a. Attribution. + + 1. If You Share the Licensed Material (including in modified + form), You must: + + a. retain the following if it is supplied by the Licensor + with the Licensed Material: + + i. identification of the creator(s) of the Licensed + Material and any others designated to receive + attribution, in any reasonable manner requested by + the Licensor (including by pseudonym if + designated); + + ii. a copyright notice; + + iii. a notice that refers to this Public License; + + iv. a notice that refers to the disclaimer of + warranties; + + v. a URI or hyperlink to the Licensed Material to the + extent reasonably practicable; + + b. indicate if You modified the Licensed Material and + retain an indication of any previous modifications; and + + c. indicate the Licensed Material is licensed under this + Public License, and include the text of, or the URI or + hyperlink to, this Public License. + + 2. You may satisfy the conditions in Section 3(a)(1) in any + reasonable manner based on the medium, means, and context in + which You Share the Licensed Material. For example, it may be + reasonable to satisfy the conditions by providing a URI or + hyperlink to a resource that includes the required + information. + + 3. If requested by the Licensor, You must remove any of the + information required by Section 3(a)(1)(A) to the extent + reasonably practicable. + + 4. If You Share Adapted Material You produce, the Adapter's + License You apply must not prevent recipients of the Adapted + Material from complying with this Public License. + + +Section 4 -- Sui Generis Database Rights. + +Where the Licensed Rights include Sui Generis Database Rights that +apply to Your use of the Licensed Material: + + a. for the avoidance of doubt, Section 2(a)(1) grants You the right + to extract, reuse, reproduce, and Share all or a substantial + portion of the contents of the database; + + b. if You include all or a substantial portion of the database + contents in a database in which You have Sui Generis Database + Rights, then the database in which You have Sui Generis Database + Rights (but not its individual contents) is Adapted Material; and + + c. You must comply with the conditions in Section 3(a) if You Share + all or a substantial portion of the contents of the database. + +For the avoidance of doubt, this Section 4 supplements and does not +replace Your obligations under this Public License where the Licensed +Rights include other Copyright and Similar Rights. + + +Section 5 -- Disclaimer of Warranties and Limitation of Liability. + + a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE + EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS + AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF + ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, + IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, + WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR + PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, + ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT + KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT + ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. + + b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE + TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, + NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, + INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, + COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR + USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN + ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR + DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR + IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. + + c. The disclaimer of warranties and limitation of liability provided + above shall be interpreted in a manner that, to the extent + possible, most closely approximates an absolute disclaimer and + waiver of all liability. + + +Section 6 -- Term and Termination. + + a. This Public License applies for the term of the Copyright and + Similar Rights licensed here. However, if You fail to comply with + this Public License, then Your rights under this Public License + terminate automatically. + + b. Where Your right to use the Licensed Material has terminated under + Section 6(a), it reinstates: + + 1. automatically as of the date the violation is cured, provided + it is cured within 30 days of Your discovery of the + violation; or + + 2. upon express reinstatement by the Licensor. + + For the avoidance of doubt, this Section 6(b) does not affect any + right the Licensor may have to seek remedies for Your violations + of this Public License. + + c. For the avoidance of doubt, the Licensor may also offer the + Licensed Material under separate terms or conditions or stop + distributing the Licensed Material at any time; however, doing so + will not terminate this Public License. + + d. Sections 1, 5, 6, 7, and 8 survive termination of this Public + License. + + +Section 7 -- Other Terms and Conditions. + + a. The Licensor shall not be bound by any additional or different + terms or conditions communicated by You unless expressly agreed. + + b. Any arrangements, understandings, or agreements regarding the + Licensed Material not stated herein are separate from and + independent of the terms and conditions of this Public License. + + +Section 8 -- Interpretation. + + a. For the avoidance of doubt, this Public License does not, and + shall not be interpreted to, reduce, limit, restrict, or impose + conditions on any use of the Licensed Material that could lawfully + be made without permission under this Public License. + + b. To the extent possible, if any provision of this Public License is + deemed unenforceable, it shall be automatically reformed to the + minimum extent necessary to make it enforceable. If the provision + cannot be reformed, it shall be severed from this Public License + without affecting the enforceability of the remaining terms and + conditions. + + c. No term or condition of this Public License will be waived and no + failure to comply consented to unless expressly agreed to by the + Licensor. + + d. Nothing in this Public License constitutes or may be interpreted + as a limitation upon, or waiver of, any privileges and immunities + that apply to the Licensor or You, including from the legal + processes of any jurisdiction or authority. + + +======================================================================= + +Creative Commons is not a party to its public +licenses. Notwithstanding, Creative Commons may elect to apply one of +its public licenses to material it publishes and in those instances +will be considered the “Licensor.” The text of the Creative Commons +public licenses is dedicated to the public domain under the CC0 Public +Domain Dedication. Except for the limited purpose of indicating that +material is shared under a Creative Commons public license or as +otherwise permitted by the Creative Commons policies published at +creativecommons.org/policies, Creative Commons does not authorize the +use of the trademark "Creative Commons" or any other trademark or logo +of Creative Commons without its prior written consent including, +without limitation, in connection with any unauthorized modifications +to any of its public licenses or any other arrangements, +understandings, or agreements concerning use of licensed material. For +the avoidance of doubt, this paragraph does not form part of the +public licenses. + +Creative Commons may be contacted at creativecommons.org. \ No newline at end of file diff --git a/LICENSE-CODE b/LICENSE-CODE new file mode 100644 index 000000000..b17b032a4 --- /dev/null +++ b/LICENSE-CODE @@ -0,0 +1,17 @@ +The MIT License (MIT) +Copyright (c) Microsoft Corporation + +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and +associated documentation files (the "Software"), to deal in the Software without restriction, +including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, +and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, +subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all copies or substantial +portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT +NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. \ No newline at end of file diff --git a/LICENSE.md b/LICENSE.md index d5b4108b7..cc73ce409 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -4,6 +4,6 @@ Copyright (c) Microsoft Corporation. Distributed under the following terms: 1. Microsoft and any contributors to this project each grants you a license, under its respective copyrights, to the Microsoft SharePoint Documentation under the [Creative Commons Attribution-NonCommercial-NoDerivs 3.0 United States License](https://creativecommons.org/licenses/by-nc-nd/3.0/us/legalcode). In addition, with respect to any sample code contained in the documentation, Microsoft and any such contributors grants you an additional license, under its respective intellectual property rights, to use the code to develop or design your software for Microsoft SharePoint and/or Office 365. -2. Microsoft, Microsoft Office, Microsoft SharePoint, Office 365, Windows, Windows Azure and/or other Microsoft products and services referenced in the documentation may be either trademarks or registered trademarks of Microsoft in the United States and/or other countries. This license does not grant you rights to use any names, logos, or trademarks. For Microsoft’s general trademark guidelines, go to [1](http://go.microsoft.com/fwlink/?LinkID=254653). +2. Microsoft, Microsoft Office, Microsoft SharePoint, Office 365, Windows, Windows Azure and/or other Microsoft products and services referenced in the documentation may be either trademarks or registered trademarks of Microsoft in the United States and/or other countries. This license does not grant you rights to use any names, logos, or trademarks. For Microsoft’s general trademark guidelines, go to [1](https://go.microsoft.com/fwlink/?LinkID=254653). 3. Microsoft and any contributors reserves all others rights, whether under copyrights, patents, or trademarks, or by implication, estoppel or otherwise. diff --git a/Microsoft Sharepoint Framework Preview EULA.DOCX b/Microsoft Sharepoint Framework Preview EULA.DOCX deleted file mode 100644 index f6f04741f..000000000 Binary files a/Microsoft Sharepoint Framework Preview EULA.DOCX and /dev/null differ diff --git a/README.md b/README.md index 91f2c8ee2..4e77f8fcb 100644 --- a/README.md +++ b/README.md @@ -1,63 +1,55 @@ -# Welcome to the SharePoint Framework Developer Preview! +# Welcome to the SharePoint Framework! The SharePoint Framework (SPFx) is a page and part model that enables client-side development for building SharePoint experiences. It facilitates easy integration with the SharePoint data, and provides support for open source tooling development. -The SharePoint Framework is still in initial Developer Preview, and it's still rough around the edges. As we work to improve the SharePoint Framework, we'd love your feedback! If you find issues or have new ideas and suggestions for SharePoint Framework, make sure you submit them [here](https://github.com/SharePoint/sp-dev-docs/issues). We’ll also be monitoring [#spfx](http://sharepoint.stackexchange.com/tags/spfx/), [#spfx-webparts](http://sharepoint.stackexchange.com/tags/spfx-webparts/), and [#spfx-tooling](http://sharepoint.stackexchange.com/tags/spfx-tooling/) at [SharePoint StackExchange](http://sharepoint.stackexchange.com/) as well. +* [Official SharePoint Framework Documentation](https://aka.ms/spfx) -## Developer Preview Releases +This repository contains the raw documents published to Microsoft Docs. -* **Nov 22, 2016** - * **Drop 6 is available**. [See the release notes here](https://github.com/SharePoint/sp-dev-docs/wiki/Release-Notes-Drop-6) +## Questions & Help -* **Oct 17, 2016** - * **Drop 5 is available**. [See the release notes here](https://github.com/SharePoint/sp-dev-docs/wiki/Release-Notes-Drop-5) +Feel free to use [Issues]((https://github.com/SharePoint/sp-dev-docs/issues)) list to report us potential issues around the SharePoint Framework or gaps in our documentation. You can also submit directly pull requests towards our documentation. -* **Sept 21, 2016** - * **Drop 4 is available**. [See the release notes here](https://github.com/SharePoint/sp-dev-docs/wiki/Release-Notes-Drop-4-and-MDL2) +You can also tweet / follow [@Microsoft365Dev](https://twitter.com/Microsoft365Dev) or [@m365pnp](https://twitter.com/m365pnp). -* **Sep 14, 2016** - * **Drop 3 is available**. [See the release notes here](https://github.com/SharePoint/sp-dev-docs/wiki/Release-Notes-Drop-3) - -* **Sep 1, 2016** - * **Drop 2 is available**. [See the release notes here](https://github.com/SharePoint/sp-dev-docs/wiki/Release-Notes-Drop-2) +## SharePoint Framework Releases -* **Aug 17, 2016** - * **Drop 1 is available**. [See the release notes here](https://github.com/SharePoint/sp-dev-docs/wiki/Drop-1) - -## Get Started +Review all the SPFx releases here from the [initial GA release in February 2017](https://learn.microsoft.com/sharepoint/dev/spfx/roadmap) -* [Setup your Office 365 Developer Tenant](http://dev.office.com/sharepoint/docs/spfx/set-up-your-developer-tenant) -* [Setup your Machine](http://dev.office.com/sharepoint/docs/spfx/set-up-your-development-environment) -* [Go build your first web part](http://dev.office.com/sharepoint/docs/spfx/web-parts/get-started/build-a-hello-world-web-part) +## Get Started + +* [Setup your Office 365 Developer Tenant](https://learn.microsoft.com/sharepoint/dev/spfx/set-up-your-developer-tenant) +* [Setup your Machine](https://learn.microsoft.com/sharepoint/dev/spfx/set-up-your-development-environment) +* [Go build your first web part](https://learn.microsoft.com/sharepoint/dev/spfx/web-parts/get-started/build-a-hello-world-web-part) ## Learn More -* [Background and Philosophy](http://dev.office.com/sharepoint/docs/spfx/sharepoint-framework-overview) -* [Design Great Web Parts](http://dev.office.com/sharepoint/docs/spfx/web-parts/basics/design-considerations-for-web-parts) -* [API Docs](https://sharepoint.github.io/) +* [Background and Philosophy](https://learn.microsoft.com/sharepoint/dev/spfx/sharepoint-framework-overview) +* [Design Great Web Parts](https://learn.microsoft.com/sharepoint/dev/design/design-guidance-overview) +* [API Docs](https://learn.microsoft.com/javascript/api/sp-application-base) ## Updates & Feedback To keep track of improvements to the Office 365 Framework, please take a look at: -* [@SharePoint](https://twitter.com/sharepoint) and [@OfficeDev](https://twitter.com/officedev) on Twitter -* [Office Developer Blog](http://dev.office.com/blogs) +* [@SharePoint](https://twitter.com/sharepoint), [@Microsoft365Dev](https://twitter.com/Microsoft365Dev) and [@m365pnp](https://twitter.com/m365pnp) on Twitter +* [Office Developer Blog](https://developer.microsoft.com/office/blogs/) Provide Feedback: * If you find issues or have new ideas and suggestions for SharePoint Framework, make sure you submit them [here](https://github.com/SharePoint/sp-dev-docs/issues). -* [SharePoint StackExchange](http://sharepoint.stackexchange.com/) (please use [#spfx](http://sharepoint.stackexchange.com/tags/spfx/), [#spfx-webparts](http://sharepoint.stackexchange.com/tags/spfx-webparts/), and [#spfx-tooling](http://sharepoint.stackexchange.com/tags/spfx-tooling/) tags) * [SharePoint Developer](https://techcommunity.microsoft.com/t5/SharePoint-Developer/bd-p/SharePointDev) group at Microsoft Tech Community * [SharePoint Developer UserVoice](https://sharepoint.uservoice.com/forums/329220-sharepoint-dev-platform) -## Deployment Status -Note: SharePoint Framework web parts are not supported for production use. +## Contribute on the SharePoint Dev Docs + +Please see following guidance if you are planning to submit changes on the SharePoint developer documentation. We do welcome your pull requests! -The SharePoint Framework is currently available for use in Classic Pages within Office 365 Developer and First Release Tenancies as a developer review release. - -Of course, you can also get started with our SharePoint Workbench to create and test your web parts locally, on your machine. +* [Contribution guidance](https://github.com/SharePoint/sp-dev-docs/blob/master/.github/CONTRIBUTING.md) +* [How to Create Good Pull Requests](https://github.com/SharePoint/sp-dev-docs/wiki/How-to-Create-Good-Pull-Requests) +* If you are a Microsoft contributor, please review official guidance from our [internal documentation](https://review.learn.microsoft.com/help/contribute/?branch=main) for Microsoft Docs contributors ## Have Fun -We look forward to seeing what you build! Please tweet us at @OfficeDev or @SharePoint with the #SPFx tag! +We look forward to seeing what you build! Please tweet us at @Microsoft365Dev, @m365pnp or @SharePoint with the #SPFx tag! diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 000000000..e138ec5d6 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,41 @@ + + +## Security + +Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, which include [Microsoft](https://github.com/microsoft), [Azure](https://github.com/Azure), [DotNet](https://github.com/dotnet), [AspNet](https://github.com/aspnet), [Xamarin](https://github.com/xamarin), and [our GitHub organizations](https://opensource.microsoft.com/). + +If you believe you have found a security vulnerability in any Microsoft-owned repository that meets [Microsoft's definition of a security vulnerability](https://aka.ms/opensource/security/definition), please report it to us as described below. + +## Reporting Security Issues + +**Please do not report security vulnerabilities through public GitHub issues.** + +Instead, please report them to the Microsoft Security Response Center (MSRC) at [https://msrc.microsoft.com/create-report](https://aka.ms/opensource/security/create-report). + +If you prefer to submit without logging in, send email to [secure@microsoft.com](mailto:secure@microsoft.com). If possible, encrypt your message with our PGP key; please download it from the [Microsoft Security Response Center PGP Key page](https://aka.ms/opensource/security/pgpkey). + +You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at [microsoft.com/msrc](https://aka.ms/opensource/security/msrc). + +Please include the requested information listed below (as much as you can provide) to help us better understand the nature and scope of the possible issue: + + * Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.) + * Full paths of source file(s) related to the manifestation of the issue + * The location of the affected source code (tag/branch/commit or direct URL) + * Any special configuration required to reproduce the issue + * Step-by-step instructions to reproduce the issue + * Proof-of-concept or exploit code (if possible) + * Impact of the issue, including how an attacker might exploit the issue + +This information will help us triage your report more quickly. + +If you are reporting for a bug bounty, more complete reports can contribute to a higher bounty award. Please visit our [Microsoft Bug Bounty Program](https://aka.ms/opensource/security/bounty) page for more details about our active programs. + +## Preferred Languages + +We prefer all communications to be in English. + +## Policy + +Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https://aka.ms/opensource/security/cvd). + + diff --git a/ThirdPartyNotices b/ThirdPartyNotices new file mode 100644 index 000000000..25ca6dcd6 --- /dev/null +++ b/ThirdPartyNotices @@ -0,0 +1,15 @@ +##Legal Notices +Microsoft and any contributors grant you a license to the Microsoft documentation and other content +in this repository under the [Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/legalcode), +see the [LICENSE](LICENSE) file, and grant you a license to any code in the repository under the [MIT License](https://opensource.org/licenses/MIT), see the +[LICENSE-CODE](LICENSE-CODE) file. + +Microsoft, Windows, Microsoft Azure and/or other Microsoft products and services referenced in the documentation +may be either trademarks or registered trademarks of Microsoft in the United States and/or other countries. +The licenses for this project do not grant you rights to use any Microsoft names, logos, or trademarks. +Microsoft's general trademark guidelines can be found at http://go.microsoft.com/fwlink/?LinkID=254653. + +Privacy information can be found at https://privacy.microsoft.com/ + +Microsoft and any contributors reserve all others rights, whether under their respective copyrights, patents, +or trademarks, whether by implication, estoppel or otherwise. \ No newline at end of file diff --git a/assets/MicrosoftSharePointClientComponentsEULA.docx b/assets/MicrosoftSharePointClientComponentsEULA.docx new file mode 100644 index 000000000..d7e06041f Binary files /dev/null and b/assets/MicrosoftSharePointClientComponentsEULA.docx differ diff --git a/assets/ace/URL.txt b/assets/ace/URL.txt new file mode 100644 index 000000000..7d3d66ec3 --- /dev/null +++ b/assets/ace/URL.txt @@ -0,0 +1 @@ +me/events?$select=subject,body,bodyPreview,organizer,attendees,start,end,location \ No newline at end of file diff --git a/assets/ace/calendar-top.png b/assets/ace/calendar-top.png new file mode 100644 index 000000000..d8cb719da Binary files /dev/null and b/assets/ace/calendar-top.png differ diff --git a/assets/ace/email-top.png b/assets/ace/email-top.png new file mode 100644 index 000000000..d9170e95a Binary files /dev/null and b/assets/ace/email-top.png differ diff --git a/assets/ace/events-quick-view.json b/assets/ace/events-quick-view.json new file mode 100644 index 000000000..fb16cb82b --- /dev/null +++ b/assets/ace/events-quick-view.json @@ -0,0 +1,85 @@ +{ + "type": "AdaptiveCard", + "version": "1.5", + "@odata.type": "#microsoft.graph.message", + "body": [ + { + "type": "Container", + "items": [ + { + "type": "Image", + "url": "https://raw.githubusercontent.com/SharePoint/sp-dev-docs/main/assets/ace/calendar-top.png" + }, + { + "type": "TextBlock", + "text": "This control displays the latest calendar events. You can open the event in Outlook or, if it's a meeting, you can join it simply clicking on the button next to the event.", + "wrap": true + } + ] + }, + { + "type": "Container", + "$data": "${value}", + "items": [ + { + "type": "ColumnSet", + "columns": [ + { + "type": "Column", + "width": "stretch", + "items": [ + { + "type": "TextBlock", + "text": "${subject}", + "size": "Medium" + }, + { + "type": "TextBlock", + "text": "${location.displayName}", + "spacing": "None" + }, + { + "type": "TextBlock", + "text": "${formatDateTime(substring(start.dateTime,0,19), 'dd/MM/yyyy hh:mm')}-${formatDateTime(substring(end.dateTime,0,19), 'hh:mm')}", + "spacing": "None", + "size": "Small" + } + ] + }, + { + "type": "Column", + "width": "auto", + "items": [ + { + "type": "Image", + "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAAAXNSR0IArs4c6QAAAvBJREFUSEvtVUtIalEUXdeKiDDIiIY1i7CIBkqRRrNCAqFM6AsRQhMLx5VSVvTBoqwIIqTIoCYV1aBZ/4EDk4gkmgg16iP9cFQaez+89N4zrz148AZvw+XCufectddeZ68tRCKRCP5iCP8MgM/nQ39/P9bX15Gfnw+bzYb6+nokJyfH5Z8Qg0AggObmZqjVarS2tsLr9WJ4eBhjY2PQ6/UMEA6H8fT0BJlMhoyMDAiCwOsJAayuroKehYUFZGZmgmSbm5vD+fk5HA4H3t/f0d3djcnJScjlcvT29sJisTC7hADcbjd2d3cxMzPDB1AsLS3h5OQEExMTODo64kNnZ2dxe3uLnp4eLC4uQqlUQgiHwxGPx4PDw0POJFbc3NzwhunpaTQ0NODy8hKdnZ1cHnqvra2JDB8fH7mcxKy0tBTC/f19pKmpiTP8TnR1dWFwcBDp6emIahQKhUCPRqPB+Pj4Dy0+A9DNqKys/A1nb28PfX190Gq1XIqioiLk5OSIQtKGh4cHbG1tMaBOp+M3i/wZYHl5GcTm1yANiLZCoUBxcTFSUlIkydbW1qK9vf1ngJKSEmRnZ6OmpgZmsxlOpxPb29u4u7vD6ekpCgoKYDQakZaWJgIEg0Fsbm6yHpQABWl2dXUFSiymBtRQVAq73Q6r1SoeVlVVxZuysrLEtajgU1NT3IAUx8fHvPc/AJfjj0pkMpnQ2NiIlZUVzM/Pf1uDg4MDDA0Nfa3BV3cwEZHf3t7YaV9fXzE6OhrfKigTioqKCiQlJXGjkaNGnZK+nZ2dwWAw8A0qKysD2TpZD92g8vLy+GZH7rmzsyO6aCxm9I/L5YJKpcLFxQUKCwu5h/Ly8qTtOuoxpElLSwt7/efw+/1oa2vjA2M5QELzYH9/HwRAndrR0YHc3Fy8vLxgY2MDIyMjqK6uFk0vFkPJeUDDhWxiYGCAx2U0qObU5XV1dUhNTf3SmyQBojsJ6Pn5GdfX1+xXZBdS8zihEknapsQPH6Mh/FGBh+hUAAAAAElFTkSuQmCC", + "selectAction": { + "type": "Action.OpenUrl", + "url": "${onlineMeeting.joinUrl}" + }, + "$when": "${isOnlineMeeting}" + } + ] + }, + { + "type": "Column", + "width": "auto", + "items": [ + { + "type": "Image", + "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAAAXNSR0IArs4c6QAAAR5JREFUSEvtljGuRFAUhv8rIdGQSHQahc4ORG8PbMICVBZgE+xBL3agU2h0RIJCQsLkSt4kM2/e3Fu8ea+hPef4zvnOjYscx3Hggw95BizLgjAM4boufN/nQmdZhqIokCQJZFl+qCHzPB9pmmIcxzOwbRvyPIdpmrBtmwtQVRWapoHneRBF8axRVRVBEID0fX/QTilAURTs+466rqFpGnRd5wJ0XYdhGGBZFgRBwDRNJ4BOdgdEUQTHcfAbisqyRBzHrwF057QDSZK++fxpHNrUuq6nAUIIXgLoeIZhcClhJbVte2p+UPS1A1YxT/ztDnhewMp5uwNWMU/8AjAtXYouRUwDzIT/OUUf+9g9X5nM+TkT7lfmn/9VcDbInXYDn/BFftWPiLMAAAAASUVORK5CYII=", + "selectAction": { + "type": "Action.OpenUrl", + "url": "${webLink}" + } + } + ] + } + ] + } + ], + "separator": true + } + ], + "$schema": "http://adaptivecards.io/schemas/adaptive-card.json" +} \ No newline at end of file diff --git a/assets/ace/messages-quick-view.json b/assets/ace/messages-quick-view.json new file mode 100644 index 000000000..74e7f40a1 --- /dev/null +++ b/assets/ace/messages-quick-view.json @@ -0,0 +1,84 @@ +{ + "type": "AdaptiveCard", + "version": "1.5", + "@odata.type": "#microsoft.graph.message", + "body": [ + { + "type": "Container", + "items": [ + { + "type": "Image", + "url": "https://raw.githubusercontent.com/SharePoint/sp-dev-docs/main/assets/ace/email-top.png" + }, + { + "type": "TextBlock", + "text": "This control displays the last email message received in your inbox. To view the message, simply click on the button. The message will open directly in Outlook, allowing you to read and respond to it as needed.", + "wrap": true + } + ] + }, + { + "type": "Container", + "$data": "${value}", + "items": [ + { + "type": "ColumnSet", + "columns": [ + { + "type": "Column", + "width": "stretch", + "items": [ + { + "type": "TextBlock", + "text": "${from.emailAddress.name}", + "size": "Medium", + "weight": "${if(isRead, 'normal', 'bolder')}" + }, + { + "type": "TextBlock", + "text": "${subject}", + "spacing": "None", + "weight": "${if(isRead, 'normal', 'bolder')}" + } + ] + }, + { + "type": "Column", + "width": "auto", + "items": [ + { + "type": "TextBlock", + "text": "${if(hasAttachments, '📎', '')} ${if(importance == 'normal', '', '❗')} ${if(flag.flagStatus == 'flagged', '🚩', '')}", + "horizontalAlignment": "Right" + }, + { + "type": "TextBlock", + "text": "{{DATE(${sentDateTime}, COMPACT)}} {{TIME(${sentDateTime})}}", + "spacing": "None", + "size": "Small" + } + ], + "verticalContentAlignment": "Center" + }, + { + "type": "Column", + "width": "auto", + "items": [ + { + "type": "Image", + "url": "${if(isRead, 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAAAXNSR0IArs4c6QAAAY5JREFUSEvt1aGLwlAcB/DvQ2FNg6BFMPg3WDRZRayGLWkxKViUgUkYWgRNKy5psG52kxb/BoOwMtEwTaLwjudxntObb3onHMe9uvH97Pd9vDdCKaV44SK/Btjv9zAMAz6fD5lMBoIgeJqbOwELHo/HaLfbME3zFBqNRlGr1ZDNZrmQK3AZvFqtUKlUUCwWT0C/30e320U4HOZCN4BbcCAQcFSy3W49QWfAa/B18TyIHA4Hqus6Wq0WLqu4/mLejl5D9XoduVwOZL1eU1EUEYlE0Ol0EAqFeFl3n282G1SrVViWheFw+AnMZjMoioJSqQS/3/8UcjweoaoqZFlGMpl0AolEAqPRCOVy+SnkI7zX6yGfz2M+nzuBRqMBttFsgkeRy3A2ATuEzWbzFmBjTSYTFAoFLJfLh2qKxWLQNA3pdBqs7i+BVCoFdvctFovzqfWqsNMdj8dBCMF0OnUHvAbee+8f4Lb4RyuybRuPXnBuXbGLLxgMvh+03W5HB4MBGPCTiwGSJIH7y/wu+nLgDSewZ7NrDNFAAAAAAElFTkSuQmCC', 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAAAXNSR0IArs4c6QAAARBJREFUSEvtlS2qhUAYhl+LRbALYhMsrsAF2MXmLhRsJpugu7CJ3QW4AotgE8EiBsFimYNevJxz8Th6YZpThpnv55nvnT+OEELAsHEPgKYue4nGcSS+76NtW9pibtkVRUEUReCGYSCO46Cua6y9KIq3Ev11nqYJaZpC07St/wUURQFd1+F5HmzbhiAIt0DzPCPLMsRxjKqqYJrmJ8B1XfR9vzms7SroPfEeJ0kSkiT5BARBAMMwcBRwVNGZX1mWCMPwGLDr8i3Bat+l+FbpJcARaFmWbZrn+VMJbwHeQXmeb0PLsk4Pwb8Ad47UA6CqdSiRqqqQZZkafMWh6zo0TfNzD5g/ds+PRtsT9j8a6z14AbwnH7bn+xIdAAAAAElFTkSuQmCC')}", + "selectAction": { + "type": "Action.OpenUrl", + "url": "${webLink}" + } + } + ] + } + ] + } + ], + "separator": true + } + ], + "$schema": "http://adaptivecards.io/schemas/adaptive-card.json" +} \ No newline at end of file diff --git a/assets/bot-powered/Media/Collect-Feedback.png b/assets/bot-powered/Media/Collect-Feedback.png new file mode 100644 index 000000000..16aecc8a0 Binary files /dev/null and b/assets/bot-powered/Media/Collect-Feedback.png differ diff --git a/assets/bot-powered/Media/Ok-Feedback.png b/assets/bot-powered/Media/Ok-Feedback.png new file mode 100644 index 000000000..ea5aa3a3b Binary files /dev/null and b/assets/bot-powered/Media/Ok-Feedback.png differ diff --git a/assets/bot-powered/TeamsAppManifest/icon-color.png b/assets/bot-powered/TeamsAppManifest/icon-color.png new file mode 100644 index 000000000..b8cf81afb Binary files /dev/null and b/assets/bot-powered/TeamsAppManifest/icon-color.png differ diff --git a/assets/bot-powered/TeamsAppManifest/icon-outline.png b/assets/bot-powered/TeamsAppManifest/icon-outline.png new file mode 100644 index 000000000..2c3bf6fa6 Binary files /dev/null and b/assets/bot-powered/TeamsAppManifest/icon-outline.png differ diff --git a/assets/bot-powered/TeamsAppManifest/manifest.json b/assets/bot-powered/TeamsAppManifest/manifest.json new file mode 100644 index 000000000..7a502770d --- /dev/null +++ b/assets/bot-powered/TeamsAppManifest/manifest.json @@ -0,0 +1,65 @@ +{ + "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.14/MicrosoftTeams.schema.json", + "manifestVersion": "1.16", + "version": "1.0.0", + "id": "", + "packageName": "collectfeedback.botpoweredace", + "developer": { + "name": "", + "websiteUrl": "", + "privacyUrl": "", + "termsOfUseUrl": "", + "mpnId": "" + }, + "name": { + "short": "Collect Feedaback Bot Powered ACE", + "full": "This is a basic sample of a Bot Powered ACE for Microsoft Viva Connections Dashboard to collect user's feedback" + }, + "description": { + "short": "Basic sample of a Bot Powered ACE for Microsoft Viva Connections Dashboard to collect user's feedback", + "full": "Basic sample of how to use the latest release of the Bot Framework SDK to build a Bot Powered ACE for Microsoft Viva Connections Dashboard to collect user's feedback" + }, + "icons": { + "outline": "icon-outline.png", + "color": "icon-color.png" + }, + "accentColor": "#FFFFFF", + "bots": [ + { + "botId": "", + "needsChannelSelector": false, + "isNotificationOnly": false, + "supportsCalling": false, + "supportsVideo": false, + "supportsFiles": false, + "scopes": [ + "team", + "personal", + "groupchat" + ] + } + ], + "dashboardCards": [ + { + "id": "", + "displayName": "Collect Feedaback", + "description": "Bot Powered ACE to collect user's feedback", + "icon": { + "officeUIFabricIconName": "Feedback" + }, + "contentSource": { + "sourceType": "bot", + "botConfiguration": { + "botId": "" + } + }, + "defaultSize": "medium" + } + ], + "permissions": [ + "identity" + ], + "validDomains": [ + ".ngrok.io" + ] +} \ No newline at end of file diff --git a/assets/sharepoint-pnp-general-dev-community-call.ics b/assets/sharepoint-pnp-general-dev-community-call.ics new file mode 100644 index 000000000..fe57ff55f --- /dev/null +++ b/assets/sharepoint-pnp-general-dev-community-call.ics @@ -0,0 +1,594 @@ +BEGIN:VCALENDAR +PRODID:-//Microsoft Corporation//Outlook 16.0 MIMEDIR//EN +VERSION:2.0 +METHOD:REQUEST +X-MS-OLK-FORCEINSPECTOROPEN:TRUE +BEGIN:VTIMEZONE +TZID:FLE Standard Time +BEGIN:STANDARD +DTSTART:16011028T040000 +RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10 +TZOFFSETFROM:+0300 +TZOFFSETTO:+0200 +END:STANDARD +BEGIN:DAYLIGHT +DTSTART:16010325T030000 +RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=3 +TZOFFSETFROM:+0200 +TZOFFSETTO:+0300 +END:DAYLIGHT +END:VTIMEZONE +BEGIN:VEVENT +CLASS:PUBLIC +CREATED:20190625T112317Z +DESCRIPTION:Welcome to SharePoint PnP Bi-weekly Special Interest Group call + around SharePoint General dev. Topics covered in this call are solution d + esigns\, provisioning\, PnP PowerShell\, CSOM\, PnP CSOM\, PowerApps\, Flo + w etc. \n \nLink to join the call – https://aka.ms/spdev-sig-call-join \ + n \n-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --\nShareP + oint Dev Community – https://aka.ms/sppnp \nSharePoint Dev Videos (includ + ing recorded community calls) – https://aka.ms/spdev-videos \nSharePoint + Dev Documentation - https://aka.ms/spdev-docs \nSharePoint Dev issues – h + ttp://aka.ms/spdev-issues \nSharePoint Dev UserVoice – https://aka.ms/spd + ev-uservoice \n \n \n +DTEND;TZID="FLE Standard Time":20190808T180000 +DTSTAMP:20190625T112319Z +DTSTART;TZID="FLE Standard Time":20190808T170000 +LAST-MODIFIED:20190625T112317Z +LOCATION:Microsoft Teams Meeting +ORGANIZER;CN="Vesa Juvonen":mailto:Vesa.Juvonen@microsoft.com +PRIORITY:5 +RECURRENCE-ID;TZID="FLE Standard Time":20190808T170000 +SEQUENCE:0 +SUMMARY;LANGUAGE=en-us:SharePoint Dev Ecosystem (PnP) - General Dev\, Micro + soft Flow\, PowerApps\, CSOM\, PnP Core\, PnP PowerShell SIG Bi-Weekly Cal + l +TRANSP:OPAQUE +UID:040000008200E00074C5B7101A82E00800000000D0AFD045D62AD501000000000000000 + 01000000090435FC9105F97488EB25A958F88D87C +X-ALT-DESC;FMTTYPE=text/html:

Welcome to SharePoint PnP Bi-weekly Special Interest G + roup call around SharePoint General dev. Topics covered in this call are s + olution designs\, provisioning\, PnP PowerShell\, CSOM\, PnP CSOM\, PowerA + pps\, Flow etc.

 \;

Link to join + the call –\; https://aka + .ms/spdev-sig-call-join

 \;

- + - -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --

SharePoint D + ev Community –\; https://aka.ms/sppnp

SharePoint Dev Videos (including re + corded community calls) –\; http + ://aka.ms/spdev-videos

SharePoint + Dev Documentation - https://aka.ms/spde + v-docs

SharePoint Dev issues R + 11\; https://aka.ms/spdev-issues < + o:p>

SharePoint Dev UserVoice –\; https://aka.ms/spdev-uservoice

 \;

 \;

< + /html> +X-MICROSOFT-CDO-BUSYSTATUS:BUSY +X-MICROSOFT-CDO-IMPORTANCE:1 +X-MICROSOFT-DISALLOW-COUNTER:FALSE +X-MS-OLK-AUTOFILLLOCATION:FALSE +X-MS-OLK-CONFTYPE:0 +BEGIN:VALARM +TRIGGER:-PT15M +ACTION:DISPLAY +DESCRIPTION:Reminder +END:VALARM +END:VEVENT +END:VCALENDAR diff --git a/assets/sharepoint-pnp-monthly-community-call.ics b/assets/sharepoint-pnp-monthly-community-call.ics new file mode 100644 index 000000000..a7e1eb018 --- /dev/null +++ b/assets/sharepoint-pnp-monthly-community-call.ics @@ -0,0 +1,593 @@ +BEGIN:VCALENDAR +PRODID:-//Microsoft Corporation//Outlook 16.0 MIMEDIR//EN +VERSION:2.0 +METHOD:REQUEST +X-MS-OLK-FORCEINSPECTOROPEN:TRUE +BEGIN:VTIMEZONE +TZID:FLE Standard Time +BEGIN:STANDARD +DTSTART:16011028T040000 +RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10 +TZOFFSETFROM:+0300 +TZOFFSETTO:+0200 +END:STANDARD +BEGIN:DAYLIGHT +DTSTART:16010325T030000 +RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=3 +TZOFFSETFROM:+0200 +TZOFFSETTO:+0300 +END:DAYLIGHT +END:VTIMEZONE +BEGIN:VEVENT +CLASS:PUBLIC +CREATED:20190624T184213Z +DESCRIPTION:Welcome to SharePoint Dev Ecosystem (PnP) – Monthly Community + Call. In this call we cover the latest changes around the SharePoint deve + lopment from SharePoint engineering and community perspective. We’ll go + through the latest contributions and status in the UserVoice. \n \nLink t + o join the call – https://aka.ms/spdev-call-join \n \n-- -- -- -- -- -- + -- -- -- -- -- -- -- -- -- -- -- -- -- -- --\nSharePoint Dev Community – + https://aka.ms/sppnp \nSharePoint Dev Videos (including recorded community + calls) – https://aka.ms/spdev-videos \nSharePoint Dev Documentation - ht + tp://aka.ms/spdev-docs \nSharePoint Dev issues – https://aka.ms/spdev-iss + ues \nSharePoint Dev UserVoice – https://aka.ms/spdev-uservoice \n \n \n +DTEND;TZID="FLE Standard Time":20190813T190000 +DTSTAMP:20190624T184214Z +DTSTART;TZID="FLE Standard Time":20190813T180000 +LAST-MODIFIED:20190624T184213Z +LOCATION:Microsoft Teams Meeting +ORGANIZER;CN="Vesa Juvonen":mailto:Vesa.Juvonen@microsoft.com +PRIORITY:5 +RRULE:FREQ=MONTHLY;BYDAY=TU;BYSETPOS=2 +SEQUENCE:0 +SUMMARY;LANGUAGE=en-us:SharePoint Dev Ecosystem (PnP) - Monthly Community C + all +TRANSP:OPAQUE +UID:040000008200E00074C5B7101A82E008000000001067215BC42AD501000000000000000 + 010000000FAF0FD97CF317A488F8BED917B68BC08 +X-ALT-DESC;FMTTYPE=text/html:

Welcome to SharePoint Dev Ecos + ystem (PnP) –\; Monthly Community Call. In this call we cover the lat + est changes around the SharePoint development from SharePoint engineering + and community perspective. We’\;ll go through the latest contribution + s and status in the UserVoice. \;

&nbs + p\;

Link to join the call ̵ + 1\; https://aka.ms/spdev-call-joi + n

+  \;

-- -- -- -- -- -- -- -- + -- -- -- -- -- -- -- -- -- -- -- -- --

SharePoint Dev Community –\; + https://aka.ms/sppnp

SharePoint Dev Videos (including recorded community calls + ) –\; https://aka.ms/spdev-videos +

SharePoint Dev Documentation - < + a href="https://aka.ms/spdev-docs">https://aka.ms/spdev-docs +

SharePoint Dev issues –\; https://aka.ms/spdev-issues

SharePoint Dev UserVoice –\; https://aka.ms/spdev-uservoice

 \;

 \;

+X-MICROSOFT-CDO-BUSYSTATUS:BUSY +X-MICROSOFT-CDO-IMPORTANCE:1 +X-MICROSOFT-DISALLOW-COUNTER:FALSE +X-MS-OLK-AUTOFILLLOCATION:FALSE +X-MS-OLK-CONFTYPE:0 +BEGIN:VALARM +TRIGGER:-PT15M +ACTION:DISPLAY +DESCRIPTION:Reminder +END:VALARM +END:VEVENT +END:VCALENDAR diff --git a/assets/sharepoint-pnp-spfx-pnpjs-community-call.ics b/assets/sharepoint-pnp-spfx-pnpjs-community-call.ics new file mode 100644 index 000000000..3f92769fa --- /dev/null +++ b/assets/sharepoint-pnp-spfx-pnpjs-community-call.ics @@ -0,0 +1,105 @@ +BEGIN:VCALENDAR +PRODID:-//Microsoft Corporation//Outlook 16.0 MIMEDIR//EN +VERSION:2.0 +METHOD:REQUEST +X-MS-OLK-FORCEINSPECTOROPEN:TRUE +BEGIN:VTIMEZONE +TZID:Eastern Standard Time +BEGIN:STANDARD +DTSTART:16011104T020000 +RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=11 +TZOFFSETFROM:-0400 +TZOFFSETTO:-0500 +END:STANDARD +BEGIN:DAYLIGHT +DTSTART:16010311T020000 +RRULE:FREQ=YEARLY;BYDAY=2SU;BYMONTH=3 +TZOFFSETFROM:-0500 +TZOFFSETTO:-0400 +END:DAYLIGHT +END:VTIMEZONE +BEGIN:VEVENT +CLASS:PUBLIC +CREATED:20190624T182257Z +DESCRIPTION:Welcome to SharePoint PnP Bi-weekly Special Interest Group call + around Client-side development. Topics covered in this call are SharePoin + t Framework latest updates\, PnPjs\, Office365Cli\, Reusable Controls\, an + d community demos.\n\n \n\nLink to join the call – https://aka.ms/spdev- + spfx-call-join\n\n \n\n-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- + -- -- -- --\n\n \n\nSharePoint Dev Community – https://aka.ms/sppnp Share + Point Dev Videos (including recorded community calls) – https://aka.ms/sp + dev-videos SharePoint Dev Documentation - https://aka.ms/spdev-docs SharePo + int Dev issues – https://aka.ms/spdev-issues SharePoint Dev UserVoice – + https://aka.ms/spdev-uservoice\n\n +DTEND;TZID="Eastern Standard Time":20190801T110000 +DTSTAMP:20190624T182203Z +DTSTART;TZID="Eastern Standard Time":20190801T100000 +LAST-MODIFIED:20190624T182257Z +LOCATION:Microsoft Teams Meeting +ORGANIZER;CN="Patrick Rodgers":invalid:nomail +PRIORITY:5 +RRULE:FREQ=WEEKLY;INTERVAL=2;BYDAY=TH;WKST=SU +SEQUENCE:2 +SUMMARY;LANGUAGE=en-us:SharePoint Patterns and Practices Client-side develo + pment SIG +TRANSP:OPAQUE +UID:040000008200E00074C5B7101A82E00800000000C0BD1A15972AD501000000000000000 + 01000000044FD58F0AA2A1F4790EC41C4BE20606E +X-ALT-DESC;FMTTYPE=text/html: + + + + + + + +``` + +
+ +If you want your users to deep link into portions of your add-in, your apphost page and the contents of the **IFrame** can collaborate to make that possible. One alternative is to use **IFrame** post-message communication and individual URLs per page in the remote add-in. To have individual URLs per page, you can create individual pages in the add-in web or use query string parameters on one page. + +### Alternative approach: Add the sites to the same security zone in Internet Explorer + +If an add-in was not designed following the apphost pattern, you can still allow it to work by adding the following domains into the same security zone: + +- The domain of your SharePoint site (for example, `https://contoso.sharepoint.com`). + +- The domain of the cloud-hosted add-in (`http://remoteserver`). + +- The domain of Microsoft-hosted sign-in pages and services (`*.microsoftonline.com`). + +Administrators can use Active Directory policies to push changes to all computers in the organization. + + + + +## Security implications of using the apphost pattern + +It is important to point out that the apphost pattern effectively puts your remote page in the same security zone as the add-in web. Make you sure you understand the implications of adding a site to a security zone. + + + +## Working in other browsers: Chrome, Firefox, and Safari + +Other browsers, such as Google Chrome, Mozilla Firefox, and Apple Safari, do not implement the concept of security zones. If a browser does not isolate the cookies in separated storage, it probably will not encounter the difficulties described in this article. We recommend that you follow the apphost pattern in your add-ins. Using the apphost pattern ensures that your add-in works in the mentioned browsers and Internet Explorer, regardless of which security zone SharePoint is in. + +## See also + +- [Secure data access and client object models for SharePoint Add-ins](secure-data-access-and-client-object-models-for-sharepoint-add-ins.md) +- [Create a custom proxy page for the cross-domain library in SharePoint](create-a-custom-proxy-page-for-the-cross-domain-library-in-sharepoint.md) +- [Client-side Cross-domain Security](https://msdn.microsoft.com/library/cc709423%28v=vs.85%29.aspx) +- [Creating SharePoint Add-ins that use the cross-domain library](creating-sharepoint-add-ins-that-use-the-cross-domain-library.md) +- [Authorization and authentication of SharePoint Add-ins](authorization-and-authentication-of-sharepoint-add-ins.md) + + + diff --git a/docs/sp-add-ins/working-with-folders-and-files-with-rest.md b/docs/sp-add-ins/working-with-folders-and-files-with-rest.md new file mode 100644 index 000000000..cf4666d49 --- /dev/null +++ b/docs/sp-add-ins/working-with-folders-and-files-with-rest.md @@ -0,0 +1,356 @@ +--- +title: Working with folders and files with REST +description: Perform basic create, read, update, and delete (CRUD) operations on folders and files with the SharePoint REST interface. +ms.date: 01/12/2023 +ms.localizationpriority: high +ms.service: sharepoint +--- + +# Working with folders and files with REST + +> [!NOTE] +> The examples on this page do not support the % and # characters. [Support % and # in files and folders with ResourcePath API](../solution-guidance/supporting-and-in-file-and-folder-with-the-resourcepath-api.md) + +> [!TIP] +> The SharePoint Online (and on-premises SharePoint 2016 and later) REST service supports combining multiple requests into a single call to the service by using the OData `$batch` query option. For details and links to code samples, see [Make batch requests with the REST APIs](make-batch-requests-with-the-rest-apis.md). + +## Working with folders by using REST + +You can retrieve a folder inside a document library when you know its URL. For example, you can **retrieve the root folder of your Shared Documents library** by using the endpoint in the following example. + +```http +GET https://{site_url}/_api/web/GetFolderByServerRelativeUrl('Shared Documents') +Authorization: "Bearer " + accessToken +Accept: "application/json;odata=verbose" +``` + +The following XML shows an example of **folder properties that are returned when you request the XML content type**. + +```xml + + + 0 + Shared Documents + /Shared Documents + + + +``` + +The following example shows how to **create a folder**. + +```http +POST https://{site_url}/_api/web/folders +Authorization: "Bearer " + accessToken +Accept: "application/json;odata=verbose" +Content-Type: "application/json" +Content-Length: {length of request body as integer} +X-RequestDigest: "{form_digest_value}" + +{ + "__metadata": { + "type": "SP.Folder" + }, + "ServerRelativeUrl": "/document library relative url/folder name" +} +``` + +The following example shows how to **rename a folder by using the MERGE method**. + +First, obtain the folder's OData type with a GET request. + +```http +GET https://{site_url}/_api/web/GetFolderByServerRelativeUrl('Folder Name')/ListItemAllFields +Authorization: "Bearer " + accessToken +Accept: "application/json;odata=verbose" +``` + +From the result, obtain the `odata.type` value, such as `SP.Data.Shared_x0020_DocumentsItem` (the value may be different depending on your library configuration). Then submit a MERGE request: + +```http +POST https://{site_url}/_api/web/GetFolderByServerRelativeUrl('Folder Name')/ListItemAllFields +Authorization: "Bearer " + accessToken +Accept: "application/json;odata=verbose" +Content-Type: "application/json" +Content-Length: {length of request body as integer} +If-Match: "{etag or *}" +X-HTTP-Method: "MERGE" +X-RequestDigest: "{form_digest_value}" + +{ + "__metadata": { + "type": "{odata.type from previous call}" + }, + "Title": "New name", + "FileLeafRef": "New name" +} +``` + +The following example shows how to **delete a folder**. + +```http +POST https://{site_url}/_api/web/GetFolderByServerRelativeUrl('Folder Name') +Authorization: "Bearer " + accessToken +If-Match: "{etag or *}" +X-HTTP-Method: "DELETE" +X-RequestDigest: "{form_digest_value}" +``` + +## Working with files by using REST + +The following example shows how to **retrieve all of the files in a folder**. + +```http +GET https://{site_url}/_api/web/GetFolderByServerRelativeUrl('Folder Name')/Files +method: GET +Authorization: "Bearer " + accessToken +Accept: "application/json;odata=verbose" +``` + +The following example shows how to **retrieve a specific file**. + +```http +GET https://{site_url}/_api/web/GetFolderByServerRelativeUrl('Folder Name')/Files('{file_name}')/$value +Authorization: "Bearer " + accessToken +``` + +You can also **retrieve a file when you know its URL**, as in the following example. + +```http +GET https://{site_url}/_api/web/GetFileByServerRelativeUrl('/Folder Name/{file_name}')/$value +Authorization: "Bearer " + accessToken +``` + +The following code sample shows how to **retrieve a file when you know its URL by using the REST endpoint above and C#**. + +```csharp +/// +/// Download File Via Rest API +/// +/// https://xxxxx/sites/DevSite +/// +/// MyDocumentLibrary +/// test.docx +/// C:\\ +public static void DownloadFileViaRestAPI(string webUrl, ICredentials credentials, string documentLibName, string fileName, string path) +{ + webUrl = webUrl.EndsWith("/") ? webUrl.Substring(0, webUrl.Length - 1) : webUrl; + string webRelativeUrl = null; + if (webUrl.Split('/').Length > 3) + { + webRelativeUrl = "/" + webUrl.Split(new char[] { '/' }, 4)[3]; + } + else + { + webRelativeUrl = ""; + } + + using (WebClient client = new WebClient()) + { + client.Headers.Add("X-FORMS_BASED_AUTH_ACCEPTED", "f"); + client.Credentials = credentials; + Uri endpointUri = new Uri(webUrl + "/_api/web/GetFileByServerRelativeUrl('" + webRelativeUrl + "/" + documentLibName + "/" + fileName + "')/$value"); + + byte[] data = client.DownloadData(endpointUri); + FileStream outputStream = new FileStream(path + fileName, FileMode.OpenOrCreate | FileMode.Append, FileAccess.Write, FileShare.None); + outputStream.Write(data, 0, data.Length); + outputStream.Flush(true); + outputStream.Close(); + } +} + +static void Main(string[] args) +{ + string siteURL = "https://xxxxx/sites/DevSite"; + + //set credential of SharePoint online + SecureString secureString = new SecureString(); + foreach (char c in "Password".ToCharArray()) + { + secureString.AppendChar(c); + } + ICredentials credentials = new SharePointOnlineCredentials("xxxxxx.onmicrosoft.com", secureString); + + //set credential of SharePoint 2013(On-Premises) + //string userName = "Administrator"; + //string password = "xxxxxxx"; + //string domain = "CONTOSO"; + //ICredentials credentials = new NetworkCredential(userName, password, domain); + + DownloadFileViaRestAPI(siteURL, credentials, "MyDocumentLib", "test.docx", "c:\\"); + + Console.WriteLine("success"); + Console.ReadLine(); +} +``` + +The following example shows how to **create a file and add it to a folder**. + +```http +POST https://{site_url}/_api/web/GetFolderByServerRelativeUrl('Folder Name')/Files/add(url='a.txt',overwrite=true) +Authorization: "Bearer " + accessToken +Content-Length: {length of request body as integer} +X-RequestDigest: "{form_digest_value}" + +"Contents of file" +``` + +The following example shows how to **update a file by using the PUT method**. + +> [!NOTE] +> **PUT** is the only method that you can use to update a file. The **MERGE** method is not allowed. + +```http +POST https://{site_url}/_api/web/GetFileByServerRelativeUrl('/Folder Name/{file_name}')/$value +Authorization: "Bearer " + accessToken +Content-Length: {length of request body as integer} +X-HTTP-Method: "PUT" +X-RequestDigest: "{form_digest_value}" + +"Contents of file" +``` + +If you want to update a file's metadata, you have to construct an endpoint that reaches the file as a list item. You can do this because each folder is also a list, and each file is also a list item. Construct an endpoint that looks like this: `https://{site_url}/_api/web/lists/getbytitle('Documents')/items({item_id})`. For information about how to update a list item's metadata, see [Working with lists and list items with REST](working-with-lists-and-list-items-with-rest.md). + +You may want to check out a file to make sure that no one changes it before you update it. After your update, you should check the file back in so that others can work with it. + +The following example shows how to **check out a file**. + +```http +POST https://{site_url}/_api/web/GetFileByServerRelativeUrl('/Folder Name/{file_name}')/CheckOut(), +Authorization: "Bearer " + accessToken +X-RequestDigest: "{form_digest_value}" +``` + +The following example shows how to **check in a file**. + +```http +POST https://{site_url}/_api/web/GetFileByServerRelativeUrl('/Folder Name/{file_name}')/CheckIn(comment='Comment',checkintype=0) +Authorization: "Bearer " + accessToken +X-RequestDigest: "{form_digest_value}" +``` + +The following example shows how to **delete a file**. + +```http +POST https://{site_url}/_api/web/GetFileByServerRelativeUrl('/Folder Name/{file_name}') +Authorization: "Bearer " + accessToken +If-Match: "{etag or *}" +X-HTTP-Method: "DELETE" +X-RequestDigest: "{form_digest_value}" +``` + +## Working with large files by using REST + +When you need to upload a binary file that is larger than 1.5 megabytes (MB), the REST interface is your only option. For a code example that shows you how to upload a binary file that is smaller than 1.5 MB by using the SharePoint JavaScript object model, see [Complete basic operations using JavaScript library code in SharePoint](complete-basic-operations-using-javascript-library-code-in-sharepoint.md). The maximum size of a binary file that you can create with REST is 2 gigabytes (GB). + +The following example shows how to **create a large binary file**. + +> [!WARNING] +> This approach works only with Internet Explorer 10 and the latest versions of other browsers. + +```http +POST https://{site_url}/_api/web/GetFolderByServerRelativeUrl('Folder Name')/Files/Add(url='{file_name}', overwrite=true) +Authorization: "Bearer " + accessToken +Content-Length: {length of request body as integer} +X-RequestDigest: "{form_digest_value}" + +Contents of binary file +``` + +The following code sample shows how to **create a file by using this REST endpoint and the JSOM cross-domain library**. + +```javascript +function uploadFileBinary() { + XDomainTestHelper.clearLog(); + var requestExecutor; + if (document.getElementById("TxtViaUrl").value.length > 0) { + requestExecutor = new SP.RequestExecutor(document.getElementById("TxtWebUrl").value, document.getElementById("TxtViaUrl").value); + } + else { + requestExecutor = new SP.RequestExecutor(document.getElementById("TxtWebUrl").value); + } + + var body = ""; + for (var i = 0; i < 1000; i++) { + var ch = i % 256; + body = body + String.fromCharCode(ch); + } + + var info = { + url: "_api/web/lists/getByTitle('Shared Documents')/RootFolder/Files/Add(url='a.dat', overwrite=true)", + method: "POST", + binaryStringRequestBody: true, + body: body, + success: success, + error: fail, + state: "Update" + }; + + requestExecutor.executeAsync(info); +} + +``` + +## Working with files attached to list items by using REST + +The following example shows how to **retrieve all of the files that are attached to a list item**. + +```http +GET https://{site_url}/_api/web/lists/getbytitle('{list_title}')/items({item_id})/AttachmentFiles/ +Authorization: "Bearer " + accessToken +Accept: "application/json;odata=verbose" +``` + +The following example shows how to **retrieve a file that is attached to a list item**. + +```http +GET https://{site_url}/_api/web/lists/getbytitle('{list_title}')/items({item_id})/AttachmentFiles('{file_name}')/$value +Authorization: "Bearer " + accessToken +Accept: "application/json;odata=verbose" +``` + +The following example shows how to **create a file attachment to a list item**. + +```http +POST https://{site_url}/_api/web/lists/getbytitle('{list_title}')/items({item_id})/AttachmentFiles/ add(FileName='{file_name}') +Authorization: "Bearer " + accessToken +Content-Length: {length of request body as integer} +X-RequestDigest: "{form_digest_value}" + +"Contents of file" +``` + +The following example shows how to **update a file attachment to a list item by using the PUT method**. + +> [!NOTE] +> **PUT** is the only method that you can use to update a file. The **MERGE** method is not allowed. + +```http +POST https://{site_url}/_api/web/lists/getbytitle('{list_title}')/items({item_id})/AttachmentFiles('{file_name}')/$value +Authorization: "Bearer " + accessToken +Content-Length: {length of request body as integer} +X-HTTP-Method: "PUT" +X-RequestDigest: "{form_digest_value}" + +"Contents of file" +``` + +The following example shows how to **delete a file that is attached to a list item**. + +```http +DELETE https://{site_url}/_api/web/lists/getbytitle('{list_title}')/items({item_id})/AttachmentFiles('{file_name}') +Authorization: "Bearer " + accessToken +Accept: "application/json;odata=verbose" +``` + +## See also + +- [Get to know the SharePoint REST service](get-to-know-the-sharepoint-rest-service.md) +- [Complete basic operations using SharePoint client library code](complete-basic-operations-using-sharepoint-client-library-code.md) +- [Upload a file by using the REST API and jQuery](upload-a-file-by-using-the-rest-api-and-jquery.md) +- [SharePoint-Add-in-REST-OData-BasicDataOperations](https://github.com/OfficeDev/SharePoint-Add-in-REST-OData-BasicDataOperations) +- [Secure data access and client object models for SharePoint Add-ins](secure-data-access-and-client-object-models-for-sharepoint-add-ins.md) +- [Work with external data in SharePoint](work-with-external-data-in-sharepoint.md) +- [OData resources](get-to-know-the-sharepoint-rest-service.md#odata-resources) +- [Develop SharePoint Add-ins](develop-sharepoint-add-ins.md) diff --git a/docs/sp-add-ins/working-with-lists-and-list-items-with-rest.md b/docs/sp-add-ins/working-with-lists-and-list-items-with-rest.md new file mode 100644 index 000000000..7a4d93509 --- /dev/null +++ b/docs/sp-add-ins/working-with-lists-and-list-items-with-rest.md @@ -0,0 +1,638 @@ +--- +title: Working with lists and list items with REST +description: Perform basic create, read, update, and delete (CRUD) operations on lists and list items with the SharePoint REST interface. +ms.date: 06/13/2022 +ms.localizationpriority: high +ms.service: sharepoint +--- + +# Working with lists and list items with REST + +> [!TIP] +> The SharePoint Online (and on-premises SharePoint 2016 and later) REST service supports combining multiple requests into a single call to the service by using the OData `$batch` query option. For details and links to code samples, see [Make batch requests with the REST APIs](make-batch-requests-with-the-rest-apis.md). + +## Prerequisites + +This topic assumes that you're already familiar with the topics [Get to know the SharePoint REST service](get-to-know-the-sharepoint-rest-service.md) and [Complete basic operations using SharePoint REST endpoints](complete-basic-operations-using-sharepoint-rest-endpoints.md). It doesn't provide code snippets. + +## Retrieving lists and list properties with REST + +The following example shows how to **retrieve a specific list if you know its GUID**. + +```http +GET https://{site_url}/_api/web/lists(guid'{list_guid}') +Authorization: "Bearer " + accessToken +Accept: "application/json;odata=verbose" +``` + +> [!NOTE] +> If you want the response in JSON, use `application/json;odata=verbose` in the `Accept` header. +> +> If you want the response in Atom format, use `application/atom+xml` in the `Accept` header. + +The following example shows how to **retrieve a specific list if you know its title**. + +```http +GET https://{site_url}/_api/web/lists/GetByTitle('List Title') +Authorization: "Bearer " + accessToken +Accept: "application/json;odata=verbose" +``` + +The following XML shows an example of the **list properties that are returned when you request the XML content type**. + +```xml + + + true + 100 + 0 + false + 2012-06-26T23:15:58Z + 00000000-0000-0000-0000-000000000000 + A list created by Project Based Retention used to store Project Policy Items. + none + + 0 + true + false + false + false + false + ProjectPolicyItemList + false + false + true + 74de3ff3-029c-42f9-bd2a-1e9463def69d + /_layouts/15/images/itgen.gif + false + false + false + false + false + false + 0 + 2012-06-26T23:15:58Z + 2012-06-26T23:15:59Z + SP.Data.ProjectPolicyItemListItem + false + true + / + true + 00bfea71-de22-43b2-a848-c05709900100 + Project Policy Item List + + +``` + +> [!NOTE] +> The **ListItemEntityTypeFullName** property (**SP.Data.ProjectPolicyItemListItem** in the previous example) is especially important if you want to create and update list items. This value must be passed as the **type** property in the metadata that you pass in the body of the HTTP request whenever you create and update list items. + +## Working with lists by using REST + +The following example shows how to **create a list**. + +```http +POST https://{site_url}/_api/web/lists +Authorization: "Bearer " + accessToken +Accept: "application/json;odata=verbose" +Content-Type: "application/json" +Content-Length: {length of request body as integer} +X-RequestDigest: "{form_digest_value}" + +{ + "__metadata": { + "type": "SP.List" + }, + "AllowContentTypes": true, + "BaseTemplate": 100, + "ContentTypesEnabled": true, + "Description": "My list description", + "Title": "Test" +} +``` + +The following example shows how to **update a list by using the MERGE method**. + +```http +POST https://{site_url}/_api/web/lists(guid'{list_guid}') +Authorization: "Bearer " + accessToken +Accept: "application/json;odata=verbose" +Content-Type: "application/json" +Content-Length: {length of request body as integer} +If-Match: "{etag or *}" +X-HTTP-Method: "MERGE" +X-RequestDigest: "{form_digest_value}" + +{ + "__metadata": { + "type": "SP.List" + }, + "Title": "New title" +} +``` + +The following example shows how to **create a custom field for a list**. + +```http +POST https://{site_url}/_api/web/lists(guid'{list_guid}')/Fields +Authorization: "Bearer " + accessToken +Accept: "application/json;odata=verbose" +Content-Type: "application/json" +Content-Length: {length of request body as integer} +X-RequestDigest: "{form_digest_value}" + +{ + "__metadata": { + "type": "SP.Field" + }, + "Title": "field title", + "FieldTypeKind": FieldType value, + "Required": "true/false", + "EnforceUniqueValues": "true/false", + "StaticName": "field name" +} +``` + +The following example shows how to **delete a list**. + +```http +POST https://{site_url}/_api/web/lists(guid'{list_guid}') +Authorization: "Bearer " + accessToken +Accept: "application/json;odata=verbose" +If-Match: "{etag or *}" +X-HTTP-Method: "DELETE" +X-RequestDigest: "{form_digest_value}" +``` + +### Lookup column changes + +When referring to a lookup column inside a list using REST API, use the display name of the lookup column instead of the internal name. + +```http +GET https://{site_url}/_api/web/lists/getbytitle('ListName')/Items?&$filter=LookupColumnId eq 1 +Authorization: "Bearer " + accessToken +Accept: "application/json;odata=verbose" +``` + +## Working with list items by using REST + +### Retrieve all list items + +The following example shows how to retrieve all of a list's items. + +> [!NOTE] +> +> - The OData `$skip` query parameter doesn't work when querying list items. In many situations, you can use the [$skiptoken](/openspecs/windows_protocols/ms-odata/4dda9434-c2c5-4577-8e01-7bf9e822d90a) option instead. +> - By default, this will return the first 100 items. More information on controlling the number of items, paging, etc. see the documentation on [OData Query operations](use-odata-query-operations-in-sharepoint-rest-requests.md) + +```http +GET https://{site_url}/_api/web/lists/GetByTitle('Test')/items +Authorization: "Bearer " + accessToken +Accept: "application/json;odata=verbose" +``` + +### Retrieve specific list item + +The following example shows how to retrieve a specific list item. + +```http +GET https://{site_url}/_api/web/lists/GetByTitle('Test')/items({item_id}) +Authorization: "Bearer " + accessToken +Accept: "application/json;odata=verbose" +``` + +The following XML shows an example of the list item properties that are returned when you request the XML content type. + +```xml + + + 0 + 1 + 1 + 0x010049564F321A0F0543BA8C6303316C8C0F + an item + 2012-07-24T22:47:26Z + 2012-07-24T22:47:26Z + 11 + 11 + 1.0 + false + eb6850c5-9a30-4636-b282-234eda8b1057 + + +``` + +### Retrieve items as a stream + +Retrieves information about the list and its data. Using this API you can retrieve list items in case they use complex fields such as lookups or managed metadata. + +```http +POST https://{site_url}/_api/web/GetList(@listUrl)/RenderListDataAsStream?@listUrl=%27%2Fsites%2Fteam-a%2Flists%2FList%27 +Authorization: "Bearer " + accessToken +Accept: "application/json;odata=nometadata" +Content-Type: "application/json;odata=nometadata" + +{ + "parameters": { + "AddRequiredFields": "true", + "DatesInUtc": "true", + "RenderOptions": 17 + } +} +``` + +#### RenderListDataAsStream URI parameters + +Following properties can be added as query string parameters to manipulate the returned data. + +Property | Description | Type | Example +-------- | ----------- | ---- | ------- +`CascDelWarnMessage`| Specifies if a message should be displayed if there's a cascade deletion warning | number | `1` +`DrillDown`| Specifies that some groups in a grouped view are expanded. Used with `GroupString`.| string | +`GroupString` | Group identifier used for drill-down feature. | string | +`HasOverrideSelectCommand` | Used to ensure that certain fields are present for proper functioning of the SharePoint ListView control. | string | +`Field`| Specifies a special field that should be included.| string | +`FieldInternalName`| Used to identify a field when a list has an external data source. Also used when filtering on a custom field.| string | +`Filter`| Specifies whether the requested view should have a filter applied.| string | +`FilterData`| Data specified by a particular filter.| string | +`FilterData1` | Data specified by a particular filter.| string | +`FilterData2` | Data specified by a particular filter.| string | +`FilterData3` | Data specified by a particular filter.| string | +`FilterData4` | Data specified by a particular filter.| string | +`FilterData5` | Data specified by a particular filter.| string | +`FilterData6` | Data specified by a particular filter.| string | +`FilterData7` | Data specified by a particular filter.| string | +`FilterData8` | Data specified by a particular filter.| string | +`FilterData9` | Data specified by a particular filter.| string | +`FilterData10` | Data specified by a particular filter.| string | +`FilterField` | A filter field name for a specific filter that is applied to the view.| string | +`FilterField1` | A filter field name for a specific filter that is applied to the view.| string | `ID` +`FilterField2` | A filter field name for a specific filter that is applied to the view.| string | `ID` +`FilterField3` | A filter field name for a specific filter that is applied to the view.| string | `ID` +`FilterField4` | A filter field name for a specific filter that is applied to the view.| string | `ID` +`FilterField5` | A filter field name for a specific filter that is applied to the view.| string | `ID` +`FilterField6` | A filter field name for a specific filter that is applied to the view.| string | `ID` +`FilterField7` | A filter field name for a specific filter that is applied to the view.| string | `ID` +`FilterField8` | A filter field name for a specific filter that is applied to the view.| string | `ID` +`FilterField9` | A filter field name for a specific filter that is applied to the view.| string | `ID` +`FilterField10`| A filter field name for a specific filter that is applied to the view.| string | `ID` +`FilterFields` | Specifies multiple fields that are being filtered on for a multiplier filter. | string | +`FilterFields1`| Specifies multiple fields that are being filtered on for a multiplier filter. | string | +`FilterFields2`| Specifies multiple fields that are being filtered on for a multiplier filter. | string | +`FilterFields3`| Specifies multiple fields that are being filtered on for a multiplier filter. | string | +`FilterFields4`| Specifies multiple fields that are being filtered on for a multiplier filter. | string | +`FilterFields5`| Specifies multiple fields that are being filtered on for a multiplier filter. | string | +`FilterFields6`| Specifies multiple fields that are being filtered on for a multiplier filter. | string | +`FilterFields7`| Specifies multiple fields that are being filtered on for a multiplier filter. | string | +`FilterFields8`| Specifies multiple fields that are being filtered on for a multiplier filter. | string | +`FilterFields9`| Specifies multiple fields that are being filtered on for a multiplier filter. | string | +`FilterFields10`| Specifies multiple fields that are being filtered on for a multiplier filter. | string | +`FilterValue` | The filter value associated with a particular filter. For example, FilterField3 goes with FilterValue3, and so forth. | string | +`FilterValue1` | The filter value associated with a particular filter. For example, FilterField3 goes with FilterValue3, and so forth. | string | `1` +`FilterValue2` | The filter value associated with a particular filter. For example, FilterField3 goes with FilterValue3, and so forth. | string | `1` +`FilterValue3` | The filter value associated with a particular filter. For example, FilterField3 goes with FilterValue3, and so forth. | string | `1` +`FilterValue4` | The filter value associated with a particular filter. For example, FilterField3 goes with FilterValue3, and so forth. | string | `1` +`FilterValue5` | The filter value associated with a particular filter. For example, FilterField3 goes with FilterValue3, and so forth. | string | `1` +`FilterValue6` | The filter value associated with a particular filter. For example, FilterField3 goes with FilterValue3, and so forth. | string | `1` +`FilterValue7` | The filter value associated with a particular filter. For example, FilterField3 goes with FilterValue3, and so forth. | string | `1` +`FilterValue8` | The filter value associated with a particular filter. For example, FilterField3 goes with FilterValue3, and so forth. | string | `1` +`FilterValue9` | The filter value associated with a particular filter. For example, FilterField3 goes with FilterValue3, and so forth. | string | `1` +`FilterValue10`| The filter value associated with a particular filter. For example, FilterField3 goes with FilterValue3, and so forth. | string | `1` +`FilterValues` | Used with FilterFields for multiplier filter. For example, FilterFields3 would go with FilterValues3, and so forth.| string | +`FilterValues1`| Used with FilterFields for multiplier filter. For example, FilterFields3 would go with FilterValues3, and so forth.| string | +`FilterValues2`| Used with FilterFields for multiplier filter. For example, FilterFields3 would go with FilterValues3, and so forth.| string | +`FilterValues3`| Used with FilterFields for multiplier filter. For example, FilterFields3 would go with FilterValues3, and so forth.| string | +`FilterValues4`| Used with FilterFields for multiplier filter. For example, FilterFields3 would go with FilterValues3, and so forth.| string | +`FilterValues5`| Used with FilterFields for multiplier filter. For example, FilterFields3 would go with FilterValues3, and so forth.| string | +`FilterValues6`| Used with FilterFields for multiplier filter. For example, FilterFields3 would go with FilterValues3, and so forth.| string | +`FilterValues7`| Used with FilterFields for multiplier filter. For example, FilterFields3 would go with FilterValues3, and so forth.| string | +`FilterValues8`| Used with FilterFields for multiplier filter. For example, FilterFields3 would go with FilterValues3, and so forth.| string | +`FilterValues9`| Used with FilterFields for multiplier filter. For example, FilterFields3 would go with FilterValues3, and so forth.| string | +`FilterValues10`| Used with FilterFields for multiplier filter. For example, FilterFields3 would go with FilterValues3, and so forth.| string | +`FilterLookupId`| Used when filtering on a lookup field. This is the item id in the foreign list that has a value that is being filtered on.| string | +`FilterLookupId1` | Used when filtering on a lookup field. This is the item id in the foreign list that has a value that is being filtered on.| string | +`FilterLookupId2` | Used when filtering on a lookup field. This is the item id in the foreign list that has a value that is being filtered on.| string | +`FilterLookupId3` | Used when filtering on a lookup field. This is the item id in the foreign list that has a value that is being filtered on.| string | +`FilterLookupId4` | Used when filtering on a lookup field. This is the item id in the foreign list that has a value that is being filtered on.| string | +`FilterLookupId5` | Used when filtering on a lookup field. This is the item id in the foreign list that has a value that is being filtered on.| string | +`FilterLookupId6` | Used when filtering on a lookup field. This is the item id in the foreign list that has a value that is being filtered on.| string | +`FilterLookupId7` | Used when filtering on a lookup field. This is the item id in the foreign list that has a value that is being filtered on.| string | +`FilterLookupId8` | Used when filtering on a lookup field. This is the item id in the foreign list that has a value that is being filtered on.| string | +`FilterLookupId9` | Used when filtering on a lookup field. This is the item id in the foreign list that has a value that is being filtered on.| string | +`FilterLookupId10` | Used when filtering on a lookup field. This is the item id in the foreign list that has a value that is being filtered on.| string | +`FilterOnly`| | string | +`FilterOp` | Filter operator. Used when filtering with other operators than Eq (`Geq`, `Leq` etc.) | string | `Geq` +`FilterOp1`| Filter operator. Used when filtering with other operators than Eq (`Geq`, `Leq` etc.) | string | `Geq` +`FilterOp2`| Filter operator. Used when filtering with other operators than Eq (`Geq`, `Leq` etc.) | string | `Geq` +`FilterOp3`| Filter operator. Used when filtering with other operators than Eq (`Geq`, `Leq` etc.) | string | `Geq` +`FilterOp4`| Filter operator. Used when filtering with other operators than Eq (`Geq`, `Leq` etc.) | string | `Geq` +`FilterOp5`| Filter operator. Used when filtering with other operators than Eq (`Geq`, `Leq` etc.) | string | `Geq` +`FilterOp6`| Filter operator. Used when filtering with other operators than Eq (`Geq`, `Leq` etc.) | string | `Geq` +`FilterOp7`| Filter operator. Used when filtering with other operators than Eq (`Geq`, `Leq` etc.) | string | `Geq` +`FilterOp8`| Filter operator. Used when filtering with other operators than Eq (`Geq`, `Leq` etc.) | string | `Geq` +`FilterOp9`| Filter operator. Used when filtering with other operators than Eq (`Geq`, `Leq` etc.) | string | `Geq` +`FilterOp10`| Filter operator. Used when filtering with other operators than Eq (`Geq`, `Leq` etc.) | string | `Geq` +`ID`| The item id of the item whose information is being sought.| number | +`InplaceSearchQuery`| Search term for a full list search.| string | +`InplaceFullListSearch`| A boolean that specifies whether there's a full list search. | string | +`IsCSR`| Whether this view is a client side rendered view. | string | +`CustomAction` | | string | +`IsGroupRender`| Used to set the IsGroupRender property of the SPView. | string | +`IsRibbon` | | string | +`IsXslView`| Whether this view is an xslt list view.| string | +`List` | | string | +`ListId`| | string | +`ListViewPageUrl` | | string | +`OverrideScope`| Used to override a scope on the rendered view: SPView.Scope| string | +`OverrideSelectCommand`| Used to make sure that certain fields are present in the query regardless of whether they're explicitly included in the view. | string | +`PageFirstRow` | Paging information about the first row that is requested. Used for paging list views. | string | +`PageLastRow` | Paging information about the last row that is requested. Used for paging list views. | string | +`RootFolder`| The folder that the view is displaying.| string | +`SortField`| A field that the view should be sorted on.| string | `ID` +`SortField1`| A field that the view should be sorted on.| string | `ID` +`SortField2`| A field that the view should be sorted on.| string | `ID` +`SortField3`| A field that the view should be sorted on.| string | `ID` +`SortField4`| A field that the view should be sorted on.| string | `ID` +`SortField5`| A field that the view should be sorted on.| string | `ID` +`SortField6`| A field that the view should be sorted on.| string | `ID` +`SortField7`| A field that the view should be sorted on.| string | `ID` +`SortField8`| A field that the view should be sorted on.| string | `ID` +`SortField9`| A field that the view should be sorted on.| string | `ID` +`SortField10` | A field that the view should be sorted on.| string | `ID` +`SortFields`| Specifies the name of the first field to sort by | string | +`SortFieldValues` | Specifies the name of the first field to sort by | string | +`SortDir` | The sort direction of an ad hoc sort that is being applied to the view.| string | `Desc` +`SortDir1` | The sort direction of an ad hoc sort that is being applied to the view.| string | `Desc` +`SortDir2` | The sort direction of an ad hoc sort that is being applied to the view.| string | `Desc` +`SortDir3` | The sort direction of an ad hoc sort that is being applied to the view.| string | `Desc` +`SortDir4` | The sort direction of an ad hoc sort that is being applied to the view.| string | `Desc` +`SortDir5` | The sort direction of an ad hoc sort that is being applied to the view.| string | `Desc` +`SortDir6` | The sort direction of an ad hoc sort that is being applied to the view.| string | `Desc` +`SortDir7` | The sort direction of an ad hoc sort that is being applied to the view.| string | `Desc` +`SortDir8` | The sort direction of an ad hoc sort that is being applied to the view.| string | `Desc` +`SortDir9` | The sort direction of an ad hoc sort that is being applied to the view.| string | `Desc` +`SortDir10`| The sort direction of an ad hoc sort that is being applied to the view.| string | `Desc` +`View` | Specifies the base view that will be used to render the list. | GUID| `3d13559e-3071-5000-76b8-8f1ca6b835f0` +`ViewPath` | Specifies the path of the view that will be used to render the list. If `ViewId` is given, then the `ViewId` will be used and this parameter will be ignored. | string | +`ViewCount`| When multiple list views are on a page, this identifies one of them. | string | +`ViewId`| Specifies the base view that will be used to render the list. ad-hoc parameters will be applied on top of this view. If both `ViewXml` and `BaseViewId` are given, then the `ViewXml` will be used and the ad-hoc parameters will be ignored. | string | +`WebPartId`| The id of the list view web part that is showing this view.| string | + +#### RenderListDataAsStream body parameter properties + +Property | Description | Type | Example +-------- | ----------- | ---- | ------- +`AddRequiredFields` | Specifies if required fields should be returned or not | bool| `true` +`AllowMultipleValueFilterForTaxonomyFields` | Specifies if multi value filtering is allowed for taxonomy fields or not | bool| `true` +`DatesInUtc`| Specifies if we return DateTime field in UTC or local time.| bool| `true` +`ExpandGroups`| Specifies if the grouping should be expanded or not. | bool| `true` +`FirstGroupOnly`| Specifies if only the first group should be returned or not (regardless of view schema). | bool| `true` +`FolderServerRelativeUrl` | Specifies the url to the folder from which to return items.| string| `/sites/team-a/lists/Orders/Europe` +`ImageFieldsToTryRewriteToCdnUrls`| Comma-separated list of field names whose values should be rewritten to CDN URLs | string| `ArticleImage,SecondaryImage` +`OverrideViewXml` | Specifies the override XML to be combined with the View CAML. Applies only to the `Query/Where` part of the View CAML. | string| `3` +`Paging`| Specifies the paging information.| string +`RenderOptions` | Specifies the type of output to return.| SPRenderListDataOptions | See the next section for possible values. You can specify multiple values by adding their values together +`ReplaceGroup`| Specifies if the grouping should be replaced or not to deal with GroupBy throttling. | bool| `true` +`ViewXml` | Specifies the CAML view XML. | string + +##### SPRenderListDataOptions options + +Label | Description | Value +----- | ----------- | ----- +`None`| Return default output| `0` +`ContextInfo` | Return list context information| `1` +`ListData`| Return list data (same as `None`)| `2` +`ListSchema`| Return list schema | `4` +`MenuView`| Return HTML for the list menu| `8` +`ListContentType` | Returns information about list content types. Must be combined with the `ContextInfo` flag | `16` +`FileSystemItemId`| The returned list will have a FileSystemItemId field on each item if possible. Must be combined with the `ListData` flag | `32` +`ClientFormSchema`| Returns the client form schema to add and edit items | `64` +`QuickLaunch` | Returns QuickLaunch navigation nodes | `128` +`Spotlight` | Returns Spotlight rendering information| `256` +`Visualization` | Returns Visualization rendering information| `512` +`ViewMetadata`| Returns view XML and other information about the current view| `1024` +`DisableAutoHyperlink`| Prevents AutoHyperlink from being run on text fields in this query | `2048` +`EnableMediaTAUrls` | Enables URLs pointing to Media TA service, such as `.thumbnailUrl`, `.videoManifestUrl`, `.pdfConversionUrls`| `4096` +`ParentInfo`| Returns parent folder information| `8192` +`PageContextInfo` | Returns page context info for the current list being rendered| `16384` +`ClientSideComponentManifest` | Return client-side component manifest information associated with the list (reserved for future use) | `32768` + +#### Examples + +##### Retrieve item with specific ID + +```http +POST https://{site_url}/sites/team-a/_api/web/GetList(@listUrl)/RenderListDataAsStream?@listUrl=%27%2Fsites%2Fteam-a%2Flists%2FList%27&FilterField1=ID&FilterValue1=1 +Authorization: "Bearer " + accessToken +Accept: "application/json;odata=nometadata" +... +``` + +##### Sort items descending by ID + +```http +POST https://{site_url}/sites/team-a/_api/web/GetList(@listUrl)/RenderListDataAsStream?@listUrl=%27%2Fsites%2Fteam-a%2Flists%2FList%27&SortField=ID&SortDir=Desc +Authorization: "Bearer " + accessToken +Accept: "application/json;odata=nometadata" +... +``` + +##### Retrieve items from the specified folder + +```http +POST https://{site_url}/sites/team-a/_api/web/GetList(@listUrl)/RenderListDataAsStream?@listUrl=%27%2Fsites%2Fteam-a%2Flists%2FOrders%27 +Authorization: "Bearer " + accessToken +Accept: "application/json;odata=nometadata" +Content-Type: "application/json" + +{ + "parameters": { + "FolderServerRelativeUrl": "/sites/team-a/lists/Orders/Europe" + } +} +``` + +##### Retrieve list schema + +```http +POST https://{site_url}/sites/team-a/_api/web/GetList(@listUrl)/RenderListDataAsStream?@listUrl=%27%2Fsites%2Fteam-a%2Flists%2FList%27 +Authorization: "Bearer " + accessToken +Accept: "application/json;odata=nometadata" +Content-Type: "application/json" + +{ + "parameters": { + "RenderOptions": 4 + } +} +``` + +##### Retrieve information about list content types + +```http +POST https://{site_url}/sites/team-a/_api/web/GetList(@listUrl)/RenderListDataAsStream?@listUrl=%27%2Fsites%2Fteam-a%2Flists%2FList%27 +Authorization: "Bearer " + accessToken +Accept: "application/json;odata=nometadata" +Content-Type: "application/json" + +{ + "parameters": { + "RenderOptions": 17 + } +} +``` + +### Create list item + +The following example shows how to create a list item. + +> [!NOTE] +> To do this operation, you must know the **ListItemEntityTypeFullName** property of the list and pass that as the value of **type** in the HTTP request body. Following is a sample rest call to get the ListItemEntityTypeFullName +> +> ```http +> GET https://{site_url}/_api/web/lists/GetByTitle('Test')?$select=ListItemEntityTypeFullName +> Authorization: "Bearer " + accessToken +> Accept: "application/json;odata=nometadata" +> ``` + +```http +POST https://{site_url}/_api/web/lists/GetByTitle('Test')/items +Authorization: "Bearer " + accessToken +Accept: "application/json;odata=verbose" +Content-Type: "application/json;odata=verbose" +Content-Length: {length of request body as integer} +X-RequestDigest: "{form_digest_value}" + +{ + "__metadata": { + "type": "SP.Data.TestListItem" + }, + "Title": "Test" +} +``` + +### Create list item in a folder + +The following example shows how to create a list item in a folder. + +```http +POST https://{site_url}/_api/web/lists/GetByTitle('Test')/AddValidateUpdateItemUsingPath +Authorization: "Bearer " + accessToken +Accept "application/json;odata=nometadata" +Content-Type "application/json;odata=nometadata" +X-RequestDigest "The appropriate digest for current site" + +{ + "listItemCreateInfo": { + "FolderPath": { + "DecodedUrl": "https://{site_url}/lists/Test/Folder/SubFolder" + }, + "UnderlyingObjectType": 0 + }, + "formValues": [ + { + "FieldName": "Title", + "FieldValue": "Item" + } + ], + "bNewDocumentUpdate": false +} +``` + +#### Request property details + +Property | Description +-------- | ----------- +`listItemCreateInfo` | Information about the list and folder where the item should be created +`listItemCreateInfo.FolderPath.DecodedUrl` | Absolute URL of the folder where the item should be created +`listItemCreateInfo.UnderlyingObjectType`| Type of item to create. For more information, see [FileSystemObjectType](/previous-versions/office/developer/sharepoint-2010/ee537053(v=office.14)) +`formValues` | Array of field names and values to set on the newly created item +`bNewDocumentUpdate` | Set to `false` to create a list item + +#### Responses + +| Name | Type |Description| +|--------|---------|-----------| +|200 OK | Boolean |Success | + +```json +{ + "value": [ + { + "ErrorMessage": null, + "FieldName": "Title", + "FieldValue": "Item", + "HasException": false, + "ItemId": 0 + }, + { + "ErrorMessage": null, + "FieldName": "Id", + "FieldValue": "1", + "HasException": false, + "ItemId": 0 + } + ] +} +``` + +The `value` property contains the list of properties that have been set when creating the list item. + +### Update list item + +The following example shows how to update a list item. + +> [!NOTE] +> To do this operation, you must know the **ListItemEntityTypeFullName** property of the list and pass that as the value of **type** in the HTTP request body. + +```http +POST https://{site_url}/_api/web/lists/GetByTitle('Test')/items({item_id}) +Authorization: "Bearer " + accessToken +Accept: "application/json;odata=verbose" +Content-Type: "application/json" +Content-Length: {length of request body as integer} +If-Match: "{etag or *}" +X-HTTP-Method: "MERGE" +X-RequestDigest: "{form_digest_value}" + +{ + "__metadata": { + "type": "SP.Data.TestListItem" + }, + "Title": "TestUpdated" +} +``` + +### Delete list item + +The following example shows how to delete a list item. + +```http +POST https://{site_url}/_api/web/lists/GetByTitle('Test')/items({item_id}) +Authorization: "Bearer " + accessToken +Accept: "application/json;odata=verbose" +Content-Type: "application/json" +If-Match: "{etag or *}" +X-HTTP-Method: "DELETE" +``` + +## Using ETag values to determine document and list item versioning + +The SharePoint REST service, which follows the [OData standard](https://www.odata.org/developers/protocols/operations), uses [Header ETags](https://docs.oasis-open.org/odata/odata/v4.01/cs01/part1-protocol/odata-v4.01-cs01-part1-protocol.html#sec_HeaderETag) of SharePoint lists and list items. To check on an item's version when you perform a **PUT**, **MERGE**, or **DELETE** request, specify an **ETag** in the **If-Match** HTTP request header. + +If the **ETag** you specify in your request doesn't match the **ETag** of the document or list item on the server, the REST service returns a 412 exception, per the OData specification. + +- To force an overwrite of the item regardless of version, set the **ETag** value to **"*"**. +- If you do not specify an **ETag**, SharePoint overwrites the item regardless of version. + +Within SharePoint, ETags apply only to SharePoint lists and list items. + +## See also + +- [Get to know the SharePoint REST service](get-to-know-the-sharepoint-rest-service.md) +- [SharePoint-Add-in-REST-OData-BasicDataOperations](https://github.com/OfficeDev/SharePoint-Add-in-REST-OData-BasicDataOperations) +- [SharePoint: Perform basic data access operations on files and folders by using REST](/sharepoint/dev/sp-add-ins/working-with-folders-and-files-with-rest) +- [Secure data access and client object models for SharePoint Add-ins](secure-data-access-and-client-object-models-for-sharepoint-add-ins.md) +- [Work with external data in SharePoint](work-with-external-data-in-sharepoint.md) +- [OData resources](get-to-know-the-sharepoint-rest-service.md#odata-resources) +- [Develop SharePoint Add-ins](develop-sharepoint-add-ins.md) diff --git a/docs/spfx/build-for-teams-configure-in-teams.md b/docs/spfx/build-for-teams-configure-in-teams.md new file mode 100644 index 000000000..cd3dae93c --- /dev/null +++ b/docs/spfx/build-for-teams-configure-in-teams.md @@ -0,0 +1,68 @@ +--- +title: Configure SharePoint Framework web parts in Microsoft Teams +description: To accommodate your users' preferences, you can let them configure your web parts when used in Microsoft Teams. +ms.date: 06/15/2020 +ms.localizationpriority: medium +--- + +# Configure SharePoint Framework web parts in Microsoft Teams + +To accommodate your users' preferences, you can let them configure your web parts when used in Microsoft Teams. Depending if you exposed your web parts as Teams tabs or personal apps, there are different ways to implement configuration capabilities in your web part. + +> [!TIP] +> To see how to use the different concepts described in this article, see the sample [Leads application](https://github.com/pnp/sp-dev-solutions/tree/master/solutions/LeadsLOBSolution) on GitHub. + +## Configure Microsoft Teams tabs built using SharePoint Framework + +Typically, when building Microsoft Teams tab, you need to [build custom UI to allow users to configure your tab](/microsoftteams/platform/tabs/how-to/create-tab-pages/configuration-page). Additionally, you need to write code to store and load configuration values as selected by the user. + +When building tabs using SharePoint Framework, the generated tab uses the [web part property pane](web-parts/guidance/integrate-web-part-properties-with-sharepoint.md) to let users configure the tab. This saves you a lot of effort. Not only you don’t need to build and maintain a separate configuration UI but you also don’t need to implement any code responsible for storing and managing the settings. All of that is handled automatically for you by SharePoint Framework. + +## Configure Microsoft Teams personal apps built using SharePoint Framework + +Microsoft Teams personal apps don’t offer any infrastructure for implementing configuration. Instead, following the pattern recommended by Microsoft Teams, personal app’s [settings should be exposed in a separate tab](/microsoftteams/platform/concepts/design/personal-apps). + +![Personal app with multiple tabs including settings built using SharePoint Framework](../images/build-for-teams/build-for-teams-personal-app.png) + +Translating this to your SharePoint Framework solution, it means building a separate web part that contains the configuration UI and which will be used only in the context of the personal app, defining a storage for user’s configuration and extending the personal app definition to contain multiple tabs. + +### Personal app configuration UI web part + +Each tab in a personal app is mapped to a URL. The easiest way to build UI for configuring your SharePoint Framework web part exposed as a personal app, is by building a separate web part with the configuration UI. This will allow you to optimize the UI for use in the context of the personal app and keep this code separate from your web part. + +Since the personal app configuration UI web part is not meant to be used outside of the personal app, in its manifest, you should set the `supportedHosts` property to an empty array. + +![The supportedHosts property of a SharePoint Framework web part used as a personal app configuration UI](../images/build-for-teams/build-for-teams-manifest-settings-webpart.png) + +The reason you want the `supportedHosts` property to be empty is to prevent the web part from being used in SharePoint but also not include it in the autogenerated Teams manifest. By default, each web part that contains the `TeamsTab` or `TeamsPersonalApp` value in the manifest is included in the generated Teams manifest as a separate Microsoft Teams app. In this case however, you want the personal app to consist of multiple tabs, each pointing to a different web part. This can be done only by manually updating the manifest yourself. + +To add a tab to your personal app and have it point to another web part, in the Teams manifest defined in the **teams/manifest.json** file, navigate to the `staticTabs` section and copy the existing entry. In the copied entry, update values of the `entityId` and `name` properties. In the `contentUrl` property, update the value of the `componentId` query string parameter so that it matches the ID of your settings web part as defined in its manifest. + +![Microsoft Teams app's manifest defining a personal app with multiple tabs pointing to SharePoint Framework web parts](../images/build-for-teams/build-for-teams-teams-manifest-personalapp-multipletabs.png) + +### Choose the location to store user’s configuration + +By default, web parts’ configuration is shared and the same for all users. Personal Teams apps are however meant to be installed, configured and used by individuals. As such, you need to have a way to store their preferences. + +#### Store user configuration in the User Profile Service + +In the past, a common way to store user-specific information in SharePoint, was by adding a custom property to the user profile service and storing the configuration as a serialized string in there. The problem with using the user profile service for this purpose is that you can’t automatically generate new user profile properties which complicates the deployment of your application. + +#### Store user configuration in a custom list + +Alternatively, you could store user settings in a list. You could create a hidden list in the root SharePoint site and configure it so that users can see only their items. The downside of this approach is that each time your web part starts you need to check if the list and the settings for the current user exist and gracefully handle errors in case they don’t. Additionally, when loading the configuration UI you would need to check if the list exists and provision it, along with all its settings if necessary. + +#### Store user configuration in application’s personal folder + +One of the less-known options for persisting application- and user-specific configuration is using the [application’s personal folder](/graph/api/drive-get-specialfolder?tabs=http). Application’s specific folder is located in the user’s OneDrive for Business site. Each application gets a designated folder in which it can store any number of files. + +![Application’s personal folder created for SharePoint Framework applications](../images/build-for-teams/build-for-teams-application-personal-folder.png) + +You can think of the application’s personal folder as a configuration folder of a desktop application on your disk, but then stored in OneDrive for Business and available on every device you use. + +> [!TIP] +> Application’s personal folders are created per Azure AD application, so in the context of SharePoint Framework, all SharePoint Framework solutions will share the root application folder. To avoid collisions with other solutions, you should consider creating a subfolder for your application. + +From the technical point of view, the application’s personal folder is a folder in a SharePoint document library, and you can store any number of files and folders inside. When persisting your application’s configuration to the application’s personal folder, you would serialize your settings as configured by the user and write the serialized data to a file in your folder. + +What’s convenient about using the application’s personal folder is that it’s automatically created if it doesn’t exist, data for each user is stored in their own OneDrive for Business meaning other users cannot see or tamper with their settings and it doesn’t require you to know any specific URLs because you can conveniently access it using Microsoft Graph. Should anything go wrong, user can navigate to their OneDrive for Business site and delete the application’s configuration to reset its state. diff --git a/docs/spfx/build-for-teams-considerations.md b/docs/spfx/build-for-teams-considerations.md new file mode 100644 index 000000000..5cdece1f9 --- /dev/null +++ b/docs/spfx/build-for-teams-considerations.md @@ -0,0 +1,43 @@ +--- +title: Considerations for building for Microsoft Teams using SharePoint Framework +description: There are a number of things that you should take into account when building for Microsoft Teams using SharePoint Framework +ms.date: 03/08/2023 +ms.localizationpriority: medium +--- + +# Considerations for building for Microsoft Teams using SharePoint Framework + +While using SharePoint Framework to build for Microsoft Teams offers you benefits, there are some considerations that you should take into account before building your next application. + +> [!TIP] +> To see how to use the different concepts described in this article, see the sample [Leads application](https://github.com/pnp/sp-dev-solutions/tree/master/solutions/LeadsLOBSolution) on GitHub. + +## Globally deploy the SharePoint Framework solution package + +When using SharePoint Framework to build web parts that will be exposed in Microsoft Teams you should allow the solution to be globally deployed. This setting is controlled when creating the project but can also be adjusted later in the **package-solution.json** file by setting the `skipFeatureDeployment` property to `true`. + +When the solution is globally deployed in your tenant, users can add tabs to any channel and install personal apps. + +## Expose existing application in Microsoft Teams + +If you have an existing web application, most likely you will not migrate it to SharePoint Framework. Since the application is already working, the easiest way to expose it in Microsoft Teams is by [creating a manifest for it](/microsoftteams/platform/tabs/what-are-tabs). + +Depending how your application is built, you might need to ensure that users can correctly sign into your application and that the application can securely access its APIs. When users work with your application in Microsoft Teams, the application loads inside an `