Customisation

When to customise?

When considering customisation, think about the business benefit of a customisation versus the cost.

Solution Layering

Benefit	Cost
Adapt to Client’s business processes	Blocks future updates to that area
More direct business value	Additional maintenance cost
Enhanced end-user experiences	Additional complexity / update risk

Some customisations have higher costs than others

Example	Cost of ownership
Reporting Customisation	Low
Additional form fields	Low
New entities/data structure changes	Medium
Changes to OOTB JavaScript / DOM	High

How to customise?

One of the key reasons to choose Altus and the Power Platform is to facilitate customisation of the product to suit your requirements. With Altus you can customise it yourself or engage us to help you.

Do it yourself

GOLDEN RULES FOR CUSTOMISATION

Multiple environments are required for Application Lifecycle Management (ALM)
Production environments should not include unmanaged layers. Unmanaged layers in Production can lead to several problems:
- Unpredictable Behaviour: Unmanaged layers can override managed solutions, leading to unexpected behaviour and unexpected bugs.
- Difficult to Track: Changes made directly in Production are harder to track and audit.
- Maintenance Challenges: It complicates the process of updates and maintenance, as unmanaged customisations need to be manually reconciled with new versions of managed solutions
- Microsoft includes a setting to enforce this.
Each Development environment used for solution layer creation should only host one unmanaged layer.
- When exporting a layer into a managed layer, predictable behaviour can only be assured if there is one unmanaged layer that encapsulates all the changes and dependencies of those changes.

Solution Layers Customer

Power Apps is an open and accessible platform for citizen developers and experienced developers to perform customisations themselves. We advise that all customer customisations are performed in a Development (DEV) environment in a dedicated solution layer and then deployed to the Production (PROD) environment as a managed layer. This allows good separation and change control processes to take place.

Engage a Consulting Partner

Solution Layers Consulting

To provide the highest level of expertise and support, Altus partners can provide detailed customisation services for Altus and Client Care to ensure that your deployment remains supported and up to date.

It is recommended that Consulting led customisations to Altus are stored in a layer above the base product and in the case where there are multiple environments (DEV, TEST, PROD) that unmanaged layers are used DEV and TEST are deployed into subsequent environments as Managed. Customer maintained layers can also be present to provide a quicker way to make changes without having to engage a partner every time.

Warning

Each environment must only contain one unmanaged layer used for development.

Altus customisation

The Altus solution as a set of layers over the existing project and Power Platform components. The additional components that are provided as part of the solution have the Customizable flag enabled (where possible) to allow almost any provided Dynamics component to be tailored to meet the business requirements. Where the item is not directly customisable (Security Roles, PCF Components, and the Teams App) we have taken steps to ensure that these have configuration options available to control their behaviour.

The solution layering concept is a common technique used throughout the Power Platform, and reviewing this general introduction to Solutions from Microsoft is recommended before getting started, with a more advanced discussion of best practices for Solution Lifecycle Management available here.

In the case of Altus, the solution layering can be visualised as:

Image shows the solution layer dependency in Altus

The Solution Layers are (from the bottom up):

(PFTW Edition Only) Microsoft Project Roadmap. Roadmap functionality is part of the Project Plan 3 and Project Plan 5 licenses. The Roadmap solution provides base level functionality for many project related functions and was historically released first.
(PFTW Edition Only) Project for the Web. This layer provided by Microsoft contains the back-end Dynamics components required for the Project for the Web functionality.
Kaizen. This layer contains the Altus Tables and functions that are not specific to Project for the Web, and common to all Altus solutions.
Atsumeru. Specific functionality for the Altus execution tool independent solution.
(PFTW Edition Only) IQ PFTW. This layer includes Tables, relationships and functions that provide integration with Microsoft Project for the Web.
Customisations. This layer can be added by the customer, or by a Partner on the Customer's behalf. It is either the "Default Solution" or a solution that is managed in a customer owned DEVOPS process.

Altus applies solutions in layers to provide functionality to the end user and customer specific customisations can then be applied on top to cater for specific customer needs.

Limitations

Important

Some elements in the Dataverse do not seem to handle Solution Layering. Please see below a list of the elements we have encountered which we recommend not to modify from our Altus Solutions.

SenseiProject Javascript bundle

It is not supported to customize the 'SenseiProject.bundle.js' JavaScript bundle in Webresources within your solution. Creating a customization layer will prevent future updates to this file from being visible in your environment.

Security Roles

Because Security Roles do not seem handle solution layering (and any changes made to them would be overwritten on the next update), all of the security roles shipped with Altus are shipped as non-customisable. If you require custom security roles, you can add new security roles in your environment.

Control Configuration at the Table level

Dataverse provides a capability (via the Classic interface) to modify the default Control used for each Table. This configuration change does not handle Solution Layering and any change made to this setting will either be deleted automatically whenever the base Solution updates, or will cause the base Solution update to fail completely if the control configuration is housed in another managed Solution layer. Altus strictly recommend not modifying the Control settings at the Table level for any of the Tables that are shipped with Altus.
(Note: Modifying the control for a subgrid at the Form level does not have this limitation as the layering is handled correctly by the Form). More details here

Security Role Query

Partners have access to typescript/javascript code to query the current users security roles by ID together with a list of constants that represent all the available out-of-the-box security roles.

This query will check to see if users have a given security role, and can be used if Security Roles Display Names are changing.

Query:

// Altus Roles
export const ExecutiveRoleId = "dfcfe799-f413-eb11-a813-000d3ae11abd";
export const AdminRoleId = "4c0f0c74-8b09-ea11-a811-000d3a530fe5";
export const ProjectRoleId = "9959280b-3621-ea11-a810-000d3a530fe5";
export const ProgramManagerRoleId = "f9dfbebf-fb13-eb11-a813-000d3ae11abd";
export const ProgramManagerTeamRoleId = "35e21d64-fc13-eb11-a813-000d3ae11abd";
export const PortfolioRoleId = "0bec81ef-9b09-ea11-a811-000d3a530fe5";
export const PortfolioManagerRoleId = "6032594f-fa13-eb11-a813-000d3ae11abd";
export const PortfolioManagerTeamRoleId = "ec929215-fb13-eb11-a813-000d3ae11abd";
export const ProposalManagerRoleId = "6734a4a6-fc13-eb11-a813-000d3ae11abd";
export const IdeaUserRoleId = "b0a82810-f813-eb11-a813-000d3ae11abd";
export const ChallengUserRoleId = "73ce88a4-f713-eb11-a813-000d3ae11abd";
export const StrategyRoleId = "657aa149-9c09-ea11-a811-000d3a530fe5";
export const StrategyExecutiveRoleId = "a180425f-fd13-eb11-a813-000d3ae11abd";
export const PMOUserRoleId = "92010470-f913-eb11-a813-000d3ae11abd";
export const ResourceManagerRoleId = "e53a8843-0bcf-eb11-bacc-0022481520cd";

export function currentUserHasRole(roleID: string): Xrm.Async.PromiseLike<boolean> {
    let roles = Xrm.Utility.getGlobalContext().userSettings.roles.get();
    return Xrm.WebApi.retrieveMultipleRecords(
        "role",
        `?$select=name,roleid&$filter=_parentrootroleid_value eq '${roleID}'`)
        .then(
            (result) => {
                if (result.entities.length > 0) {
                    for (let item of result.entities) {
                        if (!(roles.find((x) => x.id == item.roleid) === undefined)) {
                            return true;
                        }
                    }

                    return false;
                } else {
                    throw new Error(`No Security Roles Found!`);
                }
            },
            (error) => {
                throw new Error(`Error - ${error.message}`);
            }
        )
        .catch((error) => {
            console.log(error);
            return false;
        });
}

usage

currentUserHasRole(StrategyExecutiveRoleId)
    .then(result => {
        console.log(result);
    });

const result = await currentUserHasRole(StrategyExecutiveRoleId)
console.log(result);

SharePoint group sites

It is a common requirement to want to add elements or customise the SharePoint Site that is created in conjunction to the Microsoft (M365) Group. The approach to facilitating this is Using Site Designs to Manage Project Life Cycles.

Using techniques such as Hubs Sites, Site Designs, Site Scripts and connected Power Automate Flows allow for an almost infinite level of site customisation capabilities.

Customising Altus

Any change to Altus needs to be done via a solution, and to do this requires a Publisher.

Before you make any changes to Altus you will need to decide how you are going to make this change and how this change will interact with any base updates made to Altus. If you are making a considerable change to a form within Altus in line with a Client's request, and they don't want it to be automatically updated by any Altus base changes, it is probably best to make a copy of the form and work from this. This will mean that no changes will automatically be made to the form with future Altus releases. Any changes will need to be manually updated.

Note: Some items within Altus, such as PCFs will always get updates.

Adding a Publisher

We suggest if you are going to make customisations to your environment that in your development environment you configure a custom publisher which is not prefixed with "sensei" to avoid collisions with the Altus solution.

In order to create your publisher navigate to make.powerapps.com then select your Environment from the top right corner.

Image showing where to select your environment

Now we want to create our new Publisher inside the environment.

Click Solutions from the left-hand side bar
Select the Publishers tab
Click + New publisher from the main Home bar
Type the Display Name for your publisher, i.e. "Dynamics Edge"
Type the Name for your publisher, this value shouldn't have any spaces. The Name will mirror the Display Name without spaces by default
Type a Prefix for your publisher, as shown by marker 7 the prefix appears at start of any entities or objects created using the publisher. In this example it's "dynedge"
This is a preview of what a new Object name would look like i.e. dynedge_Object
Click Save and the publisher will be created if there is no collision with an existing name in the system.

Image indicating how to create a new Publisher

Adding a Unmanaged Solution

We want to create a new unmanaged solution using our new Publisher

Click Solutions from the left-hand side bar
Select the Solutions tab
Click + New solution from the main Home bar
Type the Display Name for your solution
Type the Name for your customisation, this value shouldn't have any spaces. The Name will mirror the Display Name without spaces or illegal characters by default
Select the Publisher you want to use: "Dynamics Edge" in our example
Unmanaged refers to the type of solution being generated
Click Create to create the solution.

Creation of new solution using new Publisher created earlier

Adding a column

In order to create your publisher navigate to make.powerapps.com then select your Environment from the top right corner.

Image showing where to select your environment

Now we need to edit our unmanaged solution. Adding in our case the existing entity and associated form.

Click Solutions from the left-hand side bar
Find your unmanaged customization layer i.e. "Customization" and select the ellipsis.
Click Edit.

Selecting Solution called Customization

To expand on an existing entity:

Select in the Top ribbon select Add Existing
Select Table (also known as Entity)

Creation of new solution using new Publisher created earlier

In our example we are going to add "sensei_risk" table to our solution.

Search for "sensei_risk" in the top right search box
Confirm that the Name also known as internal name matches
Select the checkbox
Click Next to proceed to add to unmanaged solution

Adding of existing table 'sensei_risk' to Customization solution

To add existing objects to our customisation solution:

Select Select objects

Selecting objects to add from existing Table

Adding the Main Information form to a customised solution

Select Forms
Notice the Information form definition under display name
In the Form type column it should say that it is a "Main" form
In the Managed externally? it should say "Managed", this implies this will create a solution layer which can prevent further updates to this entity. So it's recommended to keep back-ups of customisations in case you even need to restore them
Select the Columns checkbox
Click Add to add it to the solution.

Adding an existing Form to included within an unmanaged solution

This shows our form has been added to the customisation layer
Add the selected form to the solution layer.

Adding selected form to unmanaged solution

Now we can observe that our customisation has 1 entity "Risk" added to it.

To add a Column to it

Click the ellipsis
Click Edit

Editing an existing table/entity to add a column

Adding a Simple Column

Click the New Column button in the ribbon

Clicking 'new column' button

This will open the side pane which will allow for entering of the following details

New Column side pane

Display Name

This is the value that will be displayed as the Column name when added to a form

Description

Optional: the description of the column being created

Data type

The column(field) data type needs to be one of the following Microsoft Documentation

Selecting Data Type

Format

Then format for this particular data type

Selecting Format of data type

Behavior

The options here are Simple or Calculated (Rollup is an option for other data types). Calculated/Rollup will require saving the new element in order to modify the calculated column(field)

Selection of Simple or Calculated Behavior

Required

Defining if the value is optional/required/recommended

Required Options for column(field)

In the following we look at "Advanced options" (2) dropdown

Type a Display name in our example we have used "Custom Risk"
Expand Advanced options
Take note that the Schema name starts with "dynedge_" which is from the publisher for the solution and CustomRisk is the Display name removing invalid characters. Making the final "Schema name" equal "dynedge_CustomRisk". This can be changed at this point, but note that the "Schema name" cannot be changed once it has been created.
Enter the Maximum characters count for the column
Save the current configuration for your new column.

Advanced panel of New Column