Customizations and Extensions

This chapter describes how functionalities of MatchPoint Snow can be customized. Customization can be done either according to customer requirements or according to requirements related to a generic extension for MatchPoint Snow (i.e. implementation of a MatchPoint Snowflake).

On principle, MatchPoint Snow should be viewed as a product: with a defined feature set (including defined interfaces for customization) and a defined update path for future upgrades. Any customization beyond the 'defined' customization interfaces should be considered carefully:

In such a customization scenario, MatchPoint Snow is not used as a product; it is rather used as a framework for building a customized application. Since MatchPoint Snow is based on MatchPoint, it provides virtually unlimited functionalities for customization from a technical point of view. However, such customizations have significant impact on the update process for new versions of MatchPoint Snow.

MatchPoint Snow provides these interfaces for customization:

  • Implementation of a MatchPoint Snowflake
  • Adding landing pages
  • Adding workspace types
  • Adding contextual actions (for landing pages or workspace types)
  • Customization of the provisioning templates

The following sections of this chapter provide a brief overview regarding configuration of the mentioned customization mechanisms and a description of the update process for MatchPoint Snow.

Implementation of a MatchPoint Snowflake

A MatchPoint Snowflake is an extension for MatchPoint Snow that implements specific functionality for a business case, for example a HR recruiting process or a contract management tool.

A Snowflake is generally built using the same architectural concepts as MatchPoint Snow itself:

  • A Snowflake 'root' site collection provides access to the Snowflake-specific functionality (i.e. landing pages with aggregated views for accessing content).
  • Content itself is stored in workspaces. A snowflake can define multiple workspace types (i.e. "Contract") that may use a custom provisioning template and customized elements like lists, document libraries, web parts etc.

The web parts used within the landing pages and custom workspace types can be implemented using the functionality of MatchPoint. The Snowflake itself is configured using a configuration file that defines landing pages, workspace types and contextual actions.

For more information on how to implement a MatchPoint Snowflake, please refer to the Snowflake Developer Guide document.

Modifications of MatchPointSnowConfiguration.xml

The following sub-sections describe modifications to MatchPoint Snow that can be configured within the configuration file MatchPointSnowConfiguration.xml.

In general, the configuration file will be used to add elements (landing pages, workspace types, contextual actions). However, it is also possible to modify, remove or replace selected elements from MatchPoint Snow. Please note that such changes may have impact (in terms of additional update effort) when updating to a new version of MatchPoint Snow.

Adding Roles

The first step in adding new role should start with changes in the proper configuration of type "Provisioning Configuration" -> WebDefinition -> PermissionAssignments. Please add here exact role name as it will be used and select permission level for this role. After this step, new roles could be added in Snow configuration or Snowflakes.

Roles added in "MatchPointSnowConfiguration" can be referenced in the workspace type from within this configuration or in any workspace type defined in other snowflake configuration.

Name Description
Name Specifies name of the role. By this name, the role could be identified within configuration.
Permission Defines permission set for this role.
DefaultUsers

The users and groups selected here will automatically be added to the corresponding role during the workspace creation process.

Please note: This is just for the initial creation of the workspace, these users can be added/removed by the owner(s) of the workspace once it has been created.

IsSingle Defines whether the role is restricted to contain only one user.

Please note, that in order to have properly tagged workspaces, configuration of Role Tags need to be performed. To do it, please open "Workspace Template Configuration" configuration, and add the name of the created role with "Owner" permission to the -> RoleTagDefinitions -> IncludedRoles. We strongly suggest that only roles with Owner permission should be added there since only Role Tags created from Owner roles are used in the MatchPoint Snow.

Adding contextual actions

Within MatchPointSnowConfiguration.xml, additional contextual actions can be defined. This is possible in two ways:

  • The ContextualActions configuration element directly beneath MatchPointSnowConfiguration defines contextual actions that are available from landing pages.
  • The ContextualActions configuration element beneath a WorkspaceType configuration defines contextual actions that are available within that workspace type.

On both locations, different kinds of contextual actions are available:

Contextual Action Description
DialogAction Displays a site within a dialog window.
GenericWebPartPageAction Displays a MatchPoint web part within a dialog window.
JavaScriptActions Executes JS code.
RedirectAction Redirects to a defined site.
PostbackAction Raises a Postback event with the configured expression.
WorkspacePickerAction Specifies an action that will be executed for a specific workspace. That workspace will be selected manually by the user before the action is executed.

Each of these actions has one or more specific parameters that relate to the implemented 'action'. These specific parameter will not be described in detail as they should be self-explanatory when added to the MatchPointSnowConfiguration.xml. The following parameters are configurable for all actions:

Contextual Action Description
Label Specifies the label of the contextual action.
IconUrl Specifies the icon of the contextual action
VisibilityExpression Specifies an expression that evaluates whether to display the contextual action to a user
BeforeActionJavaScript Defines JS code that is executed before the action is executed.

Please note that it is not recommended to use contextual actions for functionality related to a 'selected' item (using the MatchPoint connection framework). Such functionality should be implemented either within the displaying control (i.e. within a context menu) or within a contextual action that uses a WorkspacePickerAction (i.e. a user first selects a workspace in a dialog, then an action is executed for that selected workspace).

Adding workspace types

Within MatchPointSnowConfiguration.xml, the configuration element WorkspaceTypes allows defining additional workspace types that may have functionality that differs from the 'default' workspace types (project, team, community).

Each WorkspaceType element provides the following parameters:

Parameter Description
Id Specifies a unique id for this workspace type. This parameter identifies the workspace type within MatchPoint Snow.
Name Specifies a display name for this workspace type. Identifies the workspace type for users.
ProvisioningConfigurationExpression Specifies the provisioning template for this workspace type. It is strongly suggested to use and extend MPSnow.Workspaces.BaseProvisioning.xml since this is the base template for all MatchPoint Snow workspaces.
CreatorConfigurationExpression Specifies the Workspace Editor web part used for creating new workspaces. If no specific metadata fields are configured, it is suggested to use MPSnow.Workspace.DefaultCreator.xml which already implements the base functionality for creating a new workspace.
EditorConfigurationExpression Specifies the Workspace Editor web part used for editing existing workspaces. If no specific metadata fields are configured, it is suggested to use MPSnow.Workspace.DefaultEditor.xml which already implements the base functionality for creating a new workspace.
Roles Specifies which roles will be available in the workspace. Contains role reference from snow or snowflake configuration and allows to create new roles with defined names, permissions, and default users.
Creators Specifies the users that are allowed to create new workspaces of this type.
MeetingCreatorRoleDefinitions Specifies roles which are allowed to create meetings.
CreatorRole Specifies to which role, the user which created current workspace will be added.
PublicReadersDefinitions Specifies which users will be added as public readers to which role during workspace creation. Only roles with reading permissions are available to select.
RequiredTags Specifies tags that are required on the workspace type
IsSelfSubscriptionEnabled If 'true', users with the 'Reader' role can promote themselves as 'Members'
HideInCreationDialog Specifies that the workspace type should be hidden from the user interface for creating workspaces.
  • Version 2.1.0 Please not that the new version is introducing the concept of roles. But before any role could be used in workspace, need to be defined first in "Provisioning Configuration" -> WebDefinition -> PermissionAssignments. </br>Only the role names existing in selected "Provisioning Configuration" can be used!

Adding landing pages

Landing pages (by default: timeline, workspaces, content, people, reporting) are displayed as navigation elements on the MatchPoint Snow root site and on each MatchPoint Snow workspace.

The default landing pages should generally not be modified in order to ensure a seamless update to new versions of MatchPoint Snow. However, it is possible to add additional landing pages that may provide additional or different functionality. Within MatchPointSnowConfiguration.xml, the configuration element TopNavigation specifies the landing pages (or top navigation elements) for MatchPoint Snow.

Each NavigationNode element provides the following parameters:

Parameter Description
Title Specifies the title of the landing page.
TargetUrl

Specifies the URL of the landing page.

Please note that the landing page itself needs to be provisioned and configured, i.e. by using the MatchPoint web parts.

IconUrl Specifies the icon of the landing page
ActiveIconUrl Specifies the icon of the landing page when selected.

All parameters are PatternString types that allow using the MatchPoint expression engine to dynamically determine values. For instance, the StringResources expression variable may be used to configure the Title property for multiple languages. For more information, please refer to the MatchPoint Technical Reference Document.

Modifying the Portal Welcome page

MatchPoint Snow gives the configuration capability of modifying the Welcome page.

By default this is set to “SitePages/Portal.aspx”. It can be configured to a different page from MatchPointSnowConfiguration.xml

Customizing the provisioning templates

Each workspace type within MatchPoint Snow uses its own MatchPoint provisioning template. For the default workspace types:

Workspace Type Provisioning Template
Project MPSnow.Workspaces.ProjectProvisioning.xml
Team MPSnow.Workspaces.TeamProvisioning.xml
Community MPSnow.Workspaces.CommunityProvisioning.xml

The provisioning templates are all based on MPSnow.Workspaces.BaseProvisioning.xml. This configuration file defines basic settings that are identical for all workspaces (e.g. alternate languages, enabled features etc.). It is therefore suggested to make modifications that shall be applied to all workspaces within the base template.

Please note that while some modifications (i.e. alternate languages) may have to be made to the provisioning template in order to adapt MatchPoint Snow to a specific customer scenario, it is generally suggested to keep these modifications to a minimum. If you need to make extensive changes, it is suggested to implement an own workspace type with a dedicated provisioning configuration in order to ensure a seamless update for the MatchPoint Snow base installation.

Add additional timeline posts

It may be desired that for certain actions, like creating and editing documents or adding new workspace members, timeline posts are automatically created (instead of only manual creations by users). By doing this other users can easily take notice when something interesting happened.

This can be accomplished by using custom Workflow Configurations and / or custom Workspace Event Handlers. New timeline posts can then be generated by using the MatchPoint Snow expression method MPSTimelineHelper.AddPost.

For details concerning this topics please see this blog post.

Unsupported Customization Scenarios

As mentioned before, MatchPoint Snow is based on MatchPoint and therefore provides virtually unlimited functionalities for customization from a technical point of view. However, since MatchPoint Snow is designed as a product (in terms of a defined feature set), there are some restrictions regarding what changes are supported.

Specifically, the following changes should not be made in order to ensure a clean update path for future versions of MatchPoint Snow:

  • Changes to configuration files except the configuration files specifically mentioned within the previous sections.
  • Changes to user controls
  • Changes to the metadata model except for importing customer-specific metadata into the 'business topic' tag groups.

If MatchPoint Snow is used as a framework (i.e. as a 'template library'), any changes within the full functional scope of MatchPoint are allowed. However, this means that update to a new version of MatchPoint Snow requires significant higher effort. All components of MatchPoint Snow that have been modified from the 'base' installation need to be re-tested to ensure full functionality of both the upgraded MatchPoint Snow version and the customized solution.

Updating MatchPoint Snow

As mentioned before, MatchPoint Snow provides an update path that allows updating a previous version of MatchPoint Snow to the newest version, provided that the changes implemented on the environment are within the scenarios described within this chapter.

The following steps are required in order to update an existing installation of MatchPoint Snow:

  • MatchPoint Solution Upgrade (i.e. update from MatchPoint version 4.0.2 to version 4.0.3) Can be executed using either PowerShell CmdLets or the MatchPoint installer executable.
  • MatchPoint Snow Solution Upgrade (i.e. from MatchPoint Snow version 2.0.0 to version 2.1.0) Can be executed using PowerShell Cmdlets.
  • Update of MatchPoint configuration files and SP content (i.e. workspaces, landing pages etc.) Can be executend using PowerShell CmdLets.
  • Update of 'modified' configuration files (i.e. MatchPointSnowConfiguration.xml, Provisioning configurations, string resources etc.) Needs to be executed manually.

For more information regarding updates for MatchPoint Snow and the update process, please refer to the MatchPoint Snow Installation Guide document.

results matching ""

    No results matching ""