Merge pull request #6 from pnp/alexc-msft/sharing-bugfix

Fixing prompt adaptive cards and engage messages

Author: alexc-MSFT

Documentation/Architecture.md

@@ -10,16 +10,27 @@ The following connectors are used in the Prompt Pulse solution:
 - Office 365 Users
 - SharePoint
 - Microsoft Teams
+- Office 365 Groups
 
 When executed from the Power App (to retrieve Groups, Teams and Viva Engage communities) they will be executed in the context of the current user so they should only see ones they have access to. They will also only see group chats they are part of.
 
+It's worth noting that Group Chats and Viva Engage Communities are pulled into the app via two flows.
+
 The above connectors are also used in the Power Automate flows.
 
+## Service Account
+
+**It is highly recommended to deploy Prompt Pulse using a dedicated service account/M365 user** and share the app across the organization/with the required users. The UPN for this service account is stored in the configuration list.
+
+Adaptive cards and Viva Engage notifications are sent using the account that deploys the Prompt Pulse Power Platform solution and configures the connections. Therefore by using a service account you can control the name of the user the notifications come from.
+
+In addition, in order to post the cards/notifications, the user account sending them needs to be member of the Team, Group Chat, Viva Engage community, this is handled automatically (with the exception of Group Chats) through the app. **Bear this in mind because not using a service account would result in the user who deployed the solution being added to these locations**.
+
 ## Power App
 
 The Prompt Pulse Power App is a canvas app using mostly **modern** controls where possible. Prompts that are shared/scheduled are stored in the **Prompts** SharePoint list.
 
-The app uses the above connectors to interact with the SharePoint site/lists and retrieve the locations in which to share the prompts.
+The app uses the above connectors (and flows listed below) to interact with the SharePoint site/lists and retrieve the locations in which to share the prompts. 
 
 The app can be customized if you wish, though it's worth noting that customizations will be lost if you attempt to update the solution in the future when new releases are available.
 
@@ -63,6 +74,30 @@ The flow then increments the value of the 'Likes' column by 1 and adds the promp
 
 If this value does not exist, it is appended to an array and the value of the 'LikedPrompts' column in the Users list is updated.
 
+## Get Group Chats
+
+This flow is triggered in the Power App when it is opened. It uses the Microsoft Teams connector to perform the following high-level steps:
+
+- Get group chats the user is part of.
+- Loop through group chats.
+- List members.
+- Check to see if the Prompt Pulse service account is a member of the chat AND that the chat has a name.
+- Return only the chats that contain the service account.
+
+This flow is required because prompt adaptive cards will not send if the service account is not a member of the chat. At the time of writing there is no workaround for this other than for the user to add the service account to the chat manually.
+
+## Get Engage Communities
+
+This flow is triggered in the Power App when it is opened. It uses the Viva Engage and Office 365 Groups connectors to perform the following high-level steps:
+
+- Get communities the user is a member of.
+- Loop through communities.
+- Get the M365 group for the community by filtering on the display name (may retrieve multiple groups).
+- Loop through the returned groups checking for ones where 'creationOptions' contains 'YammerProvisioning' (Viva Engage backed group).
+- Return the communities along with the groupids.
+
+This flow is required because the native Viva Engage connector does not return the M365 group id for the community. The group id is needed to add the service account to the group through the app when sending a prompt.
+
 ## Data Source
 
 As detailed in the [Overview](Overview.md) documentation, there are 3 SharePoint lists used in prompt pulse. Please see the details of each list below and what each column is used for:

Documentation/Deployment-guide.md

@@ -8,8 +8,8 @@ To begin, you will need:
 
 - Power Apps and Power Automate (seeded licenses) enabled and rolled out across your organisation.
 - Power Apps environment with a Dataverse database deployed (only required due to the solution using Environment Variables). You may use the default environment, however a production environment is recommended. If you do not have capacity to create a Dataverse database, you may need to use the default environment. 
-- Service account (optional) to deploy the Power App and Flows, if you do not wish to create a service account then an ordinary user with Environment Maker permissions is adequate.
-- Access to the Power Apps environment you wish to deploy to (Environment Maker) access.
+- Service account (**highly recommended**) to deploy the Power App and Flows. This should be a normal M365 user with a license that includes Power Apps, SharePoint, Viva Engage, Power Automate and Outlook. The account can have MFA enabled and you may choose the display name to suit your organization.
+- Access for the service account to the Power Apps environment you wish to deploy to (Environment Maker) access.
 - SharePoint site which will contain the lists - we recommend creating a new one for Prompt Pulse.
 - Full Control access to the above site. 
 - Regional settings set correctly on the SharePoint site for your timezone and locale (this is important for the scheduling to work correctly).
@@ -58,9 +58,15 @@ Title: AppId
 
 Value: Leave empty
 
+9. Create a second list item in the above list with the following details:
+
+Title: ServiceAccountUPN
+
+Value: UPN (Email) of your service account
+
 ## Step 2: Deploy Power Apps solution
 
-1. Navigate to **Power Apps**.
+1. Navigate to **Power Apps** as the service account.
 2. Click on the **Solutions** tab.
 3. Click on **Import**.
 4. Upload the solution zip file and click **Next**.
@@ -77,7 +83,7 @@ Value: Leave empty
 2. Share the app with all users who will use Prompt Pulse (you may want to add any administrators as co-owners so they can modify the app if you wish to).
 3. Test the app by 'Playing' it.
 
-You may also wish to share the 3 flows (**'Send Scheduled Prompt'**, **'Send Prompt'** and **'Like Prompt'**) with admins who may need to view the run history or edit them. You can find them under **Flows** in the **Power Apps** portal or in the **Power Automate** portal.
+You may also wish to share the 5 flows (**'Send Scheduled Prompt'**, **'Send Prompt'**, **'Like Prompt'**, **'Get Group Chats'** and **'Get Engage Communities'**) with admins who may need to view the run history or edit them. You can find them under **Flows** in the **Power Apps** portal or in the **Power Automate** portal.
 
 ## Step 3: Add the app to Teams (Optional)
 

Documentation/Overview.md

@@ -3,7 +3,7 @@
 Prompt Pulse consists of the following components:
 
 - Power App
-- 3 x Power Automate flows.
+- 5 x Power Automate flows.
 - 3 x SharePoint lists for data storage
 
 For more details on what each of these does please check out the [Architecture](Architecture.md) documentation.
@@ -39,6 +39,8 @@ From the main screen, the process for sharing a prompt is as follows:
 
 - Once sent, users will receive a notification in the format of an adaptive card in the chosen location.
 
+**Note - Only group chats with a name AND the Prompt Pulse service account/user added as a participant will display in the app. Users will need to add this user manually for the group chat to be visible in the app.**
+
 <img src="https://github.com/pnp/prompt-pulse/blob/main/Documentation/Images/prompt-pulse-share-screenshot.png?raw=true" alt="Prompt Pulse Share Screenshot"><br/>
 
 ### Viewing/using prompts
@@ -75,6 +77,7 @@ The **Send Now** option sends the prompt straight away and removes it from the s
 
 ### Tips
 
+- Use a dedicated service account/M365 user when deploying Prompt Pulse (adaptive cards will be sent from this account).
 - Deploy the app in the Teams admin center to allow users to install.
 - Add the app in Teams as a tab where appropriate.
 - Encourage users to install and pin the app in the rail.
@@ -84,17 +87,21 @@ The **Send Now** option sends the prompt straight away and removes it from the s
 
 - In it's current iteration, Prompt Pulse shows ALL prompts that have been shared irrespective of where the app is installed (personal app or in a teams tab) so bear this in mind when sharing prompts.
 - Sharing prompts in a personal install of Prompt Pulse will also show these prompts in Prompt Pulse when installed as a teams tab.
+- Only group chats that include the Prompt Pulse service account/user will appear in the app. Users will need to add this account into the group chat manually in order for it to display.
+- The Prompt Pulse service account/user will be automatically added to Teams and Engage Communities when a prompt to the location for the first time.
 
 Bear the above in mind when using Prompt Pulse, in a future iteration we will look to add support for sharing and viewing prompts in only the team the app is installed in. 
 
 
 ## Power Automate Flows
 
-There are 3 flows that are part of the Prompt Pulse solution, these are listed below along with a brief description of what these do, for more details please view the [Architecture](Architecture.md) documentation.
+There are 5 flows that are part of the Prompt Pulse solution, these are listed below along with a brief description of what these do, for more details please view the [Architecture](Architecture.md) documentation.
 
 - Send Prompt: This flow executes when a list item is created or modified in the 'Prompts' list and sends the prompt to the specified location using adaptive cards or in the case of Viva Engage, a message.
 - Send Scheduled Prompt: This flow runs on a recurrent schedule (5 minutes by default) and is responsible for checking for scheduled prompts in the list and sending these.
 - Like Prompt: This flow runs when a user clicks the **Like Prompt** button in the adaptive cards and adds the prompt to the users' liked prompts.
+- Get Group Chats: This flow is used in the Power App and retrieves a list of group chats that the current user is a member of where the Prompt Pulse account is a member of the chat.
+- Get Engage Communities: This flow is used in the Power App and returns a list of Viva Engage Communities that the current user is a member of.
 
 ## Data Storage
 
@@ -104,7 +111,7 @@ There are 3 SharePoint lists used in the solution:
 
 - Prompts: Stores the prompts shared/scheduled in the app.
 - Users: Stores the users who have opened/used Prompt Pulse and their liked prompts.
-- Configuration: Stores configuration settings for Prompt Pulse, at the time of writing it is only used to store the ID of the Power App (required for deep linking the adaptive cards in Teams).
+- Configuration: Stores configuration settings for Prompt Pulse.
 
 These lists can be easily extended or changed should you wish to modify/customize Prompt Pulse. You can of course edit and delete prompts directly from the list if required. Avoid modifying the values of the GroupId, GroupChatId, TeamId, ChannelId and MessageId columns as these are used heavily in the Power Automate flows.