diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 5c568ff57..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: @@ -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 `master` branch +## Switch to `main` branch -In order to add your changes, you will need to do those in the `master` 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 `master` branch: +Type the following command in the console to switch to `main` branch: ``` -git checkout master +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 `master` 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 `master` 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 `master` 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 a5c4964e7..000000000 --- a/.github/ISSUE_TEMPLATE.md +++ /dev/null @@ -1,51 +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. -> -> _(DELETE THIS PARAGRAPH AFTER READING)_ -> - -#### Category -- [ ] Question -- [ ] Typo -- [ ] Bug -- [ ] Additional article idea - -> 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. -> -> If you are planning to share a new feature request (enhancement / suggestion), please use SP Dev UserVoice at http://aka.ms/sp-dev-uservoice. (DELETE THIS PARAGRAPH AFTER READING) -> -> _(DELETE THIS PARAGRAPH AFTER READING)_ -> - -#### 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. -> -> _(DELETE THIS PARAGRAPH AFTER READING)_ -> - -#### 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. -> -> _(DELETE THIS PARAGRAPH AFTER READING)_ -> - -#### 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. -> -> _(DELETE THIS PARAGRAPH AFTER READING)_ -> - -#### Submission Guidelines - -> - 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. -> -> _(DELETE THIS PARAGRAPH AFTER READING)_ -> - -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 1939136f0..99aeec9af 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,22 +1,30 @@ -#### Category +## Category + - [ ] Content fix - [ ] New article -- Related issues: fixes #X, partially #Y, mentioned in #Z +- [x] Example checked item (*delete this line*) + +> **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 + +- fixes #issuenumber +- partially #issuenumber +- mentioned in #issuenumber -> 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. -> -> _(DELETE THIS PARAGRAPH AFTER READING)_ +> **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? +## What's in this Pull Request? -> Please describe the changes in this PR. Sample description or details around bugs which are being fixed. -> -> _(DELETE THIS PARAGRAPH AFTER READING)_ +> **DELETE THIS LINE BEFORE SUBMITTING** | *Please describe the changes in this PR. Sample description or details around bugs which are being fixed.* -#### Guidance +## Submission guidelines -> *Please update this PR information accordingly. We'll use this as part of our release notes in monthly communications.* -> -> *Please target your PR to 'master' branch. Released documents are in `live` branch.* -> -> _(DELETE THIS PARAGRAPH AFTER READING)_ \ No newline at end of file +> - **!!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/.openpublishing.build.ps1 b/.openpublishing.build.ps1 deleted file mode 100644 index aadef7620..000000000 --- a/.openpublishing.build.ps1 +++ /dev/null @@ -1,17 +0,0 @@ -param( - [string]$buildCorePowershellUrl = "https://opbuildstorageprod.blob.core.windows.net/opps1container/.openpublishing.buildcore.ps1", - [string]$parameters -) -# Main -$errorActionPreference = 'Stop' - -# Step-1: Download buildcore script to local -echo "download build core script to local with source url: $buildCorePowershellUrl" -$repositoryRoot = Split-Path -Parent $MyInvocation.MyCommand.Definition -$buildCorePowershellDestination = "$repositoryRoot\.openpublishing.buildcore.ps1" -Invoke-WebRequest $buildCorePowershellUrl -OutFile "$buildCorePowershellDestination" - -# Step-2: Run build core -echo "run build core script with parameters: $parameters" -& "$buildCorePowershellDestination" "$parameters" -exit $LASTEXITCODE diff --git a/.openpublishing.publish.config.json b/.openpublishing.publish.config.json index b4348cb30..f3522487f 100644 --- a/.openpublishing.publish.config.json +++ b/.openpublishing.publish.config.json @@ -24,12 +24,12 @@ ], "notification_subscribers": [ "vesaj@microsoft.com", - "bjansen@microsoft.com", - "v-licapu@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": "master", + "git_repository_branch_open_to_public_contributors": "main", "skip_source_output_uploading": false, "need_preview_pull_request": true, "contribution_branch_mappings": {}, @@ -37,19 +37,19 @@ { "path_to_root": "_themes", "url": "https://github.com/Microsoft/templates.docs.msft", - "branch": "master", + "branch": "main", "branch_mapping": {} }, { "path_to_root": "_themes.pdf", "url": "https://github.com/Microsoft/templates.docs.msft.pdf", - "branch": "master", + "branch": "main", "branch_mapping": {} }, { - "path_to_root": "PnP-Tools", - "url": "https://github.com/SharePoint/PnP-Tools.git", - "branch": "master", + "path_to_root": "sp-dev-modernization", + "url": "https://github.com/SharePoint/sp-dev-modernization.git", + "branch": "dev", "branch_mapping": {} } ], @@ -60,11 +60,11 @@ ] }, "need_generate_pdf_url_template": true, - "Targets": { - "Pdf": { - "template_folder": "_themes.pdf" - } - }, + "Targets": { + "Pdf": { + "template_folder": "_themes.pdf" + } + }, "JoinTOCPlugin": [ { "ConceptualTOC": "/docs/toc.yml", @@ -80,4 +80,4 @@ "nuget_feed": "https://www.myget.org/F/op/api/v2" } ] -} \ No newline at end of file +} 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.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/README.md b/README.md index af3f43ef8..4e77f8fcb 100644 --- a/README.md +++ b/README.md @@ -1,93 +1,55 @@ -# Welcome to the SharePoint Framework! +# 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. -* [Official SharePoint Framework Documentation](http://aka.ms/spfx) +* [Official SharePoint Framework Documentation](https://aka.ms/spfx) -This repository contains the raw documents published to docs.microsoft.com site. +This repository contains the raw documents published to Microsoft Docs. ## Questions & Help 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. -We’ll also monitor [#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. - -You can also tweet / follow [@officedev](https://twitter.com/officedev) or [@officedevpnp](https://twitter.com/officedevpnp). +You can also tweet / follow [@Microsoft365Dev](https://twitter.com/Microsoft365Dev) or [@m365pnp](https://twitter.com/m365pnp). ## SharePoint Framework Releases -* **September 5, 2018** - * **SPFx v1.6** - [See the release notes here](https://github.com/SharePoint/sp-dev-docs/wiki/SharePoint-Framework-v1.6-release-notes) - -* **June 26, 2018** - * **SPFx v1.5.1** - [See the release notes here](https://github.com/SharePoint/sp-dev-docs/wiki/Release-Notes-for-SPFx-Package-Version-1.5.1) - -* **June 5, 2018** - * **SPFx v1.5** - [See the release notes here](https://github.com/SharePoint/sp-dev-docs/wiki/Release-Notes-for-SharePoint-Framework-Package-v1.5) - -* **February 15, 2018** - * **SPFx v1.4.1** [See the release notes here](https://github.com/SharePoint/sp-dev-docs/wiki/Release-Notes-for-SPFx-Package-Version-1.4.1) - -* **December 7, 2017** - * **SPFx v1.4**. [See the release notes here](https://github.com/SharePoint/sp-dev-docs/wiki/Release-Notes-for-SPFx-Package-Version-1.4) - -* **September 25, 2017** - * **GA of Extensions and SPFx v1.3**. -* **June 6, 2017** - * **Dev Preview of extensions is available**. [See the release notes here](https://github.com/SharePoint/sp-dev-docs/wiki/Release-Notes---Extensions-Dev-Preview-Drop-1) +Review all the SPFx releases here from the [initial GA release in February 2017](https://learn.microsoft.com/sharepoint/dev/spfx/roadmap) -* **Feb 22, 2017** - * **GA is available**. [See the release notes here](https://github.com/SharePoint/sp-dev-docs/wiki/Release-Notes-GA) - -* **Jan 9, 2017** - * **RC0 is available**. [See the release notes here](https://github.com/SharePoint/sp-dev-docs/wiki/Release-Notes-RC0) - -* **Aug 17, 2016** - * **Drop 1 is available**. [See the release notes here](https://github.com/SharePoint/sp-dev-docs/wiki/Drop-1) - ## Get Started -* [Setup your Office 365 Developer Tenant](https://docs.microsoft.com/en-us/sharepoint/dev/spfx/set-up-your-developer-tenant) -* [Setup your Machine](https://docs.microsoft.com/en-us/sharepoint/dev/spfx/set-up-your-development-environment) -* [Go build your first web part](https://docs.microsoft.com/en-us/sharepoint/dev/spfx/web-parts/get-started/build-a-hello-world-web-part) - -## Reference -* [sp-application-base](https://docs.microsoft.com/en-us/javascript/api/sp-application-base) -* [sp-component-base](https://docs.microsoft.com/en-us/javascript/api/sp-component-base) -* [sp-core-library](https://docs.microsoft.com/en-us/javascript/api/sp-core-library) -* [sp-dialog](https://docs.microsoft.com/en-us/javascript/api/sp-dialog) -* [sp-extension-base](https://docs.microsoft.com/en-us/javascript/api/sp-extension-base) -* [sp-http](https://docs.microsoft.com/en-us/javascript/api/sp-http) -* [sp-listview-extensibility](https://docs.microsoft.com/en-us/javascript/api/sp-listview-extensibility) -* [sp-odata-types](https://docs.microsoft.com/en-us/javascript/api/sp-odata-types) -* [sp-page-context](https://docs.microsoft.com/en-us/javascript/api/sp-page-context) -* [sp-webpart-base](https://docs.microsoft.com/en-us/javascript/api/sp-webpart-base) +* [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](https://docs.microsoft.com/en-us/sharepoint/dev/spfx/sharepoint-framework-overview) -* [Design Great Web Parts](https://docs.microsoft.com/en-us/sharepoint/dev/design/design-guidance-overview) -* [API Docs](https://docs.microsoft.com/en-us/javascript/api/sp-application-base) +* [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), [@OfficeDev](https://twitter.com/officedev) and [@OfficeDevPnP](https://twitter.com/officedevpnp) 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 -The SharePoint Framework is now generally available at Office 365. -- [SharePoint Framework reaches general availability—build and deploy engaging web parts today](https://blogs.office.com/2017/02/23/sharepoint-framework-reaches-general-availability-build-and-deploy-engaging-web-parts-today/) +## 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! + +* [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, @OfficeDevPnP 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 index a0bd09d68..25ca6dcd6 100644 --- a/ThirdPartyNotices +++ b/ThirdPartyNotices @@ -9,7 +9,7 @@ may be either trademarks or registered trademarks of Microsoft in the United Sta 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/en-us/ +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](http://msdn.microsoft.com/en-us/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) - - - +--- +title: Work with the cross-domain library across different Internet Explorer security zones in SharePoint Add-ins +description: Use the cross-domain library in SharePoint when the host web and add-in pages are in different security zones in Internet Explorer. +ms.date: 09/26/2023 +ms.localizationpriority: high +ms.service: sharepoint +--- + + +# Work with the cross-domain library across different Internet Explorer security zones in SharePoint Add-ins + +[!INCLUDE [sp-add-in-deprecation](../../includes/snippets/sp-add-in-deprecation.md)] + +If you are using the SharePoint cross-domain library for your add-ins, you should be aware of how security zones work in Internet Explorer. Your add-in may encounter some communication issues if the SharePoint website and the add-in are in different zones. This article explains what happens when you use the cross-domain library in different Internet Explorer security zones. + + + +## Cross-zone scenarios in Internet Explorer using the SharePoint cross-domain library + +For security reasons, Internet Explorer prevents pages that are on different integrity levels (also known as security zones) to share cookies because each integrity level has its own cookie store. The integrity level of a page is determined by its top-most page, and any frame within that page shares the same integrity level. For more information, see [Beware Cookie Sharing in Cross-Zone Scenarios](https://blogs.msdn.microsoft.com/ieinternals/2011/03/10/beware-cookie-sharing-in-cross-zone-scenarios/). + +The SharePoint cross-domain library uses a hidden **IFrame** and a client-side proxy page hosted on SharePoint to enable client-side communication by using JavaScript. The cross-domain library is available when you reference the sp.requestexecutor.js file in your pages. For more information, see [Access SharePoint data from add-ins using the cross-domain library](access-sharepoint-data-from-add-ins-using-the-cross-domain-library.md). + +When the remote add-in page and SharePoint website are in different security zones, the authorization cookies cannot be sent. If there are no authorization cookies, and the **IFrame** tries to load the proxy page, it is redirected to the SharePoint sign-in page. The SharePoint sign-in page cannot be contained in an **IFrame** for security reasons. In these scenarios, the library cannot load the proxy page, and communication with SharePoint is not possible. + +The following diagram shows a cross-zone scenario in which the proxy page cannot be loaded. The top page puts the frame in the same security zone as `http://remoteserver/remotepage.html`. The proxy page does not load. + +**Cross-zone scenario where the proxy page cannot be loaded** + +![Cross-zone scenario, proxy page cannot be loaded](../images/Crosszone_loaderror.png) + +The following are some examples in which the cross-domain library may not be able to load the proxy page: + +- Your customers are using SharePoint Online, and your remote add-in page is hosted on an intranet server. This scenario is prone to the proxy page loading issue because the SharePoint Online URL is not usually in the local intranet zone. This is a very common scenario during initial development of an add-in because you may be using IIS Express or another local server to host your page without a fully qualified internet domain. + +- Your customers are using SharePoint on-premises with forms-based authentication, and your remote page is hosted on a cloud service (for example, Microsoft Azure). + + + + + +## Handling cross-zone scenarios in SharePoint Add-ins + +There are a few ways to solve this problem during both add-in development (strongly recommended) and add-in run time. + +### Best practice: Use the apphost pattern + +To handle a cross-zone scenario, we recommend that you have an apphost page in SharePoint. The apphost page is a SharePoint page that contains the remote page in an **IFrame**. Everything inside the **IFrame** on the apphost page exists in the same security zone as the add-in web. The cross-domain library on the remote page can receive the authorization cookies and loads the proxy page successfully. + +The following diagram shows a cross-zone scenario being handled by using the apphost page pattern. + +**Cross-zone scenario handling by using the apphost page pattern** + +![Cross-zone scenario handling by using the apphost](../images/Crosszone_loadsuccess.png) + +The code required for the apphost page is simple. The main portion of the apphost page is an **SPAppIFrame** element. You must use CSS to make the **IFrame** invisible so that it doesn't interfere with your add-in. + +The following markup is an example of a simple apphost page. The markup performs the following tasks: + +- Declares directives needed when using SharePoint components. + +- Declares styles to make the **IFrame** invisible. + +- Declares the **SPAppIFrame** and sets the target to the add-in start page. + + +```HTML +<%@ Page + Inherits="Microsoft.SharePoint.WebPartPages.WebPartPage, Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" + language="C#" %> +<%@ Register + Tagprefix="SharePoint" + Namespace="Microsoft.SharePoint.WebControls" + Assembly="Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %> +<%@ Register + Tagprefix="Utilities" + Namespace="Microsoft.SharePoint.Utilities" + Assembly="Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %> +<%@ Register + Tagprefix="WebPartPages" + Namespace="Microsoft.SharePoint.WebPartPages" + Assembly="Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %> + + + + Your add-in page title + + + + + + + + +``` + +
+ +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 index ce261240c..cf4666d49 100644 --- 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 @@ -1,345 +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: 4/19/2018 -ms.prod: sharepoint +ms.date: 01/12/2023 +ms.localizationpriority: high +ms.service: sharepoint --- - # Working with folders and files 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). +> [!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" ``` -url: http://site url/_api/web/GetFolderByServerRelativeUrl('/Shared Documents') -method: GET -headers: - Authorization: "Bearer " + accessToken - accept: "application/json;odata=verbose" or "application/atom+xml" - -``` - -
The following XML shows an example of **folder properties that are returned when you request the XML content type**. -```XML +```xml - -0 -Shared Documents -/Shared Documents - - + + 0 + Shared Documents + /Shared Documents + + ``` -
- The following example shows how to **create a folder**. -``` -url: http://site url/_api/web/folders -method: POST -body: { '__metadata': { 'type': 'SP.Folder' }, 'ServerRelativeUrl': '/document library relative url/folder name'} -Headers: - Authorization: "Bearer " + accessToken - X-RequestDigest: form digest value - accept: "application/json;odata=verbose" - content-type: "application/json;odata=verbose" - content-length:length of post body +```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**. -The following example shows how to **update a folder by using the MERGE method**. +First, obtain the folder's OData type with a GET request. -``` -url: http://site url/_api/web/GetFolderByServerRelativeUrl('/Folder Name') -method: POST -body: { '__metadata': { 'type': 'SP.Folder' }, 'Name': 'New name' } -Headers: - Authorization: "Bearer " + accessToken - X-RequestDigest: form digest value - "IF-MATCH": etag or "*" - "X-HTTP-Method":"MERGE", - accept: "application/json;odata=verbose" - content-type: "application/json;odata=verbose" - content-length:length of post body +```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: -The following example shows how to **delete a folder**. - -``` -url: http://site url/_api/web/GetFolderByServerRelativeUrl('/Folder Name') -method: POST -Headers: - Authorization: "Bearer " + accessToken - X-RequestDigest: form digest value - "IF-MATCH": etag or "*" - "X-HTTP-Method":"DELETE" +```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**. -``` -url: http://site url/_api/web/GetFolderByServerRelativeUrl('/Folder Name')/Files +```http +GET https://{site_url}/_api/web/GetFolderByServerRelativeUrl('Folder Name')/Files method: GET -headers: - Authorization: "Bearer " + accessToken - accept: "application/json;odata=verbose" or "application/atom+xml" - +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 ``` -url: http://site url/_api/web/GetFolderByServerRelativeUrl('/Folder Name')/Files('file name')/$value -method: GET -headers: - Authorization: "Bearer " + accessToken -``` - -
You can also **retrieve a file when you know its URL**, as in the following example. -``` -url: http://site url/_api/web/GetFileByServerRelativeUrl('/Folder Name/file name')/$value -method: GET -headers: - Authorization: "Bearer " + accessToken -``` +```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"; -The following example shows how to **create a file and add it to a folder**. + //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(); +} ``` -url: http://site url/_api/web/GetFolderByServerRelativeUrl('/Folder Name')/Files/add(url='a.txt',overwrite=true) -method: POST -body: "Contents of file" -Headers: - Authorization: "Bearer " + accessToken - X-RequestDigest: form digest value - content-length:length of post body -``` -
+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] + +> [!NOTE] > **PUT** is the only method that you can use to update a file. The **MERGE** method is not allowed. -``` -url: http://site url/_api/web/GetFileByServerRelativeUrl('/Folder Name/file name')/$value -method: POST -body: "Contents of file." -Headers: - Authorization: "Bearer " + accessToken - X-RequestDigest: form digest value - X-HTTP-Method:"PUT" - content-length:length of post body -``` +```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:///_api/web/lists/getbytitle('Documents')/items()`. 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). +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. +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}" ``` -url: http://site url/_api/web/GetFileByServerRelativeUrl('/Folder Name/file name')/CheckOut(), -method: POST -headers: - Authorization: "Bearer " + accessToken - X-RequestDigest: form digest value -``` - -
The following example shows how to **check in a file**. -``` -url: http://site url/_api/web/GetFileByServerRelativeUrl('/Folder Name/file name')/CheckIn(comment='Comment',checkintype=0) -method: POST -headers: - Authorization: "Bearer " + accessToken - X-RequestDigest: form digest value +```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}" ``` -url: http://site url/_api/web/GetFileByServerRelativeUrl('/Folder Name/file name') -method: POST -headers: - Authorization: "Bearer " + accessToken - X-RequestDigest: form digest value - IF-MATCH: etag or "*" - X-HTTP-Method:"DELETE" - -``` - -
- - ## 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). +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] + +> [!WARNING] > This approach works only with Internet Explorer 10 and the latest versions of other browsers. -``` -url: http://site url/_api/web/GetFolderByServerRelativeUrl('/Folder Name')/Files/Add(url='file name', overwrite=true) -method: POST -body: contents of binary file -headers: - Authorization: "Bearer " + accessToken - X-RequestDigest: form digest value - content-type: "application/json;odata=verbose" - content-length:length of post body -``` +```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 cross-domain library**. +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 ro; -if (document.getElementById("TxtViaUrl").value.length > 0) { -ro = new SP.RequestExecutor(document.getElementById("TxtWebUrl").value, document.getElementById("TxtViaUrl").value); -} -else { -ro = 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" -}; -ro.executeAsync(info); + 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**. -``` -url: http://site url/_api/web/lists/getbytitle('list title')/items(item id)/AttachmentFiles/ -method: GET -headers: - Authorization: "Bearer " + accessToken - accept: "application/json;odata=verbose" or "application/atom+xml" - +```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" ``` -url: http://site url/_api/web/lists/getbytitle('list title')/items(item id)/AttachmentFiles('file name')/$value -method: GET -headers: - Authorization: "Bearer " + accessToken - accept: "application/json;odata=verbose" or "application/atom+xml" - -``` - -
The following example shows how to **create a file attachment to a list item**. -``` -url: http://site url/_api/web/lists/getbytitle('list title')/items(item id)/AttachmentFiles/ add(FileName='file name') -method: POST -headers: - Authorization: "Bearer " + accessToken - body: "Contents of file." - X-RequestDigest: form digest value - content-length:length of post body -``` +```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] + +> [!NOTE] > **PUT** is the only method that you can use to update a file. The **MERGE** method is not allowed. -``` -url: http://site url/_api/web/lists/getbytitle('list title')/items(item id)/AttachmentFiles('file name')/$value -method: POST -body: "Contents of file." -headers: - Authorization: "Bearer " + accessToken - "X-HTTP-Method":"PUT" - X-RequestDigest: form digest value - content-length:length of post body +```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) -- [REST API reference and samples](https://msdn.microsoft.com/library) +- [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) -- [SharePoint: Perform basic data access operations on files and folders by using REST](http://code.msdn.microsoft.com/SharePoint-Perform-ab9c4ae5) - [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) +- [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 index cf9406c6b..7a4d93509 100644 --- 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 @@ -1,650 +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: 4/19/2018 -ms.prod: 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 are 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 does not 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**. - -``` -url: http://site url/_api/web/lists(guid'list GUID'), -method: GET -Headers: - Authorization: "Bearer " + accessToken - accept: "application/json;odata=verbose" or "application/atom+xml" - -``` - - -> [!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**. - -``` -url: http://site url/_api/web/lists/GetByTitle('Test') -method: GET -Headers: - Authorization: "Bearer " + accessToken - accept: "application/json;odata=verbose" or "application/atom+xml" - -``` - -
- -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**. - -``` -url: http://site url/_api/web/lists -method: POST -body: { '__metadata': { 'type': 'SP.List' }, 'AllowContentTypes': true, 'BaseTemplate': 100, - 'ContentTypesEnabled': true, 'Description': 'My list description', 'Title': 'Test' } -Headers: - Authorization: "Bearer " + accessToken - X-RequestDigest: form digest value - accept: "application/json;odata=verbose" - content-type: "application/json;odata=verbose" - content-length:length of post body -``` - -
- -The following example shows how to **update a list by using the MERGE method**. - -``` -url: http://site url/_api/web/lists(guid'list GUID') -method: POST -body: { '__metadata': { 'type': 'SP.List' }, 'Title': 'New title' } -Headers: - Authorization: "Bearer " + accessToken - X-RequestDigest: form digest value - IF-MATCH": etag or "*" - X-HTTP-Method: MERGE, - accept: "application/json;odata=verbose" - content-type: "application/json;odata=verbose" - content-length:length of post body -``` - -
- -The following example shows how to **create a custom field for a list**. - -``` -Url: url: http://site url/_api/web/lists(guid'list GUID')/Fields -Method:POST -Body: { '__metadata': { 'type': 'SP.Field' }, 'Title': 'field title', 'FieldTypeKind': FieldType value,'Required': 'true/false', 'EnforceUniqueValues': 'true/false','StaticName': 'field name'} -Headers: - Authorization: "Bearer " + accessToken - X-RequestDigest: form digest value - content-type: "application/json;odata=verbose" - content-length:length of post body -``` - -
- -The following example shows how to **delete a list**. - -``` -url: http://site url/_api/web/lists(guid'list GUID') -method: POST -Headers: - Authorization: "Bearer " + accessToken - X-RequestDigest: form digest value - IF-MATCH: etag or "*" - X-HTTP-Method: DELETE - -``` - -
- - - -## 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 option does not work when querying list items. In may situations, you can use the [$skiptoken](http://msdn.microsoft.com/library/4dda9434-c2c5-4577-8e01-7bf9e822d90a.aspx) option instead. - -``` -url: http://site url/_api/web/lists/GetByTitle('Test')/items -method: GET -headers: - Authorization: "Bearer " + accessToken - accept: "application/json;odata=verbose" or "application/atom+xml" - -``` - -### Retrieve specific list item - -The following example shows how to retrieve a specific list item. - -``` -url: http://site url/_api/web/lists/GetByTitle('Test')/items(item id) -method: GET -headers: - Authorization: "Bearer " + accessToken - accept: "application/json;odata=verbose" or "application/atom+xml" - -``` - -
- -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. - -```text -POST /_api/web/GetList(@listUrl)/RenderListDataAsStream?@listUrl=%27%2Fsites%2Fteam-a%2Flists%2FList%27 -``` - -#### 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 is a cascade deletion warning|number|`1` -`DrillDown`|Specifies that some groups in a grouped view is 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 is 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 are 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 parameters 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| - -#### Request headers - -Header|Value --------|----- -Accept|application/json;odata=nometadata -Content-Type|application/json;odata=nometadata - -#### Request body - -```json -{ - "parameters": { - "AddRequiredFields": "true", - "DatesInUtc": "true", - "RenderOptions": 17 - } -} -``` - -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 - -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** - -```text -POST https://contoso.sharepoint.com/sites/team-a/_api/web/GetList(@listUrl)/RenderListDataAsStream?@listUrl=%27%2Fsites%2Fteam-a%2Flists%2FList%27&FilterField1=ID&FilterValue1=1 -accept: application/json;odata=nometadata -``` - -**Sort items descending by ID** - -```text -POST https://contoso.sharepoint.com/sites/team-a/_api/web/GetList(@listUrl)/RenderListDataAsStream?@listUrl=%27%2Fsites%2Fteam-a%2Flists%2FList%27&SortField=ID&SortDir=Desc -accept: application/json;odata=nometadata -``` - -**Retrieve items from the specified folder** - -```text -POST https://contoso.sharepoint.com/sites/team-a/_api/web/GetList(@listUrl)/RenderListDataAsStream?@listUrl=%27%2Fsites%2Fteam-a%2Flists%2FOrders%27 -accept: application/json;odata=nometadata -content-type: application/json;odata=nometadata - -{ - "parameters": { - "FolderServerRelativeUrl": "/sites/team-a/lists/Orders/Europe" - } -} -``` - -**Retrieve list schema** - -```text -POST https://contoso.sharepoint.com/sites/team-a/_api/web/GetList(@listUrl)/RenderListDataAsStream?@listUrl=%27%2Fsites%2Fteam-a%2Flists%2FList%27 -accept: application/json;odata=nometadata -content-type: application/json;odata=nometadata - -{ - "parameters": { - "RenderOptions": 4 - } -} -``` - -**Retrieve information about list content types** - -```text -POST https://contoso.sharepoint.com/sites/team-a/_api/web/GetList(@listUrl)/RenderListDataAsStream?@listUrl=%27%2Fsites%2Fteam-a%2Flists%2FList%27 -accept: application/json;odata=nometadata -content-type: application/json;odata=nometadata - -{ - "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. - -``` -url: http://site url/_api/web/lists/GetByTitle('Test')/items -method: POST -body: { '__metadata': { 'type': 'SP.Data.TestListItem' }, 'Title': 'Test'} -headers: - Authorization: "Bearer " + accessToken - X-RequestDigest: form digest value - accept: "application/json;odata=verbose" - content-type: "application/json;odata=verbose" - content-length:length of post body -``` - -### Create list item in a folder - -The following example shows how to create a list item in a folder. - -```text -POST /_api/web/lists/GetByTitle('Test')/AddValidateUpdateItemUsingPath -``` - -#### URI Parameters - -None - -#### Request headers - -| Header | Value | -|--------|-------| -|Accept|application/json;odata=nometadata| -|Content-Type|application/json;odata=nometadata| -|x-requestdigest|The appropriate digest for current site| - -#### Request body - -```json -{ - "listItemCreateInfo": { - "FolderPath": { "DecodedUrl": "https://contoso.sharepoint.com/lists/Test/Folder/SubFolder" }, - "UnderlyingObjectType": 0 - }, - "formValues": [ - { - "FieldName": "Title", - "FieldValue": "Item" - } - ], - "bNewDocumentUpdate": false -} -``` - -| 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 [https://msdn.microsoft.com/en-us/library/microsoft.sharepoint.client.filesystemobjecttype(v=office.14).aspx](https://msdn.microsoft.com/en-us/library/microsoft.sharepoint.client.filesystemobjecttype(v=office.14).aspx)| -|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. - -``` -url: http://site url/_api/web/lists/GetByTitle('Test')/items(item id) -method: POST -body: { '__metadata': { 'type': 'SP.Data.TestListItem' }, 'Title': 'TestUpdated'} -headers: - Authorization: "Bearer " + accessToken - X-RequestDigest: form digest value - "IF-MATCH": etag or "*" - "X-HTTP-Method":"MERGE", - accept: "application/json;odata=verbose" - content-type: "application/json;odata=verbose" - content-length:length of post body -``` - -### Delete list item - -The following example shows how to delete a list item. - -``` -url: http://site url/_api/web/lists/GetByTitle('Test')/items(item id) -method: POST -headers: - Authorization: "Bearer " + accessToken - X-RequestDigest: form digest value - "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](http://www.odata.org/developers/protocols/operations), uses [HTML ETags for concurrency control](http://www.odata.org/developers/protocols/operations#ConcurrencycontrolandETags) 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 does not 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](https://docs.microsoft.com/en-us/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) -- [REST API reference and samples](https://msdn.microsoft.com/library) -- [OData resources](get-to-know-the-sharepoint-rest-service.md#odata-resources) -- [Develop SharePoint Add-ins](develop-sharepoint-add-ins.md) - - - - - +--- +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 `