The purpose of this topic is to provide the detailed steps required to configure and deploy the Akumina Digital Workplace Foundation Site using the AppManager Version 4.0 or greater release.  The steps will include configuring certain SharePoint options in addition to the options in the Akumina AppManager.

Who should use this Documentation?

To fully use this documentation, you should be a SharePoint Administrator as well as an Akumina AppManager Administrator.

Configuring Your Site Collection

Create the Site Collection and Add the AppManager App

The first step is to create the Site Collection into which you want to add the Akumina Foundation site.  Once the Site Collection is created and configured, add the AppManager App to the root of the Site Collection (see separate documents “Installing AppManager in the Cloud” or “Installing AppManager on Premises” for details of installing AppManager and connecting to your site collection).

IMPORTANT: Ensure that the user who will be setting up AppManager and deploying the Akumina Foundation site is in the OWNERS group for the parent site of the Site Collection.  It is not sufficient for that user to just be a Site Collection administrator. Enable Specific “Site Collection Features”

On the “Site Settings > Site collection features” (found under Site Collection Administration) page, verify the following features are ACTIVE:

• “SharePoint Server Standard Site Collection features”
• “SharePoint Server Publishing Infrastructure”.
• “Workflow”

Also in Site Collection Features, DEACTIVATE the Limited-access permissions lockdown (required for the DMS and DSL):

Enable Specific “Manage Site” Features

• Navigate to “Site Settings > Mange site features”.
• Verify that the “SharePoint Server Publishing” feature is “Active” (blue button) on the site. If this feature is not Active, then the “Activate” button will be displayed, click on “Activate”.

Adjust the Versioning Settings for Specific Libraries

• Versioning on certain libraries must be set correctly to allow the Akumina Foundation site deployment tool to add files and folders.
• On the following libraries in target Site Collection
  • Documents
  • Pages
  • Style Library
  • Images

• Ensure that the Versioning Settings are as follows:
  • Require content approval for submitted items – NO
  • Create a version each time you edit a file in this document library – Create Major Versions
  • Required documents to be checked out before they can be edited - NO

Configuring AppManager for Akumina Foundation site

In addition to the items covered in the AppManager installation documentation, there are some specific settings required for the Akumina Foundation site.

 

Verifying Values in "interchange.settings.config"

GUID Value in the Background Processor Key

Regardless of whether or not you are setting up forms support (see separate Forms Setup Guide), there must be a value set in the following key which resides in the interchange.settings.config file.  Best practice is to use a GUID generator (such as https://www.guidgenerator.com/ ).  Copy this value as it will be used in the “InterChange Query Key” field when creating the Akumina Foundation site.

  <add key="akumina:BackgroundProcessorKey" value="GUID VALUE HERE"/>

 

Azure Storage Account Configured for using the Graph API (O365 only)

If the Foundation Site will be utilizing the Graph API for connection to Azure AD (to enable functionality such as the People Directory, Akumina Workspaces, My Calendar and others) an Azure Storage Account must be configured and the keys specified in the interchange.settings.config file.  The following is the format of the key to set:

<add key="akumina:RemoteStorageConnection" value="DefaultEndpointsProtocol=http;AccountName=myAccount;AccountKey=myKey;" />

Replace the highlighted value above with the Connection String generated in the Azure Storage Account which contains the protocol, account name and account key.

Example Connection String Value:

DefaultEndpointsProtocol=https;AccountName=akuminadiag333;AccountKey=5W0jT33da5SLIX/DgtnjyHdYbyWk2JhVyeGfy7AXoRP7bps9L745WJLeHVMqhd3qsdOKQQEjPlf2ONMfYG4IWg==;

Site based Global Settings in AppManager

The first time an AppManager Admin accesses AppManager in a new Site Collection or a newly created sub-site, they are brought to the Settings screen to define the Global Settings for the site. The first action is to configure the Global Settings for the Site.

Click on Edit for Global Settings

For Global Settings, the key items to specify are

• Site Address should be the full address and not just the root of the tenant
• For example:  https://akuminadev02.sharepoint.com/sites/Akqa20PLAIN1010B (ensure that there is no / at the end of the URL)
• Administrator Group for AppManager (access to the gear icon, Admin settings and Management Apps)
• Multiple SharePoint groups can be mapped
• Reporting Access Group (enabling users to access the General Forms Reporting App)
• Multiple SharePoint groups can be mapped

Save and Exit to return to the previous screen.

Deploying the Akumina Foundation site

 

Creating the Akumina Foundation site using the Site Creator App

• Launch AppManager and navigate to the Management Apps tab
• Launch the Site Creator App
• In the Site Creator App interface, select the “Digital Workplace Foundation Site” option (ensure that the Current Site in the top left of the screen is set to the root site of the Site Collection).

Important Note: The following description applies to the case where the “Digital Workplace Core Site” has not yet been deployed.  In this case, deploying the “Digital Workplace Foundation Site” will display the input fields and will deploy BOTH the Core and the Foundation Site.  If the Core Site has already been deployed, certain fields as indicated (Part of Core Site) will not be displayed.

There are three actions that can be selected:

• Create New Installation – used to deploy a new parent site in a Site Collection for the first time
• Execute Individual Deployment Steps – used to selectively execute one or more deployment steps

Update Configuration Settings – used to change the settings in an existing parent siteIn this case we are deploying a new parent site so will select “Create New Installation”.  The list of options available will be displayed and are broken down as follows: (Multilingual Feature Enabled and Workspaces Feature Enabled fields are covered elsewhere)

• InterChange URL and Query Key (Part of Core Site)

The URL will be displayed in the AppManager address bar.  The Query Key is the value that is set in the AppManager web.config file for the"akumina:BackgroundProcessorKey"

• Enable Azure AD (Part of Core Site)

Note: Depending on your version, the Subscription ID field may not be present.

The site can be deployed with or without the Azure AD connection enabled.  With Azure AD enabled, and the associated fields completed, features such as Akumina Workspaces, content targeting, the Directory, shared calendars, My Activity, My Events, Skype integration and more are enabled.  If not enabled during the initial deployment, it can be enabled later using the “Update Configuration Settings” option under the “Digital Workplace Core Site”.

See the topic “Graph API Connection for Azure AD” for details on how to obtain the Client ID, AAD Client Secret, Subscription ID, SkypeApiKeyCC and SkypeApiKey.

• Caching Strategy (Part of Core Site)

The Caching Strategy can be set to light (1 min), medium (60 mins), heavy (360 mins), or extreme (1440 mins).  You can also enter a specific integer value for the number of minutes to cache.  This cache will apply globally, but is overridden by any cache setting on an individual control.

• Enable Debug Mode (Part of Core Site)

Setting this option enables the use of the “Cntrl-uparrow” to view the current site settings (such as groups and AD values) that are active for the current logged in user.

• Search Page Exclusion List (Part of Core Site)

This is a list of the pages which you want to EXCLUDE from the search results.  A page listed here will not be crawled by the search engine.  Pages are separated by commas and can use a relative URL path.  The default search, page not found and logout pages are automatically populated in this field.  You can add additional pages now or after the site deploy.

• Language Neutral List (Part of Core Site)

This list only applies if the Multilingual Feature is licensed and enabled.  It calls out the SharePoint lists that do not need to be multilingual enabled when multilingual support is added.

• Setting the Site Logo and Theme

The default logo is displayed, but at this time a new logo file can be selected

There are 9 themes included from which to choose. In addition, a custom theme can be added by a developer/designer.  Themes can be updated at any time after the initial deployment using the “Update Configuration Settings” option in the Digital Workplace Foundation Site

• Creating default departments

Selecting this option will automatically deploy 4 “department” subsites titled Finance, Marketing, Human Resources and IT.  This option can be helpful when deploying as a reference site, or if those departments exist in your organization.  Subsites can also be individually generated at any time after this initial deployment.

• Google Map Key

This is the GoogleMapApiKey which is used for the “Traffic” control in the footer of the Akumina Foundation site.  A free API key can be obtained at the following URL: https://developers.google.com/maps/documentation/javascript/get-api-key

Once all the desired options are specified, use the "Deploy All"  button to start the deployment.  This will provision all of the Master Page and supporting pages/layouts, lists with default content and friendlyURLs configured, default term sets, all supporting images, as well as the Apps for the site in AppManager. Status messages will display the progress of the provisioning at each step, and a Success message will be displayed once the provisioning is complete.

When complete, access the site and you should be taken to the new Akumina Foundation site homepage.

 

Creating a Department Sub-Site using the Site Creator App

• Launch AppManager and navigate to the Management Apps tab
• Launch the Site Creator App
• In the Site Creator App interface, select the “Digital Workplace Department Sub-site” option (ensure that the Current Site in the top left of the screen is set to the root site of the Site Collection).
• There are two actions that can be selected:
  • Create New Installation – used to deploy a new department sub-site
  • Upgrade Site – used to update the functionality in an existing department sub-site

In this case we are deploying a new department sub-site so will select “Create New Installation”.  The list of options available will be displayed and are broken down as follows:

• Set a title for the site which will be displayed for users
• Set the URL value
• Inherit permissions from the parent site
• If this is checked, the permissions group created for the parent site will be used.
• If it is not checked, unique permissions group for the site will be created (Owners, Members, Visitors groups)
• Set the color of the site image – this color is used for the site on the Department Listing page as well as for the top bar that appears on the department pages.

Once all desired options are specified, use the   button to start the deployment.  This will provision the supporting pages/layouts, lists with default content and friendlyURLs configured, default term sets, all supporting images, as well as the Apps for the department site in AppManager. Status messages will display the progress of the provisioning at each step, and a Success message will be displayed once the provisioning is complete.

Setting Permissions on Core Supporting Lists

See also: Setting Permissions on Core Supporting Lists

There are a number of lists that support the Akumina Framework and the Foundation site that ALL users must have edit, contribute and read permissions to (especially visitors). As an example, all users must be able to have their personal Dashboard configuration data saved in the DashboardDragDrop_AK list. which requires their user to be able to write to that list.

Here are the lists that must be permissioned for everyone to be able to edit, contribute and read:

• PageWidgets_AK
• PageData_AK
• WidgetProperties_AK
• DashboardDragDrop_AK
• FormSubmissions_AK
• AppDisplayOrder_AK
• Comments_AK
• MyDashboard_AK
• ITRequestAK
• VacationRequestAK
• FeedbackFormAK
• Favorites_AK

Additional Configuration Steps if AzureAD is enabled

If you enabled Azure AD in the site so that you could take advantage of the additional features, there are a few additional steps to complete the configuration:

 

Run the PeopleSync Console App First

Make sure that the PeopleSync Console App has been installed, configured, and has run at least one synchronization.  This will populate the AzureAD information so that it is available to the AppManager and to your site.

See Using the PeopleSync Console App

 

Mapping Your Site Departments to its Azure AD Equivalent

This step can be done at any time, and whenever you add a new department to the site.  This mapping is used to determine, when using targeting, the correct department targeted content for the current logged in user.  To perform the mapping, access the “Department Manager” in the Management Apps tab.

Select the Department Sub-site you want to map from the “Sites” drop down, then click on “Load Properties” to view the values for that subsite.  This interface also allows you to change the Title and the image color for an existing site at any time, as well as exclude a site from appearing on the Department Listing Page (for a non-department subsite).  To map the selected site to its Azure AD equivalent, use the Department drop down which will display all of the Azure AD values set in its the “Department” field.  This is why it is important to do the People Sync step PRIOR to this step as the Azure AD values come from there.

Setting the Group Calendar name for the Company Calendar

The Company Calendar connects to a group calendar in Office 365 to get its data.  The name of the group calendar needs to be set either in the Widget Manager or using the front end widget edit.

To set using the Widget Manager Management App:

• Access the “Widget Manager” App
• Under the CompanyCalendar widget, click on "View Instances"
• Edit the appropriate CompanyCalendar instance (the Foundation site only deploys one instance)
• Set the AAD group name for the Company Calendar in the first property field labeled "{calendar.friendlyname_groupname}"

To set using the front-end Widget Editing:

• Navigate to the Company Calendar Page
• Enable the widget edit mode on the front-end site by clicking on the tray icon in the bottom left () and then selecting the Widget Edit function ()
• Click on the CompanyCalendar widget by clicking on the "Please check the Group Name property..." message displayed. This will open the widget properties panel.
• In the Properties panel, enter the Group Name for the shared Calendar (the AAD Group Name) and click "Update"

Additional Configuration Changes if AzureAD is NOT Enabled

If you deploy the Akumina Foundation site without the Azure AD support, then there is functionality which is initially deployed on the site but which you may want to remove.  The following items will not function without Azure AD (Graph API) support enabled:

 

Left Rail

(these items can be hidden in the left rail using the “Rail Manager” Management App

• My Events
• My Colleagues
• My Activity

Main Navigation

(these nav items can be removed using the Main Menu Content App)

• Directory
• Company Calendar

Dashboard

(these can be disabled using the “Enabled” setting in the Dashboard Widget Manager Management App).

• My Team

Enabling "My Apps" Functionality for IE Browsers

If your organization is user Internet Explorer browsers, there is an additional setting required to enable the “My Apps” functionality from both the left rail and the widget on the Dashboard.

Access the “DigispaceConfigurationIDS_AK” list and set the “LOADER_STEPS_ENABLE_FETCHSPGROUPS” key to “true”

Refer to the topic "Additional Steps for IE Browser Support On-Prem" or "Additional Steps for IE Browser Support Cloud" for all required steps to support IE browsers.

 

Configuring Search in the Akumina Foundation site

Once the Akumina Foundation Site Home site is provisioned, there are a number of configuration steps needed to enable the search functionality for the controls.

Setting Up the Search Schema for indexing Akumina Foundation Site Page Data

To properly index the content of the Akumina Foundation site so that search results will return the page the content is on rather than the SharePoint List that contains it, the Akumina Foundation site includes a special “PageData” function.  Search needs to be configured as follows to enable this function.

Ensure that the Required Crawled Properties exist in the Search Schema

There are two crawled properties that need to exist for this step: ows_PageDataSiteId and ows_PageDataTitle.  To ensure these exist:

• Navigate to Site Settings, under Site Collection Administration, select “Search Schema”.
• Select “Crawled Properties” from the sub-menu
• Filter for “ows_PageDataTitle”.
  • If the crawled property exists, then go on to Section “Navigate to List PageData_AK”
  • If the crawled property DOES NOT exist:
    • Browse a few pages on the Akumina Foundation site site
    • Navigate to Site Contents, and open the PageData_AK list.  Verify there is at least one item entry in the list, with data under the “PageDataTitle” and “PageDataSiteId” columns
    • Run a crawl on the site which will pick up the two columns and add them to the Crawled Properties list

Create New Manage Properties in the Search Schema

• Navigate to Site Settings, under Site Collection Administration, select “Search Schema”.
• Create two new managed Properties
  • PageDataSiteId
  • PageDataTitle
• For each Property set the properties as:
  • Searchable
  • Queryable
  • Retrievable

• For “Mappings to crawled properties”, click “Add a Mapping”-only ONE value will be added as a mapping for each New Managed Property.
• Example for PageDataSiteID:
• Find - PageDataSiteId – select - ows_PageDataSiteId – click OK
• Example for PageDataTitle:
• Find - PageDataTitle – select - ows_PageDataTitle – click OK
• Click OK at the bottom of the page to complete the Managed Property definition.

Note: After completing the mappings, it is recommended that you confirm the mappings exist and are correctly configured by returning to the Search Schema page and once again filtering for “PageDataSiteId” and “PageDataTitle” and verifying their settings.

Navigate to List "PageData_AK"

On the root site collection, site contents, navigate to the list “PageData_AK”, verify that there is content in this list.  Content gets added to this list by visiting site pages.

 

ReIndex List PageData_AK

On the root site collection, site contents, navigate to the list SETTINGS page of the list “PageData_AK”.

• On the settings page click on “Advanced settings”.
• Scroll down the page and select “Reindex List”

NOTE – IT CAN TAKE UP TO 24 HOURS BEFORE THE CRAWL WILL TAKE EFFECT ON THIS SITE AND RETURN SITE SEARCH RESULTS.

Search and Offline Availability

Trigger a search for the entire site by accessing Site Settings/Search and Offline Availability

Select “Always index all Web Parts on this site”, click on Reindex site and then click “Reindex Site”.  Once complete, click “OK”

Setting up the Search Schema for the Document Summary List.

For the Document Summary List (DSL) certain search properties need to be configured to support its functionality:

• Navigate to Site Settings > Search Schema (found under the Site Collection Administration section).
• Enter LastModifiedTime into the “Manage property” input field and click .
• Under the Property Name Column, find LastModifiedTime click on the Dropdown arrow and from the menu, select “Edit/Map Property”.
• Scroll down the page and for the “Mapping to crawled Properties” click on all properties that exist there and “Remove Mapping”.
• Click on “Add a Mapping” search for “Basic:14”, select and click on OK.  The Mapping to crawled properties should then look as follows:
• Scroll down and click on OK.

 

Configuring Libraries for the DMS and Document Summary List

 

Configure Audit Log Trimming for the Popular List

• Navigate to Site Settings > “Site collection audit settings”.
• On the Configure Audit Settings page, in the Audit Log Trimming section, set “Automatically trim the audit log for this site?” to Yes
• Select the events that you want to audit
• At the bottom of the Configure Audit Settings page click OK.

 

Preparing your Document Library for Drag and Drop, Categories and Tags

If there are columns associated with the library that are marked as “required” then those columns will show up in the “Require Field Modal” as part of the “Drag and Drop” process.  If a library has a Meta Data Column with the name = Category and marked as “required”, then on the Document Management System (DMS) page the documents can be TAGGED with terms associated with the “Term Set” Category” as part of the drag and drop process.  These terms associated with the column Category will also appear and can be used to refine the document grid, when a user click the refiner “Categories” Browse button.

For the DSL Recommended Tab to work, the Term “Recommended” must be added to a Meta Data Column such as “Category”.

Below is an example of setting up a column of type Meta Data “Category” for the document library.

Trusting the Workflows Associated with Forms

• The Forms functionality includes pre-defined review/approval workflows that can be assigned to any form.  The workflows themselves are provisioned and activated as part of the Akumina Foundation site installation, but there is one additional required step to fully enable the functionality for the Site Collection.

 

Find and SAVE the “App ID” for the Site Collections Workflow

To enable the Workflows, we first need to get the “App ID” for workflow for your site collection.

• On the root site of the Site Collection, navigate to “Site Settings” > “Site app Permissions” (found under heading “Users and Permissions”).
• Here you will find an app display name for Workflow – Copy and save the

  “App ID” for the Workflow example: bfacce90-5e7b-48dd-997b-635640c878b3

Grant Permissions for Workflow via {Site Collection}/_layouts/15/appinv.aspx.

• Append /_layouts/15/appinv.aspx onto the Site Collection URL and enter it into a browser
• Enter the “App ID” for Workflow found above into App ID.
• Example: bfacce90-5e7b-48dd-997b-635640c878b3
• Click On “Lookup”, all the field will auto fill in except “Permission Request XML:”
• Paste the following lines into the “Permission Request XML:”, to grant full control permission. (Note:  There are no placeholders in the Scope value below. It is a literal value. Enter it exactly as it appears here.)

<AppPermissionRequests>

<AppPermissionRequest Scope="http://sharepoint/content/sitecollection/web" Right="FullControl" />

</AppPermissionRequests>

• Click on Create.
• Click on “Trust It” for Workflow.

Updating the Foundation Site Settings

After the initial installation, if you need to update any of the settings on a site, access the Site Creator and select the “Update Configuration Settings” action.

To Update the Azure AD Settings, Search Page Exlusion List or Language Neutral List:

• Select “Digital Workplace Core Site” from the dropdown, and then select the “Update Configuration Settings” action

To Update the Site Logo, Theme or Google Map Key

• Select “Digital Workplace Foundation Site” from the dropdown, and then select the “Update Configuration Settings” action

 

Known Issues

Images in AppManager with IE11 and EDGE Browsers

Problem: When viewing image thumbnails in AppManager (for example in the Image Picker or Image Gallery app) using IE11 or Edge, the images may appear broken.  Instead of the image thumbnail, you may see a broken icon as shown below: Resolution: The root URL for the SharePoint tenant must be added to the “Trusted Sites” in the browser (Internet Options/Security/Trusted sites).  This will allow the browser to correctly access the images.

Note that even though the image thumbnails appear broken, selecting an image will still work correctly.

Adding Content Editor web part to page using EDGE browser does not work

There is an issue with editing the Content Editor web part (used to add the widget snippet to a page) using the EDGE browser.  The EDGE browser causes the Content Editor web part to incorrectly save the snippet code.  The EDGE browser should not be used for page editing.