Customisation Reference

Sensei provides the IQ 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 Sensei IQ, the solution layering can be visualised as:

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.
  • Sensei IQ. This layer contains the Sensei IQ Tables and functions that are not specific to Project for the Web, and common to all Sensei IQ solutions.
  • IQ Atsumeru. Specific functionality for the Sensei IQ execution tool independent solution.
  • (PFTW Edition Only) Sensei 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 Sensei on the Customer's behalf. It is either the "Default Solution" or a solution that is managed in a customer owned DEVOPS process.

Sensei 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 IQ Solutions.

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 Sensei IQ are shipped as uncustomisable. 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. Sensei strictly recommend not modifying the Control settings at the Table level for any of the Tables that are shipped with Sensei IQ.
(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

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.

SSRS Reports for Dynamics

Dynamics and Model Driven Power Apps have the facility to render SQL Server Reporting Services (SSRS) reports. To create and customise them requires a very specific tool-chain.

To get started with using SQL Server Reporting Services (SSRS) report with model-driven PowerApps, you need to run some specific software. You will need to use FetchXML to write queries against Dataverse tables. You will need to install the following software in this order.

  1. Install Visual Studio Enterprise 2019
    • Include the 'Data storage and processing' workload under 'Other Toolsets'
  2. Install Visual Studio Extensions
    • Web Live Preview (Preview)
    • Microsoft Reporting Services Projects
    • Microsoft Analysis Services Projects
  3. Install the v9.0 Dynamics 365 Report Authoring Extension

You can then use Visual Studio 2019 to author reports.

To add a datasource, you use an embedded connection and choose “Microsoft Dynamics 365 Fetch” as your type. For the Connection String, type in your Dynamics 365 root URL.

Add a dataset and use FetchXML as your query text. Note, you can use FetchXML Builder from the XRM Toolkit to help you build FetchXML queries.

Save the .rdl file and then to Power Apps and navigate to your solution. You can then upload your report and choose the related table (such as Projects for a Project Status Report). To overwrite an existing report, go into Edit mode for the report and then select Choose File and upload your .rdl to overwrite.

Adding a Column

TODO:

  • Add Column to Table
  • Add Column to Form

Adding a Project Type (EPT)

TODO: Adding an EPT and setting tab visibility

Adding a Workflow

Custom Workflows can be added to Sensei.IQ, but there are some important steps required to make them function as expected within IQ.

Create a new Business Process Flow (BPF)

  • Navigate from the cog menu in PowerApps to Advanced Settings
  • From the Dynamics 365 Settings menu, select Solutions
  • Select the Sensei_IQ_Enhancements unmanaged Solution that contains the Enhancements for IQ in your environment.
  • Select the New button and then select Process
  • Enter a name for your Process, then ensure the following options are selected:
Column Value
Process name: {Name of your BPF}
Category: Business Process Flow
Table: Project
Business Process Type: Run process as a business flow (Classic)
Name: {Should be automatically entered for you when you enter the Process name. Adjust if required.}

Once you have entered the details, press OK.

  • Now that your BPF has been created, populate it as per your requirements. Once you are happy, Save and Activate your BPF.
  • Back within the IQ Enhancements Solution in the Dynamics 365 Advanced Settings area, select to either edit an existing enhancement Security Role, or select to add a new one.
  • If adding a new Role, provide a relevant Name and then select the Business Process Flows tab.
  • Locate and select the Name of your Business Process Flow. The UI should update to provide security permissions to the role across the permission set.
  • Select Save and Close.
  • Next, Navigate to the Sensei.IQ for Project app. (Note: You will need the Sensei.IQ for Admin User role to perform these actions)
  • Select the Settings area of the app
  • Select Project Types from the left menu
  • Select to create a New Project Type (or select to edit an existing one, if you need to change its associated BPF Workflow)
  • Enter the details for your new Project Type and the required tabs that you wish to display on the Project Form. Then select the Workflow tab on the Project Type form.
  • In the Workflow Column, search for and locate the BPF that you created earlier.
  • Select Save & Close.
  • Next, we need to make sure that the new BPF is available within the IQ app. Back within the IQ Enhancements Solutions in the Dynamics 365 Advanced Settings area, check whether the Sensei.IQ for Project model driven app is already part of your Enhancements Solution.
  • If it is not yet added, use the Add Existing > Model Driven App option. and then select the Sensei.IQ for Project app and press OK
  • Double-click the Sensei.IQ for Project model driven app to open it in Edit mode.
  • In the App Designer, select the Business Process Flows object.
  • In the list of BPFs that now appear in the right pane, select your new BPF
  • Press Save and then Publish.
  • Using the Dynamics Plugin Registration Tool, select to log in to your Environment
    • If you have an issue installing the tool please check "nuget sources" and if missing you will need to run "nuget sources add -Name nuget.org -Source https://api.nuget.org/v3/index.json"
  • Once connected to your environment, scroll down to locate the SenseiPlugin assembly
  • Right-click (Plugin) SenseiPlugin.Sensei_SetProjectCurrentStage and select Register New Step
  • Configure the Step with the following settings, then press Register New Step.
Message Create
Primary Table { Select your BPF Table }
Secondary Table {none}
Filtering Attributes {none}
Event Handler (Plugin) SenseiPlugin.Sensei_SetProjectCurrentStage
Step Name Sensei.IQ for Project - Set Project Current Stage : Create of { Your BPF Table Name }
Run in User's Context Calling User
Execution Order 1
Description SenseiPlugin.Sensei_SetProjectCurrentStage: Create of { Your BPF Table Name }
Event Pipeline Stage of Execution PostOperation
Execution Mode Asynchronous
Deployment Server
Delete AsyncOperation if StatusCode = Successful Unchecked

  • Again Right-click '(Plugin) SenseiPlugin.Sensei_SetProjectCurrentStage' and select 'Register New Step' - this time we will add a handler for the Update operation
  • Configure the Step with the following settings, then press 'Register New Step'
Message Update
Primary Table { Select your BPF Table}
Secondary Table {none}
Filtering Attributes activestageid, completedon, modifiedon
Event Handler (Plugin) SenseiPlugin.Sensei_SetProjectCurrentStage
Step Name Sensei.IQ for Project - Set Project Current Stage : Update of { Your BPF Table Name }
Run in User's Context Calling User
Execution Order 1
Description SenseiPlugin.Sensei_SetProjectCurrentStage: Update of { Your BPF Table Name }
Event Pipeline Stage of Execution PostOperation
Execution Mode Asynchronous
Deployment Server
Delete AsyncOperation if StatusCode = Successful Unchecked

  • After configuring these Plugin registration steps, whenever your BPF Table is used (e.g. when a Project moves from one stage to another) your Project will be updated with the Current Stage value.
  • Your BPF should now work and display correctly within Sensei.IQ.

Unhiding a Command Bar Button

Various Command Bar buttons have been hidden from various Tables relating to the Sensei.IQ Solution. If there is a customer requirement to unhide any of these buttons, then the following procedure can be used:

  • Create an Unmanaged Solution (if one does not already exist) in the customer environment and ensure you add to it the existing Tables that you wish to modify the ribbon for.
  • Open Ribbon Workbench 2016 (either as web add-on in Dynamics or from the XrmToolbox desktop application).
  • Select Open Solution
  • Select to open your unmanaged Solution containing the Tables you wish to modify the ribbon for.
  • Note: If Ribbon Workbench fails to load your Solution (because your Solution is large), try multiple times. Sometimes this error is transient.
  • Once your Solution has loaded, ensure the Command Bar tab is selected
  • Next, select the Table that you wish to modify the ribbon for
  • Any buttons which have previously been hidden will be shown under the HIDE ACTIONS heading
  • To unhide a button, right-click the hide action that you wish to remove and select Un-Hide
  • Click OK on the notification. Take note that you will only see the unhidden button after a publish operation (and only in Ribbon Workbench after subsequently reloading the Solution).
  • Make the required changes to whichever Tables you wish to modify the command bar for.
  • Once you have completed your changes, select Publish

  • Click OK to confirm Publish operation.

Dealing with Custom Tables

As with all customisations to IQ, Sensei recommend creating an unmanaged Solution which will then contain your additions and modifications to IQ artefacts. Custom Tables are no different and should be created in your IQ Enhancements solution.

This section provides guidance on how to configure IQ to ensure that your custom Table is treated the same way as out of the box IQ Tables in terms of security and in particular inheriting ownership from the Project, Program or Portfolio that your custom Table is associated with.

The following configuration steps assume that you will have already:

  • Created your Custom Table in your enhancements solution
  • Added your Custom Table to the Project, Program and/or Portfolio form(s) as a tab with a subgrid
  • Created a custom Security Role which provides access to your custom Table
  • Added your custom Security Role to the users who require it
  • If associated to more than one parent type, we highly recommend creating a Business Rule to ensure that your custom Table records can only relate to one Project, Program or Portfolio at a time. (If you were to relate your custom record to a Project and to a Portfolio, the ownership of your Table record could have unexpected results).
Note

When creating Tables that relate to a Project ensure that the relationship between the custom Table and the Project Table is not set to 'Parental'. Instead, configure the relationship as follows:

If your custom Table contains Lookup Columns to Project and/or Program and/or Portfolio, you will need to configure the Sensei Config Setting associated with each of those 'parent' Tables to ensure IQ is aware of your custom Table.

  • As an IQ Admin user, open the Sensei IQ for Project app and navigate to the Settings area.
  • From the left menu select Configuration Settings.
  • Select the {Parent} - Custom Registers setting for the Parent of your custom Table. (Note: You will need to repeat these steps for each parent. e.g. if your custom Table relates to Projects and Programs, you will need to perform these steps for 'Sensei Project - Custom Registers' and 'Program - Custom Registers').
Note

If you do not see the corresponding settings item, switch to the Inactive Sensei Config Settings view, locate the setting and switch it to Active.

  • Select the New Items button to add your new custom Table configuration.
  • Enter details relating to your custom Table to define:
    1. Table Name: The internal name of your custom Table.
    2. Required Team Root Role Id: The Id of your custom security role (this role will be applied to any owner teams).
      • To find the roleid GUID, from within the Sensei IQ app, click the Gear, Advanced Settings, Security, Security Roles and then click the custom Security Role.
    3. Parent Column Name Link: The internal Column name in your custom Table that relates the custom Table to its parent (in the case of a setting for Project - Custom Registers, this would identify the Project Column).
    4. Assigned To Column: If your custom Table has an Assigned To type Column, identify it by its internal name here.
  • Save your Config Settings item
  • Repeat these steps for each parent (Project, Program or Portfolio) that relates to your custom Table.

You will also need to perform these next steps to ensure that the Sensei IQ Plugin code is triggered to correctly run when you create or update a custom Table record. These Plugin steps ensure that your custom Table records will be visible to members of a Project, Program or Portfolio team (as applicable). To perform these steps, you will need to use the Plugin Registration Tool available here.

  • Launch the Plugin Registration Tool (PluginRegistration.exe) and select Create New Connection.
  • Ensure you select Office 365, then press Login.
  • Enter your credentials to log in to Microsoft 365.
  • In the list of Plugin Assemblies, locate (Assembly) SenseiPlugin and click the arrow to expand.
    • Depending on your implementation, SenseiAtsumeruPlugin is comparable to SenseiPlugin.
  • Locate (Plugin) SenseiPlugin.Sensei_InheritOwnershipFromProject and right-click and select Register New Step.
  • Enter the following details, then press Register New Step. This will ensure that whenever a new record is created in your custom Table that the InheritOwnershipFromProject plugin code is run - which will ensure that your custom Table record is attributed the same ownership as the Project, Program or Portfolio that it is associated with.
    1. Message: Create
    2. Primary Table: {Enter your custom Table by its internal name}
    3. Secondary Table: {Leave blank}
    4. Filtering Attributes: {Leave blank - unavailable for a Create action}
    5. Event Handler: {Leave this set to (Plugin) SenseiPlugin.Sensei_InheritOwnershipFromProject}
    6. Step Name: {Add a name for your Plugin Step, or leave as per the default.}
    7. Run in User's Context: Calling User
    8. Execution Order: 1
    9. Description: {Add a description for your Plugin Step, or leave as per the default.}
    10. Event Pipeline Stage Of Execution: PreValidation
    11. Execution Mode: Synchronous
    12. Deployment: Server
  • Perform the following steps only if your custom Table has an Assigned To Column which you have defined in the configuration settings. These steps ensure that if the person you have assigned to your Table record is not part of the Project/Program/Portfolio team, then the individual custom Table record will be shared with that person as an individual.
  • From the Plugin Registration Tool, right-click (Plugin) SenseiPlugin.Sensei_EnsureAccessForAssignedTo and select Register New Step.
  • Enter the following details, then press Register New Step.
    1. Message: Create
    2. Primary Table: {Enter your custom Table by its internal name}
    3. Secondary Table: {Leave blank}
    4. Filtering Attributes: {Leave blank - unavailable for a Create action}
    5. Event Handler: {Leave this set to (Plugin) SenseiPlugin.Sensei_EnsureAccessForAssignedTo}
    6. Step Name: {Add a name for your Plugin Step, or leave as per the default.}
    7. Run in User's Context: Calling User
    8. Execution Order: 1
    9. Description: {Add a description for your Plugin Step, or leave as per the default.}
    10. Event Pipeline Stage Of Execution: PostOperation
    11. Execution Mode: Asynchronous
    12. Deployment: Server
  • Again right-click (Plugin) SenseiPlugin.Sensei_EnsureAccessForAssignedTo and select Register New Step.
  • Enter the following details, then press Register New Step.
    1. Message: Update
    2. Primary Table: {Enter your custom Table by its internal name}
    3. Secondary Table: {Leave blank}
    4. Filtering Attributes: {Select your Assigned To Column}
    5. Event Handler: {Leave this set to (Plugin) SenseiPlugin.Sensei_EnsureAccessForAssignedTo}
    6. Step Name: {Add a name for your Plugin Step, or leave as per the default.}
    7. Run in User's Context: Calling User
    8. Execution Order: 1
    9. Description: {Add a description for your Plugin Step, or leave as per the default.}
    10. Event Pipeline Stage Of Execution: PostOperation
    11. Execution Mode: Asynchronous
    12. Deployment: Server
    13. Delete AsyncOperation if StatusCode = Successful: {Uncheck}
  • Following best practices, you should add this custom plugin step to your custom Solution.
    • Access your Sensei IQ Enhancements solution and select Add Existing > More > Developer > Plug-in step, then locate the newly registered step(s).
    • Once added, publish all customizations.

Deep Deep Linking

In 2021.02.17.2 we introduced the Deep Deep Linking feature to assist with embedding scenarios including Microsoft Teams Tabs.

To embed a reference to a particular Sensei Project and Tab use the following URL format

https://<orgURL>/main.aspx?appid=<appID>&pagetype=entityrecord&etn=<entityName>&id=<entityID>&navbar=entity&extraqs=sensei_showTab%3D<tabName>%26sensei_hideHeader%3D1

The query string parts are:

  • etn: The short form entity name e.g. sensei_project
  • id: ID of the entity you wish to embed (guid)
  • navbar: set to entity to remove the left-side nav bar
  • extraqs: this is the parameter that holds the additional IQ specific deep deep linking controls
    • sensei_showTab: is the name of the tab on the entity you wish to have be displayed. This is the internal name of the tab e.g. tab_tasks sensei_hideHeader: when included and set to 1 this also remove more surrounding chrome from the item.

Example:

https://iq.crm.dynamics.com/main.aspx?appid=e1e44b74-6430-eb11-bf68-000d3a799817&pagetype=entityrecord&etn=sensei_program&id=e436ab00-134d-4eed-bcc9-d3ef9a6dde28&navbar=entity&extraqs=sensei_showTab%3Dtab_risks%26sensei_hideHeader%3D1

Using Notes/Annotations with Project, Programs and/or Portfolios

The information in this section relates to version 2022.06.07.2 and above of Sensei IQ.

Dataverse provides the ability to turn on an attachments/notes capability on each Table/Entity. This can be turned on from the Table properties.

Note

Once this has been turned on, it cannot be switched off again for that Table.

After turning on the Attachments/Notes functionality, you would then need to expose this to the UI by adding a Timeline control to your related Table/Entity form. This will provide the mechanism for users to start adding Notes to the Project/Program/Portfolio.

Sensei IQ Security Roles are configured with the necessary permissions for users and owner teams to access Notes. Notes are treated as a special case in IQ and you do not need to configure them in the Custom Registers configuration settings.

However, if you intend to use Attachments/Notes for Projects, Programs and Portfolios, then you will need to configure a Plugin Step that runs on creation of new Notes to ensure that visibility of those Notes flows through correctly into IQ.

To perform these steps, you will need to use the Plugin Registration Tool available here.

  • Launch the Plugin Registration Tool (PluginRegistration.exe) and select Create New Connection.
  • Ensure you select Office 365, then press Login.
  • Enter your credentials to log in to Microsoft 365.
  • In the list of Plugin Assemblies, locate (Assembly) SenseiPlugin and click the arrow to expand.
    • Depending on your implementation, SenseiAtsumeruPlugin is comparable to SenseiPlugin.
  • Locate (Plugin) SenseiPlugin.Sensei_InheritOwnershipFromProject and right-click and select Register New Step.
  • Enter the following details, then press Register New Step. This will ensure that whenever a new record is created in your custom Table that the InheritOwnershipFromProject plugin code is run - which will ensure that your custom Table record is attributed the same ownership as the Project, Program or Portfolio that it is associated with.
    1. Message: Create
    2. Primary Table: annotation (this is the Dataverse internal name for the Notes Table/Entity)
    3. Secondary Table: {Leave blank}
    4. Filtering Attributes: {Leave blank - unavailable for a Create action}
    5. Event Handler: {Leave this set to (Plugin) SenseiPlugin.Sensei_InheritOwnershipFromProject}
    6. Step Name: {Add a name for your Plugin Step, or leave as per the default.}
    7. Run in User's Context: Calling User
    8. Execution Order: 1
    9. Description: {Add a description for your Plugin Step, or leave as per the default.}
    10. Event Pipeline Stage Of Execution: PreValidation
    11. Execution Mode: Synchronous
    12. Deployment: Server

Form Tab Loading

In "Kaizen - 2022.03.08.4" we have released some form loading improvements to reduce load time and the amount of flashing of tabs and forms. As part of this any conditional tabs have been made hidden to prevent the user from seeing the tabs and then them disappearing, instead we start them hidden and then show the ones that need to be shown.

To make your own custom tabs load smoothly like ours and not impact the user until they are actually required, please hide the tab in the form designer. Note you can make the designer show all hidden controls to allow you to work in the designer with them.

For Projects/Programs/Portfolios you should ensure the tabs are configured appropriately in the form tab visibility settings via the Project Types for Projects or the relevant setting for Programs and Portfolios.