Extending the Out of Office App
One of the purposes of our Office Template Series is self defining: To give PowerApps users templates or starting points to customize in their org. With that in mind, I'd like to walk through an extensibility scenario with the Out of Office app.
Generally, when people set their out of office in outlook, they provide a list of several people to contact regarding all the different projects they are associated with. As a starting point, the current Out of Office app only allows users to select one person to contact during their out of office period. Let’s extend that to:
- allow users to dynamically set a list of people to contact in their absence and
- provide a deep link to each of their email addresses.
To follow along with this tutorial, please go to https://web.powerapps.com and download the latest version of the Out of Office app, or download the fully finished app here
Modifying the Out of Office App
At a high level, here’s what we’re going to do to the app:
- Rewire the ‘CreateContactInfoScreen’ screen to allow a user to select multiple referral contacts for their out of office message
- These contacts will be stored in a collection internal to the app
- Create a new screen which allows users to set messages for each of these referral contacts
- These messages will be stored as HTML in another internal collection
- Modify the out of office message generation logic to fit the above amendments
Rewiring the Create Contact Info Screen:
Let’s start at the top: rewiring the ‘CreateContactInfoScreen’ screen.
While in the PowerApps editor, navigate to the ‘CreateContactInfoScreen’. Within the ‘ContactInfo_Contacts’ group, delete the items highlighted in the image below. These controls must be deleted to make room for a gallery which will store a collection of people to contact during the user’s out of office period.
Next, insert a blank vertical gallery in the newly open space. Before moving forward, duplicate the screen. It will serve as a basis for the second part of this extension.
On the original ’CreateContactInfoScreen’ we will be using the new gallery to allow users to select their points of contact for their out of office message. Select said gallery and set these properties as follows:
Items = UserCollect WrapCount = 2
Insert a button in the gallery and set its properties as follows:
Text = ThisItem.Name OnSelect = If(!(ThisItem in ThoseToContact), Collect(ThoseToContact, ThisItem), Remove(ThoseToContact, ThisItem)) Color = If(!(ThisItem in ThoseToContact), RGBA(47,41,43,1), White) Fill = If(ThisItem in ThoseToContact, RGBA(101, 94, 254, 1), White)
’ThoseToContact’ is a collection which stores the people the user has selected as points of contact during their out of office period. The OnSelect logic we’ve created above allows a user to select or deselect a person into or out of the ‘ThoseToContact’ collection. Style is added in the Color/Fill properties of the button to provide additional clarity to the user of which people are in the ‘ThoseToContact’ collection.
The final step on this screen is rewiring the ‘Next’ button. Select it and change its properties as follows:
OnSelect =
Clear(MessageContacts);
ForAll(ThoseToContact, Collect(MessageContacts, {MessageID: id, EmailURL: "<li><a href=mailto:" & Address & ">" & Name & "</a>", Message: ""}));
Navigate(CreateContactInfoScreen_1, None)
DisplayMode = If(CountRows(ThoseToContact) > 0, DisplayMode.Edit, Disabled)
‘MessageContacts’ is a collection which arranges each selected person (in ‘ThoseToContact’) with their respective part of the out of office message. The ‘EmailURL’ field is a deep link to each person’s email address. The ‘Message’ field is their part of the out of office message. Don’t worry about the open <li> tag in ‘EmailURL’, we’ll be closing it in the next screen when we learn how to fill out the ‘Message’ column.
The DisplayMode property is adjusted so that the button will be disabled if the user hasn’t selected anyone to include in their referral message.
With those few changes, the extension is halfway done.
Creating the Referral Messages Screen
Navigate to the screen we duplicated in the previous section (by default, it should be named ‘CreateContactInfoScreen_1’). Like the previous screen, the bulk of the work here involves manipulating the gallery. Select it and set:
Items = ThoseToContact
Recall that ‘ThoseToContact’ is the collection we created on the previous screen to store the points of contact a user wants to set in their out of office message. This gallery then, allows the user to see those people and provide a message for each.
Add a button, 2 labels, an ‘X’ icon, and a text input control to the gallery. The button is for aesthetic purposes only and will serve as a background “container” for the other items. Make sure the button fills the height/width of the gallery template and that it sits behind every other control. The rest of the properties for each of these controls is as follows:
TextInput:
OnChange =
UpdateIf(MessageContacts, MessageID = ThisItem.id,
{Message: " regarding " & TextInput2.Text & "</li>"})
Default: “”
X Icon:
OnSelect =
Remove(ThoseToContact, ThisItem); Remove(MessageContacts, LookUp(MessageContacts, ThisItem.id = MessageID))
The two properties highlighted in red and reproduced in text are the only ones significant to the functionality of the extension. Every other property listed is only for style or content.
The OnChange property of the ‘TextInput’ control is what writes the proper message to the proper user in the ‘MessageContacts’ field. We wrap the logic inside an UpdateIf function so that only the row with MessageID = ThisItem.id is overwritten. You’ll also notice that the open <li> tag is closed here. The Default property is blanked so it’s clear that no message is provided for that person.
The OnSelect property of the ‘X’ icon is removing that person from both the ‘MessageContacts’ collection and the ‘ThoseToContact’ collection. Removal from ‘MessageContacts’ is necessary because the gallery on this screen pulls from that collection, so without this removal, that person would still be visible in the gallery. Removal from ‘ThoseToContact’ is necessary because this collection is used to form the entirety of the out of office message, so failure to remove the person from this collection would result in a wrong/extra point of contact in the message.
Lastly, the OnSelect & DisplayMode properties of the ‘Next’ button on this screen needs to be modified. Select the button and in the OnSelect property make the proper modifications from the original logic (boxed in red) to the new logic (boxed in green):
Original Logic:
Set(Regarding, TextInput3.Text);
New Logic:
UpdateIf(MessageContacts, Message = "", {Message: " regarding general inquiries</li>"});
Set(Regarding, Concat(MessageContacts, "<ul>" & EmailURL & Message & "</ul>"));
Original Logic:
ContactUser & " at " & ContactUserEmail & If(Not(IsBlank(Regarding))," regarding " & Regarding) & ".
New Logic:
Regarding & “
For the DisplayMode property:
DisplayMode = If(CountRows(ThoseToContact) < 2, Disabled, Edit)
The first piece of the new OnSelect functionality sets any blank user specific messages to a generic “regarding general inquires” message. It then takes the ‘MessageContacts’ collection containing the individual ‘person pieces’ of the out of office message, and concatenates them down into one long string and stores it in the Regarding variable. The latter piece of the new functionality then amends that string (Regarding) into the pre existing message generation logic. This message will be presented to the user for review on the final ‘CreateReviewScreen’.
The DisplayMode functionality ensures that a user must set at least one point of contact in their out of office message before initializing it.
Summary
Now that we have finished the extension exercise, let’s recap what we just did.
The point of this exercise was to extend the Out of Office app to allow users to set multiple points of contact in their out of office message. To do so, we created two collections: ‘ThoseToContact’ and ‘MessageContacts’. ‘ThoseToContact’ is made up of people selected from the gallery we made in our first screen. As an app user selects/deselects a person in that gallery, they are added/removed from ‘ThoseToContact’. ‘MessageContacts’ starts being built in the OnSelect property of the Next button on that same screen. It takes all of the points of contact in ‘ThoseToContact’ and creates a table where each row contains the email address of a single point of contact and an (initially) blank ‘regarding message’.
In the second screen, the blank message field gets updated by the user from the gallery. When the text value of the ‘TextInputBox’ is changed, the message field of it’s respective row in ‘MessageContacts’ is updated to reflect that change. For any regarding messages left blank, we populate it with a precanned message. Finally, we modified the logic in the Next button on this screen to concatenate ‘MessageContacts’ into a single string which we then amended to the logic which generates the full out of office message.
Notes about this modification
- Editing your out of office message from the review screen is more complex now, due to the HTML tags. If you plan on modifying your message there, be sure that you are only editing the text between the HTML tags.
- This extension removed the ability to search for any user within your O365 tenant and set them as your referring contact. The pattern to place this feature back into the app is a straight forward, but dense exercise. See Veronica Ward’s blog Creating A Dialog for a possible design option for creating this search screen. Otherwise, the app here contains this feature
- With the message as is, the formatting will be a little clunky. Feel free to add additional HTML to better format the message, or refer to this for a possible fix.