Live publish

Author: buck1ey

powerapps-docs/maker/portals/configure/image-column.md

@@ -1,77 +1,89 @@
 ---
-title: Configuring an image column on portals (preview)
+title: Configure an image column on portals (preview)
 description: Learn how to configure an image column on portals.
 author: nageshbhat-msft
-
 ms.topic: conceptual
 ms.custom: 
-ms.date: 04/28/2022
+ms.date: 05/04/2022
 ms.subservice: portals
 ms.author: nabha
 ms.reviewer: ndoelman
 contributors:
     - ProfessorKendrick
     - nickdoelman
 ---
-# Configuring an image column on portals (preview)
 
->[!NOTE]
-> - This is a preview feature.  Preview features aren't meant for production use and may have restricted functionality. These features are available before an official release so that customers can get early access and provide feedback.
+# Configure an image column on portals (preview)
+
+[!INCLUDE [cc-preview-features-definition](../../../includes/cc-preview-features-definition.md)]
 
-You can configure image column fields on basic and advanced forms to upload, view, modify, and delete images. Image column allows you to store an image file up to the specified maximum size in Dataverse table columns. The thumbnail images can be seen in the web application when viewing the form data.
+An image column stores an image file in a column in a Dataverse table. Add an image column to a form to upload, view, modify, and delete images. The form shows a thumbnail of the image if one is available.
 
-:::image type="content" source="media/image-column/edit-image.png" alt-text="Navigating the edit image functionality.":::
+## Prerequisites
 
-## Enable image control on forms
+- **If you configure your site using the Portal Management app:** While the feature is in preview, you'll need to set the value of the site setting **Control/EnableImagePreview** to **true** to add image controls to a form.
 
-You must configure site settings **Control/EnableImagePreview** and set its value to **true** to enable **Image** controls on the form. You don't require to make any configuration to make image column with Liquid code and Web API.
+    :::image type="content" source="media/image-column/upload-image-preview.png" alt-text="Screenshot of the Control/EnableImagePreview site setting.":::
 
-:::image type="content" source="media/image-column/image-preview.png" alt-text="Enable image preview.":::
+    >[!IMPORTANT]
+    > This site setting is only required during the preview period.
 
->[!IMPORTANT]
-> This site setting is only required during the preview period.
+- **If you use [Liquid code](#liquid) or the [Web API](#web-api):** There's nothing more you need to do to add image controls to a form.
 
 ## Image URL
 
-An absolute URL to display the entity image in a client
+The image URL indicates the full URL of where the image is stored.  This can be used for development and troubleshooting.
 
-The URL is composed in following way
+An image URL takes the following form:
 
- ```{0}/Image/download.aspx?entity={1}&attribute={2}&id={3}``` 
+ ```{0}/Image/download.aspx?entity={1}&attribute={2}&id={3}```
 
-0 – Portal url
+where:
 
-1 – entity logical name
+- **{0}** is the portal URL
 
-2 – column logical name
+- **{1}** is the logical name of the entity
 
-3 – image ID
+- **{2}** is the logical name of the column
 
-## Liquid
+- **{3}** is the image ID
 
-Developers can design the website by using Liquid code to retrieve the records from Dataverse tables. Image column values can be fetched while data being queried by using fetchXML and entity view
+For example, if your portal is located at https://contososite.powerappsportals.com, your code will look like this:
 
+``` 
+https://contososite.powerappsportals.com/Image/download.aspx?entity=contact&attribute=entityimage&id=cb059a4a-b1a6-ec11-9840-00224829604e
 ```
+
+
+## Liquid
+
+You can design a website using [Liquid code](../liquid/liquid-overview.md) to retrieve records from Dataverse tables. Use fetchXML and the **Entity** view to fetch image column values, like this:
+
+```xml
     {% for item in tables.results.entities %}
         {{ item.columnname.Type }}
         {{ item.columnname.Size }}
         {{ item.columnname.Url }}
         {{ item.columnname.Value }}
     {% endfor %}
 ```
-| | |
-|-------|------------------------------|
-| Type  | Mime type of the image       |
-| Size  | Image size in bytes          |
-| Value | Image value in base64 string |
-| Url   | Image url                    |
 
-### Example: Retrieve default contact image
+where:
+
+- **Type** is the mime type of the image
+
+- **Size** is the image size in bytes
+
+- **Value** is the image value as a base64 string
+
+- **Url** is the image URL
+
+### Example: Retrieve a default contact image
 
 > [!NOTE]
-> Make sure you have configured the appropriate table permissions on the contact table to read the record.
+> Make sure you have [set the appropriate permissions](#create-a-table-permission) on the contact table to read the record.
 
-```
+```xml
     {% fetchxml contacts %}
         <fetch version="1.0" output-format="xml-platform" mapping="logical" distinct="false">
             <entity name="contact">
@@ -84,64 +96,65 @@ Developers can design the website by using Liquid code to retrieve the records f
     {% for item in contacts.results.entities %}
         {
             "Full Name":"{{ item.fullname }}"
-            "Entity Image Url":"{{ item.entityimage.Url}}",
-            "Entity Image Size":"{{ item.entityimage.Size}}",
             "Entity Image Type":"{{ item.entityimage.Type}}",
+            "Entity Image Size":"{{ item.entityimage.Size}}",
+            "Entity Image Url":"{{ item.entityimage.Url}}",
             "Entity Image Value":"{{ item.entityimage.Value}}"
         }
     {% endfor %}
 ```
 
-
 ## Web API
 
-The [portals Web API](../web-api-overview.md) can be used to perform, create, read, update, and delete operations on image columns across Dataverse tables.
+The [portals Web API](../web-api-overview.md) can be used to create, read, update, and delete images in image columns across Dataverse tables.
 
-## Retrieving image data
+### Retrieve image data
 
-To download thumbnail image data, use following APIs
+To download thumbnail image data, use the following API call:
 
-```
+```html
     GET /_api/<entity-type>(id)/<image-attribute-name>/$value
 ```
 
-Image data transfers from the web service endpoints are limited to a maximum of 16-MB data in a single service call.
+Image data transferred from the web service endpoints is limited to a maximum of 16 MB in a single service call.
 
-### Example: Thumbnail download
+#### Example: Download a thumbnail
 
-#### Request
+In the following example, we'll use a GET call to download a thumbnail if it exists.
 
-**HTTP** 
-```
+HTTP request:
+
+```html
     GET [Portal Url]/_api/accounts(62d53214-9dfa-eb11-94ee-0022482230a8)/entityimage/$value
 
     Headers:
     Content-Type: application/octet-stream
-``` 
+```
 
-#### Response
+HTTP response:
 
-**HTTP**
-```
+```html
     204 No Content
 
     Body:
     Byte[ ]
 ```
 
-## Upload image data
+In this example, the thumbnail doesn't exist and so no image is returned. If a thumbnail did exist, the response would return a byte array with values.
 
-To upload the images, set the value of the image column to a byte array that contains the content of the image file:
+### Upload image data
 
-```
+To upload an image, set the value of the image column to a byte array that contains the content of the image file:
+
+```html
     PUT or PATCH /_api<entity-type>(id)/<image-attribute-name>
 ```
 
-### Example: image upload
+#### Example: Upload an image
 
-#### Request
+HTTP request:
 
-```
+```html
     PUT [Portal Url]/_api/accounts(62d53214-9dfa-eb11-94ee-0022482230a8)/entityimage
 
     Headers:
@@ -151,40 +164,64 @@ To upload the images, set the value of the image column to a byte array that con
     Byte [ ]
 ```
 
-## Configure Profile Image
+### Upload profile images
 
-Profile picture serve as a visual of the person, so that he can be recognized visually. Now authenticated portal users can upload their image in the profile section. These images are saved in **Entity Image** column of the corresponding contact record in Dataverse. Users can upload image size up to 10 MB. A portal maker can allow uploading profile picture for the authenticated users by updating the site setting.
+Authenticated portal users can upload their picture in the profile section of the portal. The image is saved in the **Entity Image** column of the corresponding contact record in Dataverse. Users can upload images up to 10 MB.
+
+#### Create site settings
+
+First, you must create a site setting to allow authenticated users to upload a profile picture:
 
 1. Sign in to [Power Apps](https://make.powerapps.com/).
-1. Ensure that you're in the appropriate environment where your portal exists.
-1. Select **Apps** in the left navigation pane, and locate the **Portal Management** model-driven app.
-1. Select to open the **Portal Management** app, and then go to **Site Settings** in the left navigation pane.
 
-    :::image type="content" source="media/image-column/site-settings.png" alt-text="The site settings options within the Portal management app.":::
+1. Select the environment that contains your portal.
 
-1. Create or Update setting, **Profile/ShowImage**, and set its value to **true**.
+1. In the left pane, select **Apps**, and then open the **Portal Management** app.
 
-> [!NOTE]
-> The following steps are only required during the preview period.
+    :::image type="content" source="media/image-column/add-settings-site.png" alt-text="Screenshot of the Apps list, with the Portal Management app highlighted.":::
+
+1. In the left pane, select **Site Settings**.
+
+1. Create a setting called **Profile/ShowImage**, and set its value to **true**. (If the setting exists, set its value to **true**.)
+
+    :::image type="content" source="media/image-column/add-setting-showimage.png" alt-text="Screenshot of the Profile/ShowImage site setting.":::
 
-1. Create or Update setting, **Webapi/contact/enabled**, and set its value to **true**.
-1. Create or Update setting, **Webapi/contact/fields**, and set its value to **entityimage**.
+While the feature is in preview, also add or update the following site settings:
 
-### Create a table permission to allow authenticated user to upload profile picture to his contact records.
+- Set **Webapi/contact/enabled** to **true**.
 
-1. Select **Table Permissions** in the left navigation pane.
-1. Select **New**.
+- Set **Webapi/contact/fields** to **entityimage**.
 
-    :::image type="content" source="media/image-column/new.png" alt-text="Select new from table permissions.":::
+:::image type="content" source="media/image-column/add-settings-webapi.png" alt-text="Screenshot of the webapi site settings.":::
 
-1. Update the details as provided below.
+#### Create a table permission
 
-    :::image type="content" source="media/image-column/update-details.png" alt-text="Update details.":::
+Next, you must create a table permission to allow authenticated users to upload a profile picture:
+
+1. In the left pane, under **Security**, select **Table Permissions**, and then select **New**.
+
+    :::image type="content" source="media/image-column/add-table-permission.png" alt-text="Screenshot of the Active Table Permissions view, with New highlighted.":::
+
+1. Set the permission details as follows:
+
+    - Enter a meaningful name for the permission. In our example, we've entered "Contact Profile Update Permission."
+
+    - In the **Table Name** list, select **Contact (contact)**.
+
+    - In **Website**, search for and select the name of your portal.
+
+    - In the **Access Type** list, select **Self**.
+
+    - Under **Privileges**, select **Read**, **Write**, **Append**, and **Append To**.
+
+    :::image type="content" source="media/image-column/add-table-permission-details.png" alt-text="Screenshot of the details of a new table permission called Contact Profile Update Permission.":::
 
 1. Select **Save & Close**.
-1. Select and open **Contact Profile Update Permission**.
-1. Scroll down to the **Web Roles** section, and then select **Add Existing Web Role**.
-1. Search for **Authenticated Users**, and then select **Add**:
 
-    :::image type="content" source="media/image-column/add.png" alt-text="Add authenticated users":::
+1. In the **Active Table Permissions** view, select **Contact Profile Update Permission** (or whatever you named your new permission).
+
+1. In the **Web Roles** section, select **Add Existing Web Role**.
+
+1. Search for and select **Authenticated Users**, and then select **Add**.
 
+    :::image type="content" source="media/image-column/add-auth-users-web-role.png" alt-text="Screenshot that shows Authenticated Users selected as a web role.":::