User Guide

Introduction

Kick-start your work by creating your Office document based on the latest and most up-to-date templates served to you in your favorite Office application on any device or platform.

Designer for Office, Word
Designer for Office, Word
Multiple Office App Awards Winner
Microsoft 365 App Certified

Supported Office applications

Word
Word

Launching

Top

In Word

Designer Ribbon

Once the 'Designer' Add-In has been deployed and assigned to you, it will automatically appear in the 'Design' tab of your Office application ribbon. To launch the App best click on the 'Design' button.

Please note:

The 'Designer' Add-In is currently available in Word for Windows, Word for the Web, Word for Mac, and Word for iOS.

Please note:

If the 'Designer' Add-In does not appear, make sure that you have signed-in to Word with your Microsoft 365 Work or School account. If that is the case and the Add-In is still not appearing, then please contact your internal IT department.

Signing In

Top

To get started with this Add-In/App you need to connect it with your existing Microsoft 365 Work or School account or with your Personal Microsoft Account. Follow these steps:

Desinger Welcome Page
  • Click on the 'Connect' (1) button.

  • Sign-in using your Microsoft 365 (Work or School) account or your Personal Microsoft Account.

  • You might be asked to consent to the Add-In accessing your data. This step might have been taken care of by your internal IT department in advance. In that case you will not be asked.

  • Done.

Please note:

The actual sign in experience is provided by Microsoft. officeatwork does not offer any user accounts. Users must use their existing accounts to sign in to the Add-In.

Accounts

This Add-In accepts Microsoft 365 Work or School accounts. It also accepts Personal Microsoft Accounts including GitHub accounts.

Consenting

The first time you connect the app, you might be asked to consent to the permissions required by the app. Please go through those permissions carefully and grant consent as the App requires these permissions to function. If you do not grant consent, the app will not work for you.

Please note:

Your IT administrator can pre-consent on behalf of all users. That way you and your fellow users would not have to consent each individually. Your IT administrators can learn more about pre-consenting in the IT Operations Guide further below.

Add-In Menus

Top

You can find the app menus at the bottom of the app. It currently consists of the 'officeatwork' logo (on the left) and (on the right) the 'Settings' menu, the 'Help' menu, and the 'User' menu. Clicking on the officeatwork logo will take you to the officeatwork website.

Please note:

Dependent on the officeatwork app and its configuration for your Microsoft 365 tenant, items available in the app menus may vary.

Settings

Settings menu
  • About: This will take you to the about pane that lists various information about this app.

  • Rate: This will take you to the review page on Microsoft AppSource.

  • Document: This will take you to the document settings page of this app.

  • Admin Center: If you are an officeatwork admin, you will see the 'Admin Center' option that will take you straight to the officeatwork 'Admin Center' app.

Help

The help menu is customizable via the officeatwork 'Admin Center' App. The description below explains the standard officeatwork experience. It's also possible that the help option is completely missing (No help experience) or is showing different elements in the case where your officeatwork admin has chosen to go for a custom help experience.

Help menu

officeatwork standard help experience

  • Getting Started: Link to a page that will help you get started with this Add-In or App.

  • Documentation: Link to the documentation of the Add-In or App.

  • Help Center: Link to the officeatwork Help Center.

  • Yammer Community: Link to the officeatwork Yammer community.

  • Send us your Feedback: Link to an online feedback form you can use to reach out to officeatwork.

  • Roadmap: Link to the roadmap page of the Add-In or App.

Additionally to the help experiences listed above, you might also want to consider the following (free and paid) options:

  • Learn more links: Throughout the app, you will find 'Learn more' links that will take you to the documentation pages covering the topic you are currently viewing. These links are the fastest way to pull up the relevant documentation.

  • Premium Support: Customers with a Premium Support Subscription can use additional support offerings and channels made available via the premium support subscription.

  • Your internal resources: You will most likely have internal resources covering the Business aspects or IT aspects of this App. Please also consider reaching out to them when appropriate. Thank you.

User Menu

User menu
  • Signed-in User: You can see the photo, name, and email address of the currently signed-in user at the top of the User menu.

  • Sign out: This option will allow you to sign out of this Add-In/App.

Navigation

Top

Tabs section

The navigation within the App has one main element, the «Tabs» (1) menu. The «Preview» button in the ribbon opens the «Wizard» in a separate pane. The «Wizard» is also available as a separate App for users that just want to use but not create designs.

Designer navigation

The «Tabs» (1) allows you to select one of the main App sections that are «Settings», «Input Fields», «Placeholders» and «Publish».

Design Settings

Top
Designer Design Settings

The Settings are the place where you define Branding Banner, Name and a Description for your Template. We highly recommend to use all available settings to optimize the user experience of your document.

Branding Banner

The Branding Banner (1) will allow you to have an image placed right at the top of the «Wizard» Add-In. We highly recommend to place some branding element like your logo on the «Wizard» using this Branding Banner option. If you want to align your artwork with the design of the wizard you should know that all elements in the «Wizard» Add-In have a left margin of 18 pixels. So, to accommodate for that just add 18 pixels to the left of your logo and it will align perfectly. While you are at it you might also want to add 10 pixels at the top so that it does not stick to the top of the «Wizard» Add-In.

Upload

To upload an image file just click on the «Upload» icon below the image filed and then select a file from your available storage locations using the ‘Choose file to upload’ dialog. Supported file formats are .png, .gif and .bmp.

Remove

To remove the banner just click on the «Remove» icon below the image field.

Image Dimensions

Designer branding dymensions

The dimension of your branding banner is largely defined by the kind of logo or artwork you want to display. There are some measurements that you might want to consider. As the default width of the pane is just over 300 pixels we recommend not to exceed 300 pixels in your image (in total). To align it on the left we would suggest to include 18 empty (transparent) pixels on the left and 10 pixels on the top to make it nicely fit into add-in pane. In this ‘officeatwork’ sample we colored in these top and left pixels for better illustration.

Name

The Name (2) is displayed in the «Wizard» Add-In and should be not to long as it is displayed in a larger font. Best use something equivalent as 'Letter' for a Letter document or 'Report' for a Report document.

Description

The Description (3) field is displayed below the Name field in the «Wizard» Add-In and should be no longer than a short sentence describing to users, what this document shall be used for. Best use something equivalent as ‘Use this Letter globally for all your external facing correspondence’.

Input Fields

Top
Designer Input Fields

The 'Input Fields' page lists all existing input fields for your active document. Use input fields to allow users to input data that can then be used in document 'Placeholders' to personalize the document purpose fit for the user’s needs, for example for selecting a Brand, a contact person or entering a subject line. Even things like switching between a color and black & white logo for the company brand can be accomplished by utilizing «Input Fields».

New/Edit/Delete

To create a new «Input Field» just click on the «Plus» icon at the bottom of your lists of input fields. Then just click on the type of input field you wish to create.

To edit an existing «Input Field» just click on the input field you want to edit in the list of input fields.

To delete an existing «Input Field» just click on the input field you want to delete. Then click on the «Delete» button at the far bottom left of the input field edit page. You might have to scroll down to access the «Delete» button.

Connecting

Designer connecting

Some fields like the 'Office 365 Users' or 'SharePoint Online List' input field are connected to an external data source. Sources you have not recently used will present a 'Connect' button enabling you to allow the 'Designer' Add-In to connect to the corresponding data source. In this case you first need to click the 'Connect' button and go through an authentication flow to be able to edit the properties for that input field.

Office 365 Users

Designer Office 365 Users Input Field

The 'Office 365 User' input field will enable you to let the user select a one or many users in the 'Wizard' Add-In. The list of users comes from the Microsoft Graph and represents the users registered in your tenants Azure AD. A typical use for the 'Office 365 User' input field would be to select an author, contact or signature person, or meeting participants for your document. The following user properties are currently available:

  • displayName

  • givenName

  • mail

  • surname

  • userPrincipalName

Learn more about the individual properties in the official Microsoft documentation covering the Microsoft Graph: https://docs.microsoft.com/en-us/graph/api/resources/user?view=graph-rest-1.0#properties

Please note: There are more attributes available than the five listed above - but for that you need to enable the all user properties switch. Read more about this below.

Name

The Name of the input field will be visible to the User in the 'Wizard' Add-In. Please try to choose a short and meaningful name that can be easily recognized by your users.

Group

The Group will be visible to the User above the Name field in the 'Wizard' Add-In. The user can collapse and expand groups in the 'Wizard' Add-In using the collapse/expand icon to the left of the group name. Try to pick logical group names that can be shared among multiple input fields providing the user with a logical understanding of all your input fields. Group names could be something like From, To, Document, etc.

Use last input as default

If set to 'On' the Add-In will remember the user’s last input/selection and automatically apply the user’s last input/selection for that input field the next time the 'Wizard' Add-In runs the first time for each specific document. This will only work for input fields that have the same 'Name', 'Context/Group', and are of the same type, and have set the same attributes.

Allow multiple selection

Enable this option to allow users to select multiple users for your 'Input Field'. This would for instance make sense when wanting to select multiple meeting participants (any number of users) in just one input field. That way you can avoid having to create separate input fields per participant (like an input field for Participant 1, Participant 2, Participant 3 etc.)

Please note: When inserting user properties of 'multi selection enabled' Office 365 User input fields into a placeholder, the placeholder formula snippet inserted will be adjusted accordingly so that the properties of all selected users will be visible in your document/template.

Use signed-in user as default

Enable this option to automatically populate the 'Input Field' with the currently signed-in user.

Please note: The 'Use last input as default' will override any 'Use signed-in user as default' setting. So if there is a last input value available then that value will win over the signed-in user value.

Enable all user properties

If you want to use additional user properties (see list below) in your documents and templates you need to grant the add-in dedicated permissions to do that. Use the 'Grant Permissions' link to do that. Please be aware that for this to work you need to be an Microsoft 365 admin to be able to grant this access. Here is the list of the additional user properties that will be enabled:

  • aboutMe

  • birthday

  • businessPhones

  • city

  • companyName

  • country

  • department

  • employeeId

  • hireDate

  • id

  • imAddresses

  • interests

  • jobTitle

  • mailNickname

  • mobilePhone

  • mySite

  • officeLocation

  • onPremisesDistinguishedName

  • onPremisesDomainName

  • onPremisesExtensionAttributes (extensionAttribute1 - 15)

  • onPremisesImmutableId

  • onPremisesUserPrincipalName

  • otherMails

  • pastProjects

  • postalCode

  • preferredDataLocation

  • preferredLanguage

  • preferredName

  • responsibilities

  • schools

  • skills

  • state

  • streetAddress

  • usageLocation

  • userType

Personal Contacts

Designer Office 365 Personal Contacts Input Field

The 'Personal Contacts' input field allows you to let the user select personal contact in the 'Wizard' Add-In. The list of contacts comes from Office 365 Outlook and represents the users contacts in Outlook. Please note that 'Personal Contacts' does not support Outlook Shared Contact Folders.
A typical use for the 'Personal Contacts' would be to select a recipient for your document. The following contact properties are currently available:

  • assistantName

  • birthday

  • businessAddress - city

  • businessAddress - countryOrRegion

  • businessAddress - postalCode

  • businessAddress - state

  • businessAddress - street

  • businessHomePage

  • businessPhone

  • businessPhone 2

  • categories

  • children

  • companyName

  • department

  • displayName

  • emailAddress - address

  • emailAddress - name

  • emailAddress 2 - address

  • emailAddress 2 - name

  • emailAddress 3 - address

  • emailAddress 3 - name

  • fileAs

  • flag

  • generation

  • givenName

  • homeAddress - city

  • homeAddress - countryOrRegion

  • homeAddress - postalCode

  • homeAddress - state

  • homeAddress - street

  • homePhone

  • homePhone 2

  • id

  • imAddresses

  • initials

  • jobTitle

  • manager

  • middleName

  • mobilePhone

  • nickName

  • officeLocation

  • otherAddress - city

  • otherAddress - countryOrRegion

  • otherAddress - postalCode

  • otherAddress - state

  • otherAddress - street

  • parentFolderId

  • personalNotes

  • profession

  • spouseName

  • surname

  • title

Name

The Name of the input field will be visible to the User in the 'Wizard' Add-In. Please try to choose a short and meaningful name that can be easily recognized by your users.

Group

The Group will be visible to the User above the Name field in the 'Wizard' Add-In. The user can collapse and expand groups in the 'Wizard' Add-In using the collapse/expand icon to the left of the group name. Try to pick logical group names that can be shared among multiple input fields providing the user with a logical understanding of all your input fields. Group names could be something like From, To, Document, etc.

Use last input as default

If set to 'On' the Add-In will remember the user’s last input/selection and automatically apply the user’s last input/selection for that input field the next time the 'Wizard' Add-In runs the first time for each specific document. This will only work for input fields that have the same 'Name', 'Context/Group', and are of the same type, and have set the same attributes.

SharePoint Online List

Designer SharePoint Online Input Field

A SharePoint Online List Picker will allow you to select and display data from any SharePoint Online List including images from SharePoint document libraries in your documents. Please note that only the following column types are currently supported:

  • Single line of text

  • Multiple lines of text (plain text and simple rich text)

  • Choice (menu to choose from)

  • Number (1, 1.0, 100)

  • Currency ($, ¥, €)

  • Hyperlink or Picture

  • Calculated

  • Date and Time

Name

The Name of the input field will be visible to the User in the 'Wizard' Add-In. Please try to choose a short and meaningful name that can be easily recognized by your users.

Group

The Group will be visible to the User above the Name field in the 'Wizard' Add-In. The user can collapse and expand groups in the 'Wizard' Add-In using the collapse/expand icon to the left of the group name. Try to pick logical group names that can be shared among multiple input fields providing the user with a logical understanding of all your input fields. Group names could be something like From, To, Document, etc.

Use last input as default

If set to 'On' the Add-In will remember the user’s last input/selection and automatically apply the user’s last input/selection for that input field the next time the 'Wizard' Add-In runs the first time for each specific document. This will only work for input fields that have the same 'Name', 'Context/Group', and are of the same type, and have set the same attributes.

List Settings URL

The List Settings URL is used to identify the SharePoint list. It is easiest to copy and paste the List Settings URL from your browser when viewing the list settings page of your SharePoint list in your browser. After you have exited the field the Add-in will check if it can access the library referenced in the URL. If successful it will enable and populate the Search Field and Description Field below with values. Please be aware that the URL must be within your SharePoint Online root host.

SharePoint List Settings Page

Please note: The user will need at least read rights to the root site of the site collection you are connecting to.

Title Field

The 'Title Field' is the field used in the 'Wizard' Add-In to display any items found in the search experience for the linked SharePoint list. Most commonly this would be the ‘Title’ field from your SharePoint Online list.

Description Field

The 'Description' field is used in the 'Wizard' Add-In to display any items found in the search experience for the linked SharePoint list. The 'Description' field appears less prominent below the Title field within the search experience.

The 'Title' and 'Description' fields are being used for searching the entries in SharePoint Online. Be aware that this search occurs also in the translated columns of those fields. If you, for instance, define the SharePoint column 'Title' to be you Title field, the app will search in the 'Title' column as well as in the appropriate Title.[language code] (for example Title.en, Title.de etc.) columns according to your app frontend language.

Attention:

Please be aware that lists with more than 5000 items will not be searchable unless you index the fields in SharePoint that will be used for searching. Please also be aware that the search will only search in the defined Title column. Title translation fields as well as the description field (including description translation fields) will be ignored.

DEFAULT Value

The ‘Default Value’ option will allow you to select a specific Item (record) from your SharePoint list selected by default. For this to work you need to specify some criteria that will find a record in the SharePoint Online list. The criteria is defined by a field using the «Field» dropdown, an operator using the «Operator» dropdown and a value entered in the «Value» field. Note that the value can be made up of static input as well as formulas using Nunjucks functions. To add a function just click on the «Insert» button below the Value field.

The first item is found in the SharePoint list that will return true when comparing field with the value using the chosen operator. Example: select the first SharePoint record where the SharePoint column ‘City’ («Field») ‘Starts with’ («Operator») ‘London’ («Value»).

If you for instance want to select a record in SharePoint based on the City of the current user the example would look like this: select the first SharePoint record where the SharePoint column ‘City’ («Field») ‘Starts with’ («Operator») {{ currentUser.city }} («Value»)

Please note: The 'Use last input as default' will override any 'Default' setting. So if there is a last input value available then that value will win over the signed-in user value.

Plain Text

Designer Plain Text Input Field

Use this 'Plain Text' input field type whenever you want the user to be able to input some text of any kind without any guidance. This input field type has no additional properties.

Name

The Name of the input field will be visible to the User in the 'Wizard' Add-In. Please try to choose a short and meaningful name that can be easily recognized by your users.

Group

The Group will be visible to the User above the Name field in the 'Wizard' Add-In. The user can collapse and expand groups in the 'Wizard' Add-In using the collapse/expand icon to the left of the group name. Try to pick logical group names that can be shared among multiple input fields providing the user with a logical understanding of all your input fields. Group names could be something like From, To, Document, etc.

Use last input as default

If set to 'On' the Add-In will remember the user’s last input/selection and automatically apply the user’s last input/selection for that input field the next time the 'Wizard' Add-In runs the first time for each specific document. This will only work for input fields that have the same 'Name', 'Context/Group', and are of the same type, and have set the same attributes.

Allow multiple lines of text

If set to «On» the Plain Text Input field in the «Wizard» Add-In will offer the user multiple lines for entering data instead of just one line.

Please note: If you are inserting a multi lines enabled text field into a HTML placeholder you should use the 'nl2br' Nunjucks filter in your field formula to convert the carriage return a user might make to HTML actionable <br> elements.

Custom List

Designer Custom List Input Field

The 'Custom List' input field allows you to let the user make a choice between pre-defined options in the 'Wizard' Add-in. A typical use for the 'Custom List' would be to control if the company logo shall appear in color or black & white.

Name

The Name of the input field will be visible to the User in the 'Wizard' Add-In. Please try to choose a short and meaningful name that can be easily recognized by your users.

Group

The Group will be visible to the User above the Name field in the 'Wizard' Add-In. The user can collapse and expand groups in the 'Wizard' Add-In using the collapse/expand icon to the left of the group name. Try to pick logical group names that can be shared among multiple input fields providing the user with a logical understanding of all your input fields. Group names could be something like From, To, Document, etc.

Use last input as default

If set to 'On' the Add-In will remember the user’s last input/selection and automatically apply the user’s last input/selection for that input field the next time the 'Wizard' Add-In runs the first time for each specific document. This will only work for input fields that have the same 'Name', 'Context/Group', and are of the same type, and have set the same attributes.

Label & Value

Each option in a custom list has a «Label» and «Value» entry. The «Label» will be visible to the user as the option he or she can pick. The «Value» will not be visible to the user but can still be used within a calculation of a placeholder value.

To create new entries just press the plus icon at the bottom of the list of all custom list items. To delete an item, click the delete button to the far right of each custom list item. There is no limit in how many items you can have in a custom list. We do though suggest to not go crazy regarding the amount of items per custom list. Preferably a custom list has no more than 7 items.

Default

Once all Custom List items have been created one of the entries can be defined as the default item. This means that this item will automatically be selected as the default value when the Custom List field gets displayed in the «Wizard» Add-in.

Sample Data

Designer Sample Data Input Field

The 'Sample Data' input field offers a fast way to learn how users can select data using the 'Wizard' Add-In without having to first set-up lists and libraries in SharePoint. All our sample files that we offer for the 'Designer' Add-In and 'Wizard' are using input fields of type 'Sample Data'.

Name

The Name of the input field will be visible to the User in the 'Wizard' Add-In. Please try to choose a short and meaningful name that can be easily recognized by your users.

Group

The Group will be visible to the User above the Name field in the 'Wizard' Add-In. The user can collapse and expand groups in the 'Wizard' Add-In using the collapse/expand icon to the left of the group name. Try to pick logical group names that can be shared among multiple input fields providing the user with a logical understanding of all your input fields. Group names could be something like From, To, Document, etc.

Use last input as default

If set to 'On' the Add-In will remember the user’s last input/selection and automatically apply the user’s last input/selection for that input field the next time the 'Wizard' Add-In runs the first time for each specific document. This will only work for input fields that have the same 'Name', 'Context/Group', and are of the same type, and have set the same attributes.

Table

The 'Sample Data' input field offers different types of sample data. Use the Table field to select the type of sample data you want to use in your input field.

Here is a list of the available sample data tables:

  • Users

  • Contacts

  • Events

  • Invoices

  • Offers

  • Organizations

UI Translations

Top

The names and descriptions you use in your 'Design Settings' and 'Input Fields' can be translated so that users with different Microsoft 365 or Office/Browser UI languages can experience your Designer/Wizard configuration in their preferred language.

Activating Translations

The UI Translations feature is switched off by default. To enable UI Translations you need to activate the feature using the officeatwork Admin Center.

Assigning Translations

To assign translations just click on the Translations toggle button above your input field and pick any translation available.

UI Translations

Toggle Translation

  • Click on the 'translation toggle' (1) button.

    Please note:

    The 'translation toggle' button will only appear once you have configured the UI Translations Library in the Admin Center.

  • The translation field will show or hide below.

  • Done.

Pick a translation

  • Click into the 'Translation field' (2).

  • A translation picker fly-out will appear.

  • Search and select your translation entry.

  • Done.

Placeholders

Top

The «Placeholders» page lists all existing placeholders for your active document. «Placeholders» are used to visualize data entered or select via the «Wizard» Add-in, allowing the user to personalize the document purpose fit for his or her needs.

New/Edit/View/Delete

Designer Placeholder List

New

To create a new «Placeholder» just click on the «Plus» at the bottom of your lists of «Placeholders». A panel will appear allowing you to provide a custom name and pick one or multiple values for your new «Placeholder». All of these attributes can be changed later. Still we recommend to fill-in all the fields as desired.

When you click on the «Plus» icon it will create a native Word «Content Control» as your representation of your «Placeholder» in the document at the current cursor position. Additionally it will display the properties panel for that newly created «Placeholder». Learn more about the individual properties below. To get back to the list of all your «Placeholders» just click on «Done» at the bottom of the «Properties» page.

Please note: Any native Word Rich-Text «Content Control» with no «Placeholder Properties» assigned to it, it will be listed as an «Untitled».

Please note: Learn more about how to position your placeholder here.

Edit

To edit a «Placeholder» just click on the «Placeholder» in the list of «Placeholders». Once you are done editing the «Placeholder» click on «back» button at the top left of the page to return to the list of «Placeholder»

View

To view a «Placeholder» in the document just hover over a «Placeholder» in the list of «Placeholders» and click on the «Eye» icon. This will bring into view and select the appropriate placeholder representation in your Word document. Additionally it will also mark your «Placeholder» in the list of «Placeholders» with a blue bar indicating that this placeholder is currently selected within your Word document. Note that this works independently from pressing the «Eye» icon. You can select any portion of your Word document and the blue bars will appear for all selected «Placeholders» in the list of «Placeholders».

Delete

To delete a «Placeholder» just navigate to the appropriate «Placeholder» details and use the «delete» button at the bottom left of the page or delete the related native Word «Content Control» in your document and reload the add-in or page to see the list of «Placeholders» update accordingly.

Properties

Designer Placeholder properties

Once you have clicked on any of the placeholders you will be taken to the properties page of that placeholder. To return to the list of placeholders just click on the arrow back (1) on the Edit Placeholder page.

Name

Use the Name property to give your «Placeholder» a meaningful name. The name will only be used within the «Designer» Add-in and will help you to choose between many «Placeholders» in your «Placeholders» list. This property is optional. If you do not define a name for your «Placeholder» it will be listed as «Untitled» in the Placeholders list.

Format

The «Format» defines how the data defined in the value field below will be inserted into the body section of the native Word Content Control in the document. The available options are:

Plain Text: This will transfer all the content from the «Value» field as plain text into the body section of the native Word «Content Control».

HTML: This will transfer all the content from the «Value» field as HTML into the body section of the native Word «Content Control». You will be able to use HTML formatting options like for bold or for header formatting.

Ooxml: This will transfer all the content from the «Value» field as Ooxml into the body section of the native Word «Content Control». You will be able to use Ooxml formatting options but please make sure that you define a complete Ooxml with all required elements.

Picture from Public URL: This will interpret the content from the «Value» field as a URL and insert the linked image into the body section of the native Word «Content Control». Please make sure that the URL points to a CORS enabled server and that the image is publicly available and not protected with any kind of sign-in. The currently supported file formats are: PNG, JPG and GIF.

Picture from SharePoint Online URL: This will interpret the content from the «Value» field as a URL and insert the linked image into the body section of the native Word «Content Control». Please make sure that the URL is pointing to your SharePoint Online tenant and that the SharePoint Online user rights are set in a way that the designated users have access to that image resource (URL) within you tenant. The currently supported file formats are: PNG, JPG and GIF.

Please note: Learn more about how to display images in placeholders here.

Value

The «Value» represents the actual value that will be inserted in the defined «Format» into the body section of the native Word Content Control in the document.

Please note: Learn more about how to customize the value of a placeholder here.

Title

Use the «Title» property to add a title for your Word Content Control representing your «Placeholder» in the document. This property is optional.

Please note: The «Title» of your «Placeholder» will only be visible in the related native Word «Content Control» if the «Show as» property of the «Placeholder» is set to either «Start/End Tag» or «Bounding Box».

Hint

Use the «Hint» property to define what shall be visible as content of the «Placeholder» in case the «Value» of the «Placeholder» is empty. Use this to hint to the user what values will be visible when data is evaluated as «Content» for the «Placeholder».

Note that by default every placeholder comes with a hint pre-defined. So, if you do not set the «Hint» property you will be seeing a hint text whenever your placeholder is empty. To show nothing when your placeholder is empty you need to actively set your hint text to nothing. You can do this by setting your hint «Type» to «Custom Text» and leaving your hint «Custom Text» field empty.

Deletable

Use the «Deletable» property to define if the user shall be able to delete the «Placeholder» in the Document. Set this option to «Cannot be deleted» if you do not want the user to be able to delete this «Placeholder».

Editable

Use the «Editable» property to define if the user shall be able to click into the «Placeholder» in the Document and change the value of it by typing, pasting or deleting the content. Set this option to «Cannot be edited» if you do not want the user to be able to edit the content of this «Placeholder».

Tip: If you cannot format your «Placeholders» on your document it might be set to be non-editable. Please check the «Editable» property of your placeholder to make sure it is not set to «Cannot be edited» when trying to format it.

Show as

Use the «Show as» property to define the appearance of the «Placeholder» in the Document.

Positioning

The «Placeholders» used in the «Designer» are native Word «Content Controls». «Content Control» containers cannot be placed freely on your document. They can only be placed in-line within your text. They are not like pictures that can be (floating) placed anywhere on your document offering many different anchoring options.

Positioning Placeholders freely on your page including header and footer

The way to overcome the native Word «Content Controls» positioning restriction is to use «Text Boxes» (Insert -> Shapes -> Text Box). «Text Boxes» are like pictures and can be placed freely on your document. The trick is to place your «Placeholder» within a «Text Box» that can be positioned anywhere you wish. «Text Boxes» also work in the header and footer so you can also place your «Placeholders» freely anywhere in the header and footer utilizing «Text Boxes».

Here is how to do it:

Word Insert Text Box
  • Create a new «Text Box» by selecting the «Text Box» Shape from your «Shapes» menu on the «Insert» tab.

  • With the «Text Box» shape selected mark (click and drag) the area on your document where you want to place your «Text Box». When letting go of the mouse you will see your new «Text Box».

  • Use the many anchoring options to place your «Text Box» according to your design. Make sure it is relative to the page in case you do not want it to flow with your text.

  • Creating your «Placeholder»: Make sure the cursor is blinking within the «Text Box» and then create a new «Placeholder» using the «Wizard»

  • Finish customizing your «Placeholder» as desired.

  • Verify your work by launching the «Wizard» from your «Designer» Add-in and making your data input accordingly.

Value

Learn more about how to put together «Placeholder Value» formulas that display the data the user has selected or entered using the officeatwork 365 «Wizard» add in or when using the simulation of that add in as part of the officeatwork 365 «Designer» add in.

Format

Designer Placeholder Content Properties

The format option defines in what format the Value will be sent to Word. So if you want Word to insert your Value as a picture you need to select one of the picture formats. If you want it to format is as HTML you need to pick the HTML version. If you want no formatting at all you just choose the Plain Text option.

Plain Text

Use the Plain Text format if you want to have your Placeholder to display the value entirely formatted in the way the Placeholder itself is formatted.

HTML

Use the HTML option if you want to add some formatting to the value your Placeholder will display. Typically, you would add things like bold or heading style markers to display HTML supported formatting in your Placeholder value. This could look as simple as this: ‘my <b>bold<b> text’ producing this outcome: ‘my </b></b>bold text’.

OOxml

Use the OOXML option if you want to add some complex formatting to the value your Placeholder will display. Please be aware that this is an advanced feature and should only be used by professionals that are fully aware of the OOXML format.

Picture from public URL

Logo Contoso Group

Use this option if you want to the value your Placeholder will display as picture. In this case you need to make sure that the value contains a sound URL pointing to an image reachable by an secured (HTTPS) URL.

Please note: The URL must be reachable via HTTPS and must be CORS enabled.

Picture from SharePoint online URL

Use this option if you want to the value your Placeholder will display as picture. In this case you need to make sure that the value contains a sound URL pointing to an image within your SharePoint Online tenant as word will display a picture based on that URL. Typically, you would use the value of a hyperlink column in SharePoint to capture that URL. This could look as simple as this: ‘{{ field(‘Organization’, ‘From’).logoHeader }}’ where the value of the logoHeader column in SharePoint contains a URL to an image stored in one of your Document Libraries in your SharePoint Online tenant.

Tip: Learn more about how to insert a picture from SharePoint Online here.

Note: Please do not use the BMP image format as images in that format tend to be large. This will then result in lengthy download times often decreasing the user experience substantially.

Value

Static values

To display static values just type the text you want to see into the value field.

Dynamic values (Functions)

To calculate Dynamic values, you can use officeatwork specific functions as listed on the Functions page.

Formatting

Placeholders can be configured so that they show their content in a formatted way. Learn more about how to format your placeholder content using the methods described below.

HTML

A simple way to format your placeholder is to use HTML syntax to define the look of your content in your placeholder. This will of course only work if your placeholder format is set to HTML.

Word Styles

A very powerful way to do formatting is to reference an existing Word style (Word paragraph styles only) in your placeholder content. To do that you can use the HTML class attribute.

Sample 1 (custom style)

<p class="mystylename">My Text</p><br>

In this example the class attribute is referencing the style called 'mystylename'. This will then format the 'My Text' using the 'mystylename' Word Style.

Please note: If you use a style name that does not exist, the Designer Add-In will create the style for you.

Please note: Be aware that if you type a new style name slowly, it could happen that the Designer Add-In creates multiple styles while you are typing. So, it might be best to paste the style names in one go to avoid creating unwanted styles!

Please note: If you are referencing an already existing style be aware that the Designer Add-In will only recognize styles in lower caps (Word limitation). So please make sure that any existing custom style you want to reference is in lower caps.

Please note: If you are referencing an already existing built in style make sure you have used it at least once before you use it in your HTML. If the style has not been used in your document before, the style will lose its formatting when used for the first time via your HTML.

Please note: adding a <br> at the end of your HTML is currently necessary due to a bug in Word.

Sample 2 (built-in style)

<p class="msoSubtitle">My Text</p><br>

In this example the class attribute is referencing a built-in Word style called 'Subtitle'. This will then format the 'My Text' using the 'Subtitle' Word Style.

Please note: adding a <br> at the end of your HTML is currently necessary due to a bug in Word.

Bold

With the <b></b> tag (b standing for bold or strong) you can for instance have parts of your content appear in bold.

Sample

This is <b>my</b> text

This sample will appear as 'This is my text' in the placeholder in Word.

To learn more about how to use HTML to format your content check out any HTML reference. Be aware that not all HTML options will be supported by Word.

Functions

To calculate Dynamic values, you can use officeatwork specific functions as listed below as well as the functions described on the Nunjucks documentation pages. Each function must be encapsulated by two curly brackets on either side {{ function() }}. Please note that when you are using block functions like If() or Case() with curly bracket and percentage character {%  …  %} that functions within need only one set of curly brackets {%   { function() }   %}. Please also note that when nesting functions that {{ function(function()) }} that only the most outer function needs curly brackets.

This is a list of additional functions available in the Designer:

field()

If you want to insert a reference to data the users selected or entered in the Wizard Add-In you can use the field() function.

Syntax

{{ field(‘InputFieldName’, ‘InputFieldGroup’).FieldName }}

Sample 1
This will output the value of the property ‘DisplayName’ of the ‘ContactPerson’ input field in the ‘From’ group:

{{ field(‘ContactPerson’, ‘From’).DisplayName }}

formatDateTime()

If you want to insert a reference to a date the users selected or entered in the Wizard Add-In you can use the formatDateTime() function. Visit the official Moments reference to learn more about all the formatting options available to you.

Syntax

{{ formatDateTime(‘ISO_Date’, ‘Format’, ‘Local_Code’) }}

If you want to insert a reference to a date the users selected or entered in the Wizard Add-In you can use the formatDateTime() function.

Sample 1
This will output the date as follows: 7/8/2017. This is the default format.

{{ formatDateTime(field(‘Date’).value, ‘l’) }}

Sample 2
This will output the date as follows: 2017 08 07

{{ formatDateTime(field(‘Date’).value, ‘YYYY MM DD’ ) }}

Sample 3
This will output the date as follows: Monday, August 7th 2017

{{ formatDateTime(field(‘Date’).value, ‘dddd, MMMM Do YYYY’) }}

Sample 4
This will output the date as follows: Montag, August 7. 2017

{{ formatDateTime(field(‘Date’).value, ‘dddd, MMMM Do YYYY’, ‘de-de’) }}

formatNumber()

If you want to insert a number in a formatted fashion you can use the formatNumber() function. Visit the official NumberFormat reference to learn more about all the formatting options available to you.

Syntax

{{ formatNumber('number', { 'options' }, 'locales') }}

Sample 1
This will output the number in this format: 12,345.68

{{ formatNumber('12345.678', { style: 'decimal', useGrouping: true, maximumFractionDigits:2 }, 'en-US') }}

Sample 2
This will output the number in this format: £ 12'345.68

{{ formatNumber('12345.678', { style: 'currency', currency: 'GBP', useGrouping: true, maximumFractionDigits: 2 }, 'en-UK') }}

if()

If you want to apply a condition like if in your placeholder you can use the if() function. 

Syntax

{% if variable %}
     It is true
{% endif %}

Sample 1
This will output the Contact person's birthday only if the Contact person is of type 'Private'.

{% if field(‘ContactPerson’, ‘From’).Type == "Private" %}
     {{ field(‘ContactPerson’, ‘From’).Birthday }}
{% endif %}

More Function

Learn more about other available functions in the Nunjuks documentation mentioned in the References section below.

References

Nunjucks: The templating engine used to evaluate the Value field is called Nunjucks. Learn more about how to write formulas with Nunjucks here: https://mozilla.github.io/nunjucks/templating.html

Moments formats: When using the formatDateTime() function you can find more details regarding the formatting parameters in the Moment.js documentation here: https://momentjs.com/docs/#/displaying/format/

Moments simulation: To learn more about the moments format and language support you can use the simulation offered at the bottom of the moments home page: https://momentjs.com (the language local can be found here: moment.locale() – in the Multiple Locale Support section)

NumberFormat: The numberFormat() function is based on a standardized browser functionality. You can find detailed description about the syntax here:
https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat

Images

To display an image in your placeholder you must select either 'Picture form public URL' or 'Picture from SharePoint Online URL' as the type of your placeholder content. Additionally, the content value field must contain a URL allowing the Add-in to fetch the referenced image to display it in the placeholder in the document.

Linking a Placeholder to images stored in SharePoint

A typical scenario for showing images on documents or templates would be a company logo. In most cases, you do not just choose to display an image on a document or template but a set of data including an image. That is why in most cases images would be linked indirectly via a list in SharePoint.

So let’s look at the scenario where you would want to place your company logo onto a document or template:

  • Create a «Document Library» in SharePoint for your images.

  • Upload your images to that «Document Library».

  • Create a SharePoint «List» for your company entries.

  • Add all necessary columns to the «List» like «Address», «City», «Phone» and of course a column for the logo. That column needs to be of type «Hyperlink or Picture».

SharePoint site settings create hyperlink field
  • Now create a record for each of your companies and copy the URL of your logo image you stored in the «Document Library» into the ‘Hyperlink or Picture’ column you created in your SharePoint «List».

  • Use the «Designer» Add-in to create an «Input Field» that references your «List» you just created in SharePoint.

  • Then use the «Designer» Add-in to create a «Placeholder» of type «Picture from SharePoint Online URL» that references the URL of the «Hyperlink or Picture» column in your SharePoint «List».

  • Finally, use the «Preview» button in the «Designer» Add-in to verify your work.

Preview

Top
Designer Ribbon

The «Preview» button in the Word ribbon will launch the «Wizard» Add-In and is designed to help you understand if your template will actually work with the different data users can select and input. Learn more about the «Wizard» Add-In here.

Publish

Top
Designer Publish

The publish page is split up into three steps «Verify Design», «Activate placeholders» and «Distribute Design».

Verify Design

This step is designed to guide you through the process of verifying your design and its behavior by simulating user input using the «Wizard» Add-In. To launch the «Wizard» Add-In just click on the «Preview» icon in the Word Ribbon within the «Designer» Add-In ribbon group.

Activate placeholders

Once you are finished with verifying the design you want to make sure that all your simulation data will be removed. To do this click on the «Activate Placeholders» (1) button. This will clear all of your simulation data and will reveal the placeholder text defined for each of your «Placeholders».

Distribute design

Congratulations, once you are finished with verifying the design and you have removed the simulation data created with the «Wizard» Add-In using the «Activate Placeholders» button, you are ready to save and distribute your template as you require. Please consider using the officeatwork «Template Chooser» Add-In as the ideal solution to promote you templates within your organization.

Embedding Add-In

Top

Open Add-in together with a document

You might want this app to open alongside your document automatically. To actively embed the Add-In into your currently open document, please follow the steps below:

Document
  • Open the Add-In 'Settings' menu.

  • Click on the 'Document' option.

  • On the 'Document' pane, choose your Embedding option (1).

  • Click 'Save' to save your changes.

Attention:

Please be aware that automatically launching an app, together with a document, will only work if:

  • The user opening the document, with the embedded app, has the app available already, and,

  • The Add-In deployment method is the same for both the user who embedded app and the user opening the document, with the embedded app.

For example, if one user acquired the app from the Office Store, and the other user acquired the app via centralized deployment, the embedding will not work for both users. It will only work for the user who embedded the app in the document. To avoid this platform limitation, please ensure that all your users in your organization acquire the app using the same deployment method, preferably using centralized deployment

Embedding options

Never

Choose this option if you do not want the Add-In to open together with your document (default setting).

Once

Choose this option if you want the Add-In to only open the next time you open your document, after that it shall not open automatically anymore. 

Always

Choose this option if you want to have the Add-In open together with your document all the time. Note that the Add-In will also open if you close your document with the Add-In closed and then re-open the document.

Business Operations Guide

Introduction

Top

This Business Operations Guide is aimed at users that are responsible for the successful implementation and running of the officeatwork Apps and Add-Ins in their organization. This guide also includes a Roadmap section where you can learn more about existing and upcoming features.

Apps & Add-Ins

Top

The following Apps and Add-Ins are included in the 'Designer'.

Supported Applications

The 'Designer' runs within the following Microsoft 365 applications on Windows, Mac, iPad and Office Online:

Word
Word
Word
PowerPoint
(coming soon)
Word
Edge
Word
Chrome
Word
Safari
Word
FireFox

Please note:  The 'Designer' Apps might offer different features depending on the different Microsoft 365 applications on the various platforms.

Supported Storage Services

The 'Designer' supports the following storage locations:

Word
SharePoint Online
Word
Microsoft Graph

Supported User Accounts

The 'Designer' supports the following user accounts:

Word
Microsoft 365 Account
Word
Microsoft Personal Account

Variations

The 'Designer' app will offer different features based on the account you are using or if you are a subscription user or not. If you are evaluating the app without a subscription you will not be able to configure all the options a paying user with a business subscription would be able to. If you sign in using a personal Microsoft account you will also not be able to configure any settings. Additionally, features available only to Microsoft 365 Users like SharePoint Online will also be missing.

Personal

FREE

when using a personal Microsoft account.

Storage Locations

SharePoint

Microsoft Graph

Tenant Settings

Feature Settings

Custom feature settings like disabling OneDrive or removing the Yammer and Feedback form link.

Advertisement Free

New users will receive no e-mails from officeatwork.

Sample Libraries deactivated

Business

Evaluation

when using a Microsoft 365 account for evaluation purposes.

Storage Locations

SharePoint

Microsoft Graph

Tenant Settings

Feature Settings

Custom feature settings like disabling OneDrive or removing the Yammer and Feedback form link.

Advertisement Free

New users will receive no e-mails from officeatwork.

Sample Libraries deactivated

Business

Subscription

when using a paid subscription with a Microsoft 365 account.

Storage Locations

SharePoint

Microsoft Graph

Tenant Settings

Feature Settings

Custom feature settings like disabling OneDrive or removing the Yammer and Feedback form link.

Advertisement Free

New users will receive no e-mails from officeatwork.

Sample Libraries deactivated

Analytics

Top

officeatwork provides analytics support that will allow you to get insights into the usage of your assets and data used within the officeatwork Apps and Add-Ins. To capture this information you need to set up a data capturing stream that will allow the officeatwork Apps and Add-Ins to send your usage data into a storage location you own.

The attributes per event we provide are as follows:

  • action (Sample: 'Launched', 'Folder Loaded', 'Template Chosen', 'Document Creation Requested', etc.)

  • addInName (Sample: 'Template Chooser, 'Content Chooser', etc.)

  • assetExtension (Sample: 'docx', 'jpg', 'svg', 'html', 'xlsx', etc.)

  • assetId (Sample: '715IQYDHBZCGRAG5NOCVFIQUSBB7ITQ5LN' etc.)

  • assetName (Sample: 'Letter', 'Project Budget Sheet', 'Memorandum', etc.)

  • assetUrl (Sample: 'https://tenant.sharepoint.com/sites/AllCompany/Documents/General/Contents/Legal/TrademarkStatement.docx'

  • hostApplication (Sample: 'Excel', 'Word', 'SharePoint', 'Browser', etc.)

  • hostPlatform (Sample: 'Windows', 'iOS', 'Mac', 'Web', etc.)

  • hostVersion (Sample: '16.35.218.0', '2.27.709.0', '16.01', etc.)

  • sourceName (Sample: 'Corporate Templates', 'Sales Contents', etc.)

  • sourceType (Sample: 'OneDrive', 'Teams', 'SharePoint', 'Pixabay', etc.)

  • timestamp (Sample: 2018-10-11T12:27:22.205Z)

  • userDisplayName (Sample: 'Joe Miller', etc.)

  • userEmail (Sample: 'joe.miller@sample.com')

  • userId (Sample: '43d7d85d-e05e-4adf-bd1f-691b0a53bb64', etc.)

Power BI

To gain insights into your officeatwork apps and Add-In usage via Power BI you need to follow these three basic steps:

  • Set up a Streaming Data Set in Power BI

  • Register your Streaming Data Set API URL for each of your officeatwork Add-Ins and Apps using the officeatwork Admin Center

  • Create Reports in Power BI

Setting up your Power BI Streaming Data Set in Power BI

Please check out the Power BI documentation to learn how to set up a streaming data set. The steps below will provide some important additional details you will need to take into account when creating your Streaming Data Set:

  • On any of your Power BI workspaces click the '+' button (top right corner) in Power BI to create a new streaming dataset!

  • For the source of your dataset choose API.

  • For Dataset name provide any name you wish. Sample: 'officeatwork-usage'.

  • Create a field for ALL attributes we offer (Sample: 'action', 'addInName', etc.). Make sure to choose 'DateTime' for the timestamp attribute and 'Text' for all others in the format dropdown.

  • Make sure to switch on 'Historic data analysis'.

  • Once created you can get the API info for your new streaming data set and copy the value from the 'Push URL' starting with 'https://api.powerbi.com/... '. You will need this in the second step!

Register your Streaming Data Set API URL for your officeatwork Apps and Add-Ins

Please make sure that before you start this step that you have the 'Push URL' form the previous step in your clipboard.

  • Launch the officeatwork Admin Center

  • Select the app on the left you want to configure (for example the 'Template Chooser').

  • Click the 'Manage' button on the 'Analytics' panel.

  • Paste the 'Push URL' into the 'Power BI streaming dataset API endpoint URL'.

  • Click 'Save' at the bottom of the pane.

  • Done.

Create Reports in Power BI

You can now go ahead and create as many reports in Power BI as you wish. Please be aware that you need to use one of the officeatwork Apps or Add-Ins after connecting your Power BI streaming dataset for your reports to showy any officeatwork usage data!

Roadmap

Top

Under Investigation

Planned

In Development

Released May 2020

Released April 2020

Released March 2020

Released February 2020

Released January 2020

Released November 2019

Released March2019

Released January 2019

Released September 2018

Released MAY 2018

Released August 2017

Released July 2017

Released June 2017

Released May 2017

Released January 2017

Released September 2016

Released May 2016

Released December 2015

IT Operations Guide

Deployment

Top

Office Add-ins

Historically you might be used to deploy Office Add-Ins using MSI packages. This is not an option for our modern officeatwork cloud SaaS Office Add-Ins anymore as they are not built with the older (COM) platform dependent technology.

Please note:

We do not offer any MSI packages for our modern web-based Office Add-Ins.

Centralized Deployment

The by far best way of deploying Add-ins for Microsoft 365 is using the new 'Centralized Deployment' feature inside the Microsoft 365 admin center. This feature will allow you to deploy Add-Ins to your users on all devices and platforms. There are no local installations necessary for this to work.

You can reach 'Centralized Deployment' by going to: Microsoft 365 admin center > Settings > Add-ins > + Deploy Add-In

Please note:

You might want to check if your tenant is ready for 'Centralized Deployment'. Here is a link to the Microsoft support document called 'Determine if Centralized Deployment of add-ins works for your organization' that will explain the requirements in detail. Microsoft also offers an Add-In (Word & Excel) that will perform automated checks to see if your infrastructure is ready for Centralized Deployment. It's called 'Compatibility Checker for Centralized Deployment'.

Please note:

You must be an Microsoft 365 admin to be able to sign in to the Microsoft 365 Admin portal. You will also need to use the ‘I want to add an Add-In from the Office Store‘ option as this will keep your add-ins up-to-date automatically!

Additional Resources

Sharepoint add-in catalog (for older Office versions)

Modern Web Office Add-ins can also be deployed for older Office versions like Office 2013. For that you can use the SharePoint Add-In catalog deployment method. Please note that some features like showing icons in the ribbon in Office will not be available via this deployment path. This deployment method will though work for the officeatwork 365 Template Chooser and Content Chooser Add-Ins. Please expect limited functionality due to missing API's in older Office versions like Office 2013. Check out our compatibility section below to learn more about any missing features for your Office version.

Additional Resources

Office Store

You can find our Add-Ins within the Office Store experience provided within the Office applications. Just use the 'Get it now' button to acquire and deploy the Add-In for the signed-in user only.

Appsource

You can find our Add-Ins for Office on AppSource. Just use the 'Get it now' button in AppSource to acquire and deploy the Add-In. If you are signed-in as a Microsoft 365 administrator, the 'Get it now' button should take you to the centralized deployment experience.

Please note:

If you can manage your AppSource purchases in the Microsoft 365 Admin Center. Here is a link to the Manage subscriptions in Admin Center documentation.

Compatibility

Top

Check out the minimal Office versions required for running the officeatwork Web Add-In on your devices. Also see what specific features of the individual Add-Ins are supported from what version onward.

Minimal Office Version

Minimal Office version required to run the officeatwork App.

Windows

Office 2013 (MSI)

15.0 (4855.1000)

Office 2016 (MSI)

16.0 (4390.1000)

Office 2019 (MSI)

all versions

Office 365 (C2R)

1602 (6741.0000)

Office Online

Office 365

January 2016

Mac OS

Office 365

15.20 (160315)

iPad

Office 365

1.22

General Add-In Features

Ribbon Icon

Access App via one or multiple icon in the Office ribbon.

Windows

Office 2013 (MSI)

not available

Office 2016 (MSI)

not available

Office 2019 (MSI)

all versions

Office 365 (C2R)

1603 (6769.0000)

Office Online

Office 365

January 2016

Mac OS

Office 365

15.33.0 (1704.0900)

iPad

Office 365

not applicable

Centralized Deployment

Deploying Word, Excel and PowerPoint Apps in Office.

Windows

Office 2013 (MSI)

not available

Office 2016 (MSI)

not available

Office 2019 (MSI)

all versions

Office 365 (C2R)

1704 (8067.2115)

Office Online

Office 365

January 2016

Mac OS

Office 365

15.34.0 (1705.1500)

iPad

Office 365

not applicable

Automatically open a task pane

Automatically load an App and open a task pane when opening a specific Word, Excel or PowerPoint document.

Windows

Office 2013 (MSI)

not available

Office 2016 (MSI)

not available

Office 2019 (MSI)

all versions

Office 365 (C2R)

16.0 (8121.1000)

Office Online

Office 365

January 2016

Mac OS

Office 365

15.34.0 (1705.1500)

iPad

Office 365

not applicable

MFA (Multi-Factor Authentication)

Top

All the officeatwork Add-Ins require Microsoft accounts to sign-in to the Add-Ins. If you have activated MFA (Multi-Factor Authentication) for our Microsoft Work or School account in Microsoft 365, it will automatically also apply for the officeatwork Add-Ins. You as an Admin do not have to configure any dedicated settings for the officeatwork Add-ins as they automatically 'inherit' your sign-in policy you defined for your organization.

Pre-Consenting

Top

Administrators of a Microsoft 365 tenant can pre-consent access to required scopes by clicking the 'Pre-Consent' buttons listed in the Data Scopes section below. Once done, users of your tenant will not have to individually grant access to the various scopes required by the officeatwork Add-In/App.

Data Scopes

Following our security principles our Apps and Add-Ins do not have their own independent data access definitions. What the Apps and Add-Ins can access is always governed by the data provider.

Microsoft 365

Here are some principles that apply to all the access our Apps and Add-Ins have in Microsoft 365:

  • Data access is always scoped to the signed-in user.

  • officeatwork employees do not get access to your data.

  • Your data is protected by the Microsoft 365 security framework including multi-factor authentication.

  • The actual App or Add-In sign in screens are provided and hosted by Microsoft. You can see that as the officeatwork sign in process displays the identical sign in screens and flow as if you were to sign in to Microsoft 365.

  • Users can only access data within the Apps that they can access based on their existing access rights in Microsoft 365.

  • This also means that a user cannot access data of another user via the officeatwork Apps.

Sign-In
Pre-Consent

For the sign-in process the Add-In requires the following scopes:

  • openid user permission to enable users to sign in to the officeatwork app with their organizational and/or Microsoft Account.

  • openid profile user permission to show the signed-in user in the officeatwork app. This is helpful to assure/confirm the user what account was used to sign-in to the officeatwork app.

  • openid offline_access user permission to enable automatic sign in via refresh-tokens, as without users would have to manually Sign-In every single time they launch the officeatwork app. This scope is only required for Non-SSO enabled host applications.

  • User.Read user permission enable the officeatwork app to be able to read the user's basic properties.

  • openid email user permission to activate the evaluation subscription in the officeatwork app. (this scope will be retired soon)

  • User.ReadWrite user permission to be able to save the user's settings. (this scope will be retired soon)

Office 365 Users - Basic properties
Pre-Consent

For enabling basic user properties the Office 365 Users Input Field has to offer, the officeatwork app requires the following scopes:

  • User.ReadBasic.All user permission to enable the officeatwork app to read basic properties of all users.

Office 365 Users - All properties
Pre-Consent

For enabling all user properties the Office 365 Users Input Field has to offer, the officeatwork app requires the following scopes:

  • User.Read.All admin permission to enable the officeatwork app to read all properties of all users.

Office 365 Users - Limit to group
Pre-Consent

For limiting the selection of available user to a specific group the Office 365 Users Input Field has to offer, the officeatwork app requires the following scopes:

  • Group.Read.All admin permission to enable the officeatwork app to read all groups of the signed-in users.

Contacts
Pre-Consent

To enable the reading of all contacts of the signed-in user, the officeatwork app requires the following scopes:

  • Contacts.Read user permission to enable the officeatwork app to read all contacts of the signed-in users.

SharePoint Online - Lists
Pre-Consent

To enable the reading of any SharePoint Online list or library the signed-in user has access to, the officeatwork app requires the following scopes:

  • Sites.Read.All admin permission to enable the officeatwork app to read all SharePoint lists and libraries of the signed-in users.

OneDrive - Files (Contents)
Pre-Consent

To enable the reading and updating of contents in the document, of linked content files stored in OneDrive content libraries the signed-in user has access to, the officeatwork app requires the following scopes:

  • Files.Read user permission to enable the officeatwork app to read the signed-in user's files.

Teams - Files (Contents)
Pre-Consent

To enable the reading and updating of contents in the document, of linked content files stored in Teams content libraries the signed-in user has access to, the officeatwork app requires the following scopes:

  • Files.Read.All user permission to enable the officeatwork app to read all files of the signed-in user.

All Scopes
Pre-Consent
  • openid user permission to enable users to sign in to the officeatwork app with their organizational and/or Microsoft Account.

  • offline_access user permission to enable automatic sign-in via refresh-tokens, as without users would have to manually Sign-In every single time they launch the officeatwork app.

  • profile user permission to show the signed-in user in the officeatwork app. This is helpful to assure/confirm the user what account was used to sign-in to the officeatwork app.

  • email user permission to activate the evaluation subscription in the officeatwork app.

  • User.ReadWrite user permission to be able to save the user's settings.

  • User.ReadBasic.All user permission to enable the officeatwork app to read basic properties of all users.

  • User.Read.All admin permission to enable the officeatwork app to read all properties of all users.

  • Group.Read.All admin permission to enable the officeatwork app to read all groups of the signed-in users.

  • Contacts.Read user permission to enable the officeatwork appto read all contacts of the signed-in users.

  • Sites.Read.All admin permission to enable the officeatwork app to read all SharePoint lists and libraries of the signed-in users.

  • Files.Read user permission to enable the officeatwork app to read the signed-in user's files.

  • Files.Read.All user permission to enable the officeatwork app to read all files of the signed-in user.

Security

Top

You can find more information about the security of the officeatwork Add-Ins and apps on the Microsoft 365 App Certification Program pages. Navigate to the appropriate officeatwork Add-In/App using the left navigation of the site. There you will be able to learn more on how your data and privacy are adequately secured and protected.

We have built all our Apps with a solid and enterprise prove security architecture. We have chosen an architecture that follows these simple principles.

  • We believe that it is not acceptable that customer data ever gets transferred to any of our officeatwork servers and that we in general limit the data we do have to transfer to our servers to the bare minimum possible.

  • We do not introduce a new permissions or security schema but always use existing permission and security schemas in place offered by the data providers like Microsoft 365, allowing our Add-Ins to only access data the user using the Add-In has already been approved for.

  • All data transfer is encrypted.

  • Any minimal data we store is encrypted.

Data flow

One of the biggest security concerns is how the data the Add-In processes flows and if the user's privacy and the companies IP is protected.

The following describes the main usage scenarios and how the data flows between the different actors like the user, the Add-Ins and other connected services.

Loading Add-In

When the Add-In gets loaded it uses encrypted communications via a high availability Azure CDN service. Loading the Add-In requires no User nor Customer Data.

Add-In loading data flow

Sign-In to Add-In

To sign in to the officeatwork Add-Ins you can use either your Microsoft personal or organizational account. The flow starts with the user signing in using Microsoft's sign in flow. After a successful identification by Microsoft a User Access Token is collected by a trusted officeatwork server side Azure function that then hands the Access Token to the Add-In combined with tenant settings data stored in an officeatwork controlled globally available Azure cosmos DB. This flow takes place without any connection to the customer's data.

Sign in data flow

Using Add-In

While the user is interacting with the Add-Ins data might be required. The access to that data is enabled via the User Access Token allowing the Add-In to read and write data in the name of the User directly without having to bypass any officeatwork server services.

Add-In usage data flow

Service Level agreement (SLA)

Top

All officeatwork SaaS Add-Ins/Apps are hosted across multiple data centers across multiple continents and regions on the Microsoft Azure platform. Please find below the services used with the links to the according Microsoft Service Level Agreement: