Guide for upgrading to Portfolio Planning (v6.0.1) or Strategic Planning (v2.0.1) - Support and Troubleshooting

Guide for upgrading to Portfolio Planning (v6.0.1) or Strategic Planning (v2.0.1) Alignment Planner Workspace Name Change

From the Utah release onwards, Alignment Planner Workspace is available as two applications – "Strategic Planning (v2.0.1)" in SPM Pro license and "Portfolio Planning (v6.0.1)" in SPM standard license. Each of these new applications is compatible with the Tokyo release and have specific capabilities that are mentioned in the following image.

Who will need to migrate the Organization data?

Customers who meet the following criteria :

Upgrading to the new Tokyo AWP 5.0.1 – November 2022 release. Implemented APW (Alignment Planner Workspace) on San Diego (or previous releases) and have the following APW plugins installed. Alignment Planner Workspace v4.1.1 or earlier version Alignment Planner Workspace with PPM (Project Portfolio Management), Agile 2.0 and SAFe (Scaled Agile Framework) v3.01 or earlier versions. Manually entered data, maintained that data, and did not synched data between the alignment tables and ServiceNow Organizational tables.

Example :

Alignment Table

ServiceNow Table

Manually entered data & data not synchronized

Data Migration Needed

Business Unit (sn_align_core_business_unit)

Business Unit (business_unit)

Yes

Department (sn_align_core_department)

Department (cmn_department)

Yes

Upgrade Preparation Steps:

Instance where APW APW 4.x.x installed and implemented Navigate to All > Alignment Planner > Planning Hierarchies Review all Planning Hierarchies in APW APW 4.x.x Determine which Planning Hierarchies are being used Determine if these Planning Hierarchies have data that needs to be Migrated (see criteria above) Document the Planning Hierarchy Structures that are being used. Both predefined and custom Planning Hierarchy structures need to be manually set up in APW 5.x.x using Lens structures .

Review the Planning Hierarchies Integration Table Maps for each Execution Table to Alignment Table Document if there have been any Custom fields added for each Execution Table to the Alignment Table Added or Modified Filters for each Execution Table to Alignment Table Document any custom roles or specific groups created for APW 4.x.x

Why do I need to migrate the data?

The concept of Planning Hierarchies and Planning Organizations used in APW 4.x.x are no longer used in Lens Entities from APW 5.x.x onwards.

The APW 5.x.x Len structures represent a way for different planning managers to visualize, prioritize, fund, and plan work. Users will be able to use any ServiceNow data tables (example: business_unit, cmn_department, pm_portfolio, pm_program or any platform table) as planning entities in a Lens structure.

Who can perform the data migration?

Role : System Administrator (admin)

The SAMPLE migration script (below) will need to be updated for your company's planning organizations and then executed in the script - background module

When to perform this process?

Once the Upgrade Preparation Steps above are complete, the recommended steps below are complemented.

Ensure that the latest applications and all its dependent applications are upgraded successfully. Install Portfolio Planning ( sn_align_ws ) for SPM Standard license or Strategic Planning ( sn_apw_advanced ) for SPM Pro license. Refer the OOTB (Out of The Box) lenses and product documentation to understand the Lens structure. Configuring Lens and Lens Structure – SPM (Strategic Portfolio Management) Professional Ensure that required modiﬁcation has been done in the Lens structures (if required) and Lens structures are ﬁnalized. Ensure that all Lenses are validated and are marked as active.

Do the dependencies and Milestones need to be migrated as well?

All the existing dependencies among planning items are retained "as is" when upgrading Dependencies do not require any migration. Planning item-level milestones are intact Roadmap level milestones from Ad Hoc Roadmap are migrated to Free-form Roadmap. Only Planning Organization level milestones from the legacy planning hierarchy are skipped on upgrade.

How to perform data migration?

SAMPLE Data migration script completes two actions:

Action 1: Migrating Planning Organization data to Lens Entity records.

Based on the Lens Structure you selected, created, or modified

Verify if you have the required data already in place on the Lens entities tables Verify relationship among those lens entities are well maintained between the lens entity records. Action 2: Mapping Planning Items to Lens Entity Once the planning organizations and their relationships are migrated to the Lens entities records, the mapping of the planning items to the Lens Entity can be done Manually or via the sample script

Manually populating the lens entity references on the planning item record Open the Planning Item Table [sn_align_core_planning_item] Populate Business Unit, Department, or the specific Lens Entity you build out above OR

Populate the Lens Entity using the SAMPLE script Update the SAMPLE script section var planning_item_table_column = 'department'; //Reference field on planning item table, which refers the new Target ServiceNow Lens Entity table, //When running migration script for Company –field is blank //When running migration script for Business Unit –field is 'business_unit' //When running migration script for Department –field is 'department'

Note : In the SAMPLE script below, only planning item types Project, Demand and Epic will be updated. Other planning items: Initiative and Big Rock are not included in AWP 5, referred to as lens entities. Refer to the script include: PlanningItemAPIImpl -> getAvailablePlanningItemTypes() for more. For Goals module users only

Migrating the Planning Organization to the targeted tables for Strategic Priority and Goal tables that were defined in the Alignment Planner Workspace or Enterprise Goal Management module See Goals migration KB (Knowledge Base) For the script and detailed instructions Script Recommendation

Migration of records should be verified thoroughly in Pre-production environment before executing in Product instance. Do Not use this SAMPLE script as is Copy the SAMPLE Script Modify the copied script based on each of your planning hierarchies and new Lens structures. Run in the Script using the background module Data migration should be done one planning hierarchy at a time. Recommend you start the data migration with the top-level entities before the child entities so that their relationships are also retained. Example: If the lens entity structure is: Company Data migration should be done in following order: Company, Business Unit and then Department.

SAMPLE Migration Script - Run in the Script - background module

This SAMPLE script shows an example for the Alignment Table DEPARTMENT Modify for Alignment Table COMPANY (if appliable) Modify for Alignment Table BUSINESS UNIT (if appliable) etc. var apw_core_po_table = 'sn_align_core_department'; //Source Alignment table to migrate data from

var migrate_to_table = 'cmn_department'; //Destination/Target ServiceNow table to migrate data to

var planning_item_table_column = 'department'; //Reference field on planning item table, which refers the new Target ServiceNow Lens Entity table,

//When running migration script for Company –field is blank

//When running migration script for Business Unit-field is 'business_unit'

//When running migration script for Department –field is 'department'

var mappingFields = { //Provide the field level mappings between source and target table, Ensure the field types match for the field mappings.

//Key : apw_core planning organization (or its extension) field name

//Value : Migrate to table field name

'name': 'name',

'description': 'description'

};

var parent_filed_in_migrate_to_table = 'business_unit'; //Reference field from target ServiceNow table to its parent. (As per the new lens defined),

//When running migration script for COMPANY entity, field is blank/null because planning org is root entity.

//When running migration script for BUSINESS UNIT entity, field is 'company'

//When running migration script for DEPARTMENT entity, field is 'business_unit'

var alignmentPlanningOrgGr = new GlideRecord(apw_core_po_table);

alignmentPlanningOrgGr.query();

while (alignmentPlanningOrgGr.next()) {//Iterate over all records in apw_core_po_table table

var execution_entity_sysId = alignmentPlanningOrgGr.getValue('execution_entity_item');

if (gs.nil(execution_entity_sysId)) { //Check if this is ever integrated/synched to execution layer (or any other platform table)

//If record is not found to be synched with other table, synch with Execution table

execution_entity_sysId = _createPORecordsOnExecutionSide(alignmentPlanningOrgGr, migrate_to_table, mappingFields);

if (gs.nil(execution_entity_sysId)) {

continue;

} else {

//If synch to execution table is successful, update the reference on source record (i.e.: alignmentPlanningOrgGr)

alignmentPlanningOrgGr.setValue('execution_entity_item', execution_entity_sysId);

alignmentPlanningOrgGr.update();

}

//If the source planning org record has a parent populated, synch the corresponding parent's clone with the execution record (clone of planning org)

if (!gs.nil(parent_filed_in_migrate_to_table) && !gs.nil(alignmentPlanningOrgGr.parent)) {

var parentOrg = alignmentPlanningOrgGr.parent.getRefRecord();

if (!gs.nil(parentOrg) && parentOrg.isValidRecord()) {

var executionPOEquivalentRecrord = new GlideRecord(migrate_to_table);

executionPOEquivalentRecrord.get(execution_entity_sysId); //Fetch the target execution record

executionPOEquivalentRecrord.setValue(parent_filed_in_migrate_to_table, parentOrg.getValue('execution_entity_item'));//Set the mapped parent on the execution record.

executionPOEquivalentRecrord.update();

}

//ENTITY POPULATION:

//If the reference field from planning item table to new target table is provided, link the planning item to the execution record (clone of planning org)

if (!gs.nil(planning_item_table_column)) {

_updatePlanningItemRecordsForPO(alignmentPlanningOrgGr, planning_item_table_column, execution_entity_sysId);

}

//Fetches all the allowed Planning item records (usually Project/ Demand and Epic OOB (Out of Box)) from the source Planning org and associates them to the execution record (clone of planning org)

function _updatePlanningItemRecordsForPO(alignmentPlanningOrgGr, planning_item_table_column, execution_entity_sysId) {

var PlanningItemAPIImpl = new sn_align_core.PlanningItemAPIImpl();

var planningItemsList = PlanningItemAPIImpl.getAvailablePlanningItemTypes();

var planningItemGr = new GlideRecord('sn_align_core_planning_item');

planningItemGr.addQuery('planning_organization', alignmentPlanningOrgGr.getUniqueValue());

planningItemGr.addQuery('sys_class_name', 'IN', planningItemsList);

planningItemGr.query();

planningItemGr.setValue(planning_item_table_column, execution_entity_sysId);

planningItemGr.updateMultiple();

}

//Create the record clone of alignmentPlanningOrgGr in the migrate_to_table using mappingFields between the 2 tables, modify accordingly as per the need.

function _createPORecordsOnExecutionSide(alignmentPlanningOrgGr, migrate_to_table, mappingFields) {

var newExecutionPOEquivalentRecrord = new GlideRecord(migrate_to_table);

newExecutionPOEquivalentRecrord.initialize(); //New record in target table to synch with Planning Org record

if (!JSUtil.isEmpty(mappingFields)) {

for (var key in mappingFields) {

var executionFieldValue = alignmentPlanningOrgGr.getValue(key);

var executionFieldName = mappingFields[key];

newExecutionPOEquivalentRecrord.setValue(executionFieldName, executionFieldValue);

}

var newRecordSysid = newExecutionPOEquivalentRecrord.insert();

return newRecordSysid;

}

return null;

}