Merge branch 'master' into Nava_charts

Author: Nkrb

powerapps-docs/developer/common-data-service/TOC.yml

@@ -27,6 +27,10 @@
       href: use-fetchxml-left-outer-join-query-records-not-in.md
     - name: Page large result sets with FetchXML
       href: org-service/page-large-result-sets-with-fetchxml.md
+    - name: Paging behaviors and ordering
+      href: org-service/paging-behaviors-and-ordering.md
+    - name: Use column comparison in queries
+      href: column-comparison.md
   - name: "Use SQL to query data (Preview)"
     href: cds-sql-query.md
   - name: Saved Queries

powerapps-docs/developer/common-data-service/authenticate-oauth.md

@@ -1,7 +1,7 @@
 ---
 title: "Use OAuth with Common Data Service (Common Data Service) | Microsoft Docs" # Intent and product brand in a unique string of 43-59 chars including spaces
 description: "Learn how to authenticate using OAuth with Common Data Service" # 115-145 characters including spaces. This abstract displays in the search result.
-ms.custom: ""
+ms.custom: has-adal-ref
 ms.date: 10/31/2018
 ms.reviewer: "pehecke"
 ms.service: powerapps

powerapps-docs/developer/common-data-service/build-web-applications-server-server-s2s-authentication.md

@@ -32,7 +32,7 @@ S2S authentication means you don’t need to use a paid Power Apps user license
 |   Scenario    |   Description  |
 |---------------|---------------|
 | Multi-Tenant  | This is the most common scenario and the one which is used for apps distributed using Microsoft AppSource.<br /><br /> Each Common Data Service tenant is associated with an Azure AD tenant. Your web application or service is registered with your Azure AD tenant.<br /><br /> In this scenario any Common Data Service tenant can potentially use your multi-tenant application after they grant consent for the application to access data in their tenant.                                                           |
-| Single-Tenant | This scenario typically applies to Common Data Service environments that want to develop apps for their own tenant and don’t intend to distribute them to other [Common Data Service environments.<br /><br /> An enterprise can create a web application or service to connect to all the Common Data Service environments for their tenant.<br /><br /> In this scenario, your web application or service will only be able to connect to Common Data Service environments using the same Azure AD tenant. |
+| Single-Tenant | This scenario typically applies to Common Data Service environments that want to develop apps for their own tenant and don’t intend to distribute them to other Common Data Service environments.<br /><br /> An enterprise can create a web application or service to connect to all the Common Data Service environments for their tenant.<br /><br /> In this scenario, your web application or service will only be able to connect to Common Data Service environments using the same Azure AD tenant. |
 
  Both scenarios have common elements but there are some differences. Since multi-tenant is the most common scenario, the [Use Multi-Tenant Server-to-server authentication](use-multi-tenant-server-server-authentication.md) content describes how you can use S2S in this scenario and include notes where the options for single-tenant configuration is different. 
 

powerapps-docs/developer/common-data-service/column-comparison.md

@@ -0,0 +1,70 @@
+---
+title: "Use column comparison in queries (Common Data Service) | Microsoft Docs" # Intent and product brand in a unique string of 43-59 chars including spaces
+description: "Learn how to compare columns when querying business data." # 115-145 characters including spaces. This abstract displays in the search result.
+ms.custom: ""
+ms.date: 07/08/2020
+ms.reviewer: "pehecke"
+ms.service: powerapps
+ms.topic: "article"
+author: "NHelgren" # GitHub ID
+ms.author: "nhelgren" # MSFT alias of Microsoft employees only
+manager: "mayadu" # MSFT alias of manager or PM counterpart
+search.audienceType: 
+  - developer
+search.app: 
+  - PowerApps
+  - D365CE
+---
+
+# Use column comparison in queries
+
+In the Common Data Service, users can perform a column comparison for the
+following condition operators using FetchXML, Web API, or the SDK API:
+
+- Equal
+- NotEqual
+- GreaterThan
+- GreaterEqual
+- LessThan
+- LessEqual
+
+This will allow the comparison of an attribute against a specific value and
+return all found records, or allow the comparison of two attributes to return
+all records with a matching value.
+
+## Limitations
+
+Listed below are the limitations for the current Common Data Service column comparison support.
+
+- You can only compare columns within a single entity
+- Only two columns may be compared at a time.
+- Multi-value condition operators are not supported (i.e., "in").
+- Extended condition operators are not supported (i.e., "creditlimit \> spends+1000").
+- Incompatible attribute comparison is not supported. For example, "int vs. int" attributes is a valid comparison but "int vs. string" attributes is not a valid comparison.
+
+## Column comparison using FetchXML
+
+The following example shows how to compare columns using FetchXML:
+
+```xml
+<fetch>
+  <entity name='contact' >
+    <attribute name='firstname' />
+    <filter>
+      <condition attribute='firstname' operator='eq' valueof='lastname'/>
+    </filter>
+  </entity>
+</fetch>
+```
+
+For FetchXML requests, a new node `valueof` has been added inside the condition
+node. The `valueof` tag is used to identify the attribute that is being compared
+to the selected attribute. In the above example, the 'firstname' column is being
+compared against the 'lastname' column and will return any records that contain
+the same value across both attributes.
+
+### See Also
+
+[Use FetchXML to construct a query](use-fetchxml-construct-query.md)  
+[Column comparison using the Web API](webapi/query-data-web-api.md#column-comparison-using-the-web-api)  
+[Column comparison using the SDK API](org-service/use-conditionexpression-class.md#column-comparison-using-the-sdk-api)

powerapps-docs/developer/common-data-service/file-attributes.md

@@ -2,7 +2,7 @@
 title: "File attributes (Common Data Service) | Microsoft Docs" # Intent and product brand in a unique string of 43-59 chars including spaces
 description: "Learn about File attributes that store file data within the application, supporting attributes, retrieving data, and uploading file data." # 115-145 characters including spaces. This abstract displays in the search result.
 ms.custom: ""
-ms.date: 06/17/2020
+ms.date: 07/09/2020
 ms.reviewer: "pehecke"
 ms.service: powerapps
 ms.topic: "article"
@@ -150,6 +150,18 @@ Headers:
 x-ms-transfer-mode: chunked 
 x-ms-file-name: sample.png
 ```
+
+**Request** (alternate form)
+
+This form of the request uses a query string parameter and supports non-ASCII language file names. If the file name is specified in both the header and as a query string parameter, the header value has precedence.
+
+```http
+PATCH [Organization URI]/api/data/v9.1/accounts(id)/myfileattribute?x-ms-file-name=测试.txt
+
+Headers: 
+x-ms-transfer-mode: chunked
+```
+
 **Response**
 ```http
 200 OK 

powerapps-docs/developer/common-data-service/org-service/page-large-result-sets-with-fetchxml.md

@@ -108,7 +108,9 @@ while (true)
 }
 ```
 
-### See also  
+### See also
+
+ [Paging behaviors and ordering](paging-behaviors-and-ordering.md)  
  [Sample: Use FetchXML with a Paging Cookie](samples/use-fetchxml-paging-cookie.md)   
  [Building Queries with FetchXML](/dynamics365/customer-engagement/developer/org-service/build-queries-fetchxml)   
  [Fiscal date and older than datetime query operators in FetchXML](../use-fetchxml-fiscal-date-older-datetime-query-operators.md)   

powerapps-docs/developer/common-data-service/org-service/paging-behaviors-and-ordering.md

@@ -0,0 +1,179 @@
+---
+title: "Paging behaviors and ordering (Common Data Service) | Microsoft Docs" # Intent and product brand in a unique string of 43-59 chars including spaces
+description: "Learn about the different paging behaviors for FetchXML queries and how you can write queries to get the desired paging results." # 115-145 characters including spaces. This abstract displays in the search result.
+ms.custom: ""
+ms.date: 7/20/2020
+ms.reviewer: "pehecke"
+ms.service: powerapps
+ms.topic: "article"
+author: "NHelgren" # GitHub ID
+ms.author: "nhelgren" # MSFT alias of Microsoft employees only
+manager: "mayadu" # MSFT alias of manager or PM counterpart
+search.audienceType: 
+  - developer
+search.app: 
+  - PowerApps
+  - D365CE
+---
+
+# Paging behaviors and ordering
+
+When querying data using FetchXML, paging query results can make viewing large
+volumes of information easier. It is important when using paging to include
+ordering parameters as well. Without proper ordering, paging requests for the
+“next 50” records can result in retrieving the same records across multiple
+pages making reviews and edits much more difficult. Proper page ordering
+requires including unique values to help identify which records are included in
+a page.
+
+## Legacy paging
+
+Legacy paging within the Common Data Service loads all the results of the query
+up to the current page into memory on the server, selects the number of records
+that are needed for the page, and then ignores the rest. This has benefits such
+as quick back/forward paging through the data or skipping to a specific page,
+but it also has restrictions such as a 50K row limit, performance issues with
+large complex queries, and arbitrarily sorted distinct query results.
+
+## Ordering with a paging cookie
+
+When paging with ordering, a cache of the previous page’s results is stored in a
+paging cookie. This is used to calculate what the next page of data should
+display.
+
+If a user does not specify any “order by” parameters, the system will
+automatically insert “order by "\<\<entity name\>\>".\<\<entityId\>\> asc” to
+provide some basic ordering. Depending on the data that is being queried, this
+may result in inadequate and unexpected results as a single system user can be
+associated with multiple records within any query.
+
+If distinct FetchXML queries are being used, the system will not add any
+additional ordering due to potential impacts to the data returned. In these
+cases, users will have to add at least a single ordering value for a more
+consistent paging experience.
+
+> [!NOTE]
+> Paging using FetchXML for Common Data Service is dynamic. The page a
+> record appears on is determined at the time that each page is rendered. If 1000
+> records are being displayed 50 to a page, the first 50 records are displayed as
+> page one. When page two is requested, the system determines what the next 50
+> records should be at the time of request. Because of this, it would not be
+> possible to use the new paging functionality for back paging. Legacy behavior is
+> used for back paging which will have reduced performance and any returns after
+> page 500 cannot be “paged back” due to legacy limitations. 
+
+### Why ordering is important
+
+If a query is run to retrieve all records with a state of “Open” this could
+result in 1000 returns. When paging from page one to page two, there is no way
+for the system to know which orders to display on page two because all of the
+records have the same state. The paging of these records will not be efficient
+or consistent.
+
+Providing an “order by” value gives the paging cookie the ability to order the
+data by an additional value and recognize the last record in a page based on the
+values provided.
+
+#### Example 1
+
+A query is created to get all records with a state of ‘Open’, include the status
+for every record, and show three records per page. The query is then ordered by
+status. The query result would page as shown in the following table:
+
+| State | Status | Page      |
+|-----------|------------|---------------|
+| Open      | Active     | 1             |
+| Open      | Active     | 1             |
+| Open      | Active     | End of page 1 |
+| Open      | Active     |               |
+| Open      | Active     |               |
+| Open      | Inactive   |               |
+| Open      | Inactive   |               |
+
+The paging cookie will save information about the last record on the page, but
+when it’s time to get page two in this example, there is no unique identifier to
+ensure that the next page populated uses the unviewed records or include the
+first two records that were on page one.
+
+To solve this problem, queries should include “order by” columns that have
+unique values. It is possible to use multiple “order by” values. Below is a
+better way to order data for this query:
+
+#### Example 2
+
+A query is created to get all records of a state of ‘Open’, any status, include
+the Case IDs, and show three records per page. It orders by status and by Case
+ID (a unique identifier) which will order in ascending order. The query result
+would page the results as shown below:
+
+| State | Status | Case ID | Page      |
+|-----------|------------|-------------|---------------|
+| Open      | Active     | Case-0010   | 1             |
+| Open      | Active     | Case-0021   | 1             |
+| Open      | Active     | Case-0032   | End of Page 1 |
+| Open      | Active     | Case-0034   |               |
+| Open      | Active     | Case-0070   |               |
+| Open      | Inactive   | Case-0015   |               |
+| Open      | Inactive   | Case-0047   |               |
+
+The query results are first ordered by the Status, and then ordered by the Case
+ID in ascending order. When page two is generated, the result would be as shown
+below:
+
+| State | Status | Case ID | Page      |
+|-----------|------------|-------------|---------------|
+| Open      | Active     | Case-0010   |               |
+| Open      | Active     | Case-0021   |               |
+| Open      | Active     | Case-0032   | End of Page 1 |
+| Open      | Active     | Case-0034   | 2             |
+| Open      | Active     | Case-0070   | 2             |
+| Open      | Inactive   | Case-0015   |               |
+| Open      | Inactive   | Case-0047   |               |
+
+When generating page two of this query set, the cookie will have Case-0032
+stored as the last record in the first page, so page two will pick up at the
+next record in the set after that record. This will allow for more consistent
+results.
+
+### Ordering suggestions
+
+Listed below are some suggestions for improving ordering of paging results, along with some areas to avoid.
+
+#### Best ordering
+
+- Always include a column that has a unique identifier (i.e., entity ID
+  columns, auto-number columns, user/contact IDs)
+
+#### Good ordering
+
+- Include multiple fields that will most likely result in unique combinations:
+  - First name + last name + email address
+  - Full name + email address
+  - Email address + company name
+
+#### Poor ordering
+
+- Orders that do not include unique identifiers
+
+- Orders that have single or multiple fields that are not likely to provide
+  uniqueness such as:
+  - Status and state
+  - Option sets or booleans
+  - Name values by themselves (i.e., last only, first only, company name
+    only)
+  - Text fields like titles, descriptions, multi-line text
+  - Non unique number fields
+
+### Ordering and multiple entity queries
+
+Sometimes data is needed that spans multiple entities and must be queried with a
+table JOIN. In these cases, ordering can be included for both entities in the
+query. Make sure to use at least one column with a unique ID per entity to
+ensure the paging provides the best results. However, the query will be
+downgraded to legacy paging, where no paging cookie will be returned, in these
+cases due to limitations of the N:1 relationship structure that could result in
+missing data.
+
+### See Also
+
+[Page large result sets with FetchXML](page-large-result-sets-with-fetchxml.md)

powerapps-docs/developer/common-data-service/org-service/use-conditionexpression-class.md

@@ -82,7 +82,41 @@ condition3.Operator = ConditionOperator.Equal;
 condition3.Values.Add(AccountState.Active);  
 
 ```  
-  
+
+## Column comparison using the SDK API
+
+The following example shows how to compare columns using SDK API and the Organization service:
+
+```csharp
+public ConditionExpression
+(
+  string attributeName,
+  ConditionOperator conditionOperator,
+  bool compareColumns,
+  object value
+)
+
+public ConditionExpression
+(
+  string attributeName,
+  ConditionOperator conditionOperator,
+  bool compareColumns,
+  object[] values
+)
+```
+
+In the SDK, two APIs are introduced to support column comparison. The
+first identifies the original attribute, the second allows
+for the inclusion of the attribute you want to compare it against.
+
+If `compareColumns` is passed in as `true`, it will compare the two attributes
+and return all records that match.
+
+If a `false` value is passed, it will return all records for one attribute and
+return values that match the provided value.
+
+More information: [Use column comparison in queries](../column-comparison.md)
+
 ### See also  
  [Building Queries](build-queries-with-queryexpression.md)   
  [Build Queries with QueryExpression](build-queries-with-queryexpression.md)