servicemax migration tool · servicemax migration tool supports servicemax releases winter ’15...

ServiceMax Migration Tool ServiceMax Summer ’15 SP (October, 2015)

ServiceMax, Inc. 3875 Hopyard Rd, Suite 300, Pleasanton, CA 94588

Note: Any unreleased features referenced in this document, other press releases,

or public statements are not currently available and may not be delivered on time

or at all. Customers who purchase our services should make their purchase

decisions based upon features that are currently available.

Copyright 2015 ServiceMax, Inc. All Rights Reserved.

Designated trademarks and brands are the property of their respective owners.

Summer ’15 SP ServiceMax Migration Tool

of 23

Table of Contents Overview .................................................................................................................................. 3

Business Context ..................................................................................................................... 4

Compatibility ............................................................................................................................ 6

Detailed Feature Description .................................................................................................... 6

Data Model, Access, And Permissions ................................................................................... 10

Configuration ......................................................................................................................... 10

How to migrate Configuration Items using the Tool ................................................................ 11

Known Issues/Limitations ....................................................................................................... 19

Tips for Troubleshooting ........................................................................................................ 21

Appendix ................................................................................................................................ 23

ServiceMax Migration Tool Summer ’15 SP

of 23

Overview

The ServiceMax Migration Tool accelerates and automates the migration of custom

ServiceMax configuration items between environments. This supersedes the Flex-based

SFM Migrator, and can be invoked using the URL https://migrate.servicemax.com.

Following are the custom configuration items that are supported for migration using the

tool in the current release:

All custom SFM Transactions whose Status is Complete, along with all the custom

dependent configuration items such as maps and expressions

All custom SFM Wizards whose Status is Complete, along with the custom

dependent configuration items such as SFM Transactions and SFM Custom Actions

All custom SFM Searches

All custom Inventory processes

All translations defined for any dynamic strings using the ServiceMax Translation

Workbench

All ServiceMax Configuration profiles except Default and Default Group Profile

Mobile Configurations

SFM Mobile Permissions

The tool can either update or create the configuration items in the target org, depending on

whether the configuration items already exist in the target org or not. This is checked

based on the unique identifier such as SFM Transaction ID, SFM Wizard ID and profile

names.

The migration can be done from any source org (production or sandbox) to any target org

(production or sandbox). The tool supports ServiceMax releases Winter ’15 (14.6) and

above.

After user selects the configuration items to be migrated, the selected configuration items

will be migrated to the target org, with all the dependencies included automatically.

Examples of dependencies include SFM Data Validation Rule associated with a selected

SFM Transaction and SFM Transaction associated with an SFM Wizard step. Refer to the

Appendix for details about the supported dependent items.

If any of the dependent configuration items are standard configuration items (examples

include standard SFM Expression referenced in a custom SFM Transaction and standard

SFM Transaction associated with a custom SFM Wizard step), reference is made to the

existing standard configuration item in the target org, without migrating the same from the

source org.

https://migrate.servicemax.com/


of 23

Business Context

Any implementation of ServiceMax involves configuring several features. Following is the

list of key ServiceMax configuration items:

SFM Transactions, which include configuration of expressions, maps, source object

updates, page layouts, lookup configurations, data validation rules, formulas, linked

process, and multi-source process.

SFM Wizards, which include configuration of wizard steps and associated SFM

Transactions, Output Documents, SFM Custom Actions, Inventory Processes, and

SPRL Processes, and also the ServiceMax Group Profile association

SFM Searches with the ServiceMax Group Profile association

SFM Custom Actions

Inventory Processes

ServiceMax Configuration Profiles: Org-wide (Global) Profiles, Group Profiles with the

associated Salesforce Profiles, and ServiceMax Configuration Setting values

ServiceMax Offline Profiles, with the associated Salesforce Profiles and Offline

Datasets.

Mobile Configuration and SFM iPad Permissions for ServiceMax Group Profiles,

catering to mobile apps such as the iPad App and the Laptop App.

SPRL Processes

Dispatch Processes, and associated configurations such as MTTS Rules, Territory

Match Rules, Booking Windows, SLA Terms, Technician Eligibility Rules, and Skill

Match Rules.

Configurations related to Warranties, Service Contracts, and Preventive Maintenance

Plans such as Auto Entitlement Rules for Case and Work Order, Proforma Invoice

Processes for Service Contracts, Cases, and Work Orders, PM Plan Templates, and

PM Processes.

Configuration items related to Dispatch Console such as Event Hover Rules, Event

Subject Rules, Dispatch Console Field Updates, Dispatch Console Views, and

Dispatch Console Hovers

The number of these configuration items, especially the first three items listed above, is

high for enterprise customers. Generally, these are configured in a sandbox org; then they

are tested, in conjunction with customizations if any, for the completeness of the business

solution by users in the customer's organization; finally they are moved to the production

org.


of 23

In some cases, there might be more than one sandbox and the ServiceMax solution might

need to be implemented and tested in multiple sandbox orgs. In those cases, configuration

items need to be moved from one sandbox org to another.

Currently, this migration is a predominantly manual process which takes significant time

and involves verification of each migrated item in target org.

Considering the above factors, the ServiceMax Migration Tool has been built to accelerate

and automate the migration of ServiceMax configuration items from any source org to any

target org.

The tool automates several aspects, including the following:

ServiceMax version-compatibility check

Checking if the items selected for migration already exist in the target org

Updating the existing items if the user opts to overwrite

Creating new items for selected items that do not exist in the target org

Identifying which items cannot be migrated

Identifying and migrating dependencies

Not only does this result in faster migration, but also reduces chances of errors related to

dependencies and incomplete migration.


of 23

Compatibility

ServiceMax Migration Tool supports ServiceMax releases Winter ’15 (14.6) and above.

This covers all the major and minor releases made in the previous one year and is in line

with the End-Of-Life policy for ServiceMax releases.

The tool does not technically restrict migrating from any supported release to any other

supported release. It only displays a warning message if the source org version is higher

than the target org version. Note that this does not imply automatic compatibility between

different releases for migration of ServiceMax configuration. In general, migrating between

a major and its SP release should be compatible, unless explicitly stated otherwise in the

user guide of the tool.

The tool also displays a warning message if the source and target orgs have different

ServiceMax license types.

Detailed Feature Description

The following sections describe the UI aspects of ServiceMax Migration Tool:

Login and Logout

Accessible from https://migrate.servicemax.com

Enables the user to login to any source org using Salesforce OAuth Login screen

Enables the user to login to any target org using Salesforce OAuth Login screen

Enables logging out of source and target orgs individually or in one go, to enable

switching between different sets of orgs, till an actual migration session is started

Displays the Session Info, which includes details of the current source and target orgs,

user accounts used to login to each org, and ServiceMax version installed in each org

Shows tips with brief, step-by-step instructions for using the tool

Launches the detailed Feature Description document on clicking the ‘?’ icon ( )

Items for Migration

Shows in tree structure the types of configuration items supported, with the tree

collapsed by default

On expanding the trees, shows all the supported custom configuration items qualifying

for migration from source org, in the source org area of the screen; these include:

o All ServiceMax Configuration Profiles except Default and Default Group Profile

o All custom Inventory Processes

o Mobile Configurations for all configuration profiles



of 23

o All custom SFM Transactions whose Status is Complete

o All custom SFM Wizards whose Status is Complete

o All custom SFM Searches

o SFM Mobile permissions for all profiles

Displays the configuration items in alphabetical order

Enables selection or de-selection of individual configuration items or a group

Enables inline filtering based on the keyword(s) entered in the search text box

Lists all the selected items in the target org area of the screen

Validation Result screen

Lists each selected item, along with status message which indicates if the item will be

migrated or not, and the reason for not migrating where applicable

Provides the option to overwrite individual items which already exist in the target org,

along with Overwrite All option

Displays the list of custom dependent items such as expressions, maps, page layouts,

and data validation rules, highlighting the items that would be overwritten in target org.

Standard dependent items are not displayed

Has Cancel and Migrate buttons to either abort the migration or go ahead with it

The migration process consists of two stages: validation and migration. The tool does the

following during these stages:

Validation

Checks if any of the selected items and dependent items exist in the target org already

o Does this based on the unique ID of the type of item, such as SFM Transaction ID,

SFM Wizard ID, SFM Search ID, SFM Expression ID, Inventory Process ID and

Configuration profile names

o If the item or its dependent item(s) exist in the target org, prompts the user to

overwrite the item in the target org

Checks in target org for the existence of any Apex classes and custom objects & fields

referenced in the items selected for migration

o If any referenced entity does not exist in target org, shows that as the reason for

not migrating the item

o If any referenced field does not have the same field type in source and target orgs,

shows that as the reason for not migrating the item


of 23

If an SFM Page Layout (dependent item) exists in the target org, checks if the name,

count, & sequence of any existing child sections match between source and target org

o If there is any mismatch, shows that as the reason for not migrating the SFM

Transaction

o If there is no mismatch, prompts the user to overwrite the item in the target org

If an Output Document Template (dependent item) exists in the target org, checks if

the name, count, and sequence of any existing child sections match between source

and target org

o If there is any mismatch, shows that as the reason for not migrating the Output

Document

o If there is no mismatch, prompts the user to overwrite the item in the target org

Migration

Migrates the selected and validated items as reviewed by the user in the Validation

Results screen

Migrates in the order of dependencies, ensuring that an item is migrated only once,

irrespective of whether it has multiple references

o For example, if an SFM Transaction which is selected directly is also included as a

dependent item for an SFM Wizard, migrates it only once

o However, establishes the appropriate association in the target org, wherever there

is a reference

If any standard items are included by reference, establishes the appropriate

association to the standard items already existing in the target org

For SFM transactions, SFM Wizards, SFM Searches and Inventory processes,

available translations for all supported languages are migrated implicitly. Any existing

translations in the target org for migrated processes are overwritten

For ServiceMax Configuration profiles

o Profiles that do not exist in the target org are migrated with status as ‘Inactive’

o If profiles exist in the target org with the same name, they are overwritten. Their

status and associated Salesforce profiles are left unchanged.

o Custom modules, submodules and configuration settings are also migrated. If

the custom module, submodule or configuration setting have the same id in

both source and target orgs, then it is overwritten. Other custom entities are left

unchanged in the target configuration profile.

o When an org-wide ServiceMax Configuration profile is migrated, the following

settings (which refer to API field names) are also migrated automatically.


of 23

- Settings related to Field updates in Dispatch Console (under Dispatch

Management module and Dispatch Console Flex submodule)

- Settings related to Service Report in iPad app (under ServiceMax iPad Client

module and Service Report submodule)

When migrating SFM Mobile Permissions, the SFM View and Standalone create

processes assigned to the selected configuration profile are also migrated implicitly.

When migrating SFM Wizards and SFM Searches, configuration profiles assignments

for the selected items are also migrated implicitly, provided the configuration profile

already exists in the target org.

After migration, sends migration status email to the target org user, with migration

summary in the email and details in the attachments

Creates a ServiceMax Job record, capturing the details of migration

o Attaches the status log file to the record

o Attaches the file containing the details of all the migrated items, including

dependent items, to the record

If there is any error / exception during migration, aborts the migration (Note: the items

migrated to target org till the point of error / exception are not rolled back)

o Sends status email with log file and migrated items file, capturing all the details up

to and including the actual error message / exception

o Attaches the status log file and the migration items file to the ServiceMax Job

record


of 23

Data Model, Access, And Permissions

Data model aspects, access, and permissions specific to the migration tool are given

below. Apart from these, the access, permissions, and data model aspects applicable to

all the configuration items supported for migration such as SFM Transactions, SFM

Wizards, and SFM Searches, is applicable to this tool also.

The following table provides the details of key objects and fields that hold information

related to the migration tool:

Object Name Field Name /

Related Record

Remarks

ServiceMax Job Type Set to the value Configuration Migration Tool.

ServiceMax Job Start Time Migration Start Time

ServiceMax Job End Time Migration End Time

ServiceMax Job Job Status Status of migration

ServiceMax Job Message Holds the source org and source user info, and details of any error encountered during migration

ServiceMax Job Attachment There will be two attachments. The first is for capturing status log messages. It is named Migration Log.txt. The second is for capturing all the relevant details of migration items, including the dependent items, in JSON format. It is named SVMX Migrated Items.txt.

The following table provides the details of access and permissions required for the user

using the migration tool:

Actions User Permissions Needed

To view migration status record: "Read" on ServiceMax Job

To get migration status record created: "Create" on ServiceMax Job

Configuration

There are no configuration options applicable for this feature.


of 23

How to migrate Configuration Items using the Tool

Pre-Migration Actions

If any of the following are defined in source org and used in any ServiceMax configuration

items identified for migration, migrate them to the target org (using Salesforce tools

Change Set Deployment or Eclipse, or using ServiceMax configuration screens):

1. Custom objects and custom fields in standard / custom objects

2. Custom Apex web services / JavaScript code snippets (referenced in SFM Transaction

or SFM Custom Action)

3. Field Sets defined for any custom or standard objects (referenced in SFM Transaction)

4. Images / Documents referenced in Output Document Templates

5. Any dependent configuration items of SFM Custom Actions such as VF page and

Apex class (referenced in SFM Wizard)

Identify custom SFM Mappings which have any lookup field(s) mapped to values (specific

records in source org)


of 23

Using the Tool

1. Launch the ServiceMax Migration Tool from https://migrate.servicemax.com.

Figure 1: ServiceMax Migration Tool home page

2. Login to the source org by clicking the title Select Configuration Source.

Figure 2: After logging into source org

3. Login to the target org by clicking the title Select Configuration Target.

Figure 3: After logging into target org



of 23

4. If you need to login to a different source or target org, you can click the logout icon (

) next to the source org or target org as needed and login again.

5. If you need to login to different source AND target orgs, you can click the logout icon (

) at the top right of the migration tool screen and login again.

6. Identify the configuration items to be migrated and select them:

a. Expand the configuration tree to see the list of custom items of each supported

type, which are available for migration.

b. You can use the inline filter (Enter keyword(s) to filter...) to search for the required

items.

c. To select all the items of a type (say Configuration Profiles), check the checkbox

against that type – it will auto-select the checkboxes for each item of that type.

Note: If you have selected only some of the items of a particular type, the

checkbox next to that type will be displayed in grey

Figure 4: Select configuration items to migrate


of 23

7. Check the target org area to confirm if you have selected all the required items – it will

be auto-populated with the name of items to be migrated, as you select each item in

the source org area

Figure 5: Configuration items selected for migration


of 23

8. Click the Validate button

Figure 6: Validation Result screen

9. Review the validation result displayed:

a. Verify that all the required configuration items have been included and marked as

This will be migrated

Figure 7: Validation Result – Profiles & Mobile Configuration


of 23

b. Mark if overwrite should be allowed for any of the selected configuration items

already existing in the target org.

c. Expand such items to check if there are any dependent items which will be

overwritten.

Note:

If there are only standard dependent items or no dependent items, the message

There are no applicable dependents is displayed.

The message Profile does not exist in target org shown in the screenshot above

indicates that if you need to migrate Mobile Configuration / SFM Mobile

Permissions for a group configuration profile, you must migrate the profile first.

d. If any configuration item is marked as This will not be migrated, expand the item

to see the details and decide if you want to cancel the migration to take any pre-

migration actions

Figure 8: Validation Result - SFM Transactions

10. Click Migrate to migrate the required configuration items to the target org; click Cancel

to abort the migration

11. If a warning message about difference between source and target orgs is displayed

due to version mismatch, you can cancel the migration and click the Session

Information icon ( ) in the home page to know the source and target versions.


of 23

Figure 9: Session Information

12. If a warning message about difference between source and target orgs is displayed

due to license mismatch, note that you can proceed with the migration. However,

access to the configuration will be restricted by the license type in the target org.


of 23

Post-Migration Actions

1. Add the migrated SFM Wizards to the Wizard Layouts

2. Set Default Lookup Configuration flag for any required migrated Lookup Configurations

3. Edit the custom SFM Mappings identified during pre-migration, set the lookup field(s)

mapped to source org values (displayed as SFIDs) to target org values, and save

4. Associate the appropriate Salesforce profiles to the migrated ServiceMax

Configuration Group profiles

5. Launch the migrated configuration items from the designer / configuration screens and

check if there are any errors / exceptions

6. Launch the migrated configuration items from the delivery screens and check if there

are any errors / exceptions

7. If any errors / exceptions are found when executing the previous two steps, check if all

the metadata items listed in Pre-Migration Actions section have been migrated to

target org, and migrate any missing items


of 23

Known Issues/Limitations

SFM Transactions:

o Default Lookup Configuration flag is not migrated from source to target org

o An SFM Transaction will not be migrated, if the page layout associated with it

already exists in the target org and there is a mismatch between source and target

orgs with respect to the child section name, count, or sequence

o Values (specific records in source org) mapped for Lookup field(s) in Custom SFM

Mappings are not resolved to values in target org

Output Documents:

o Images / Documents referenced in an Output Document Template are not

migrated

o An Output Document will not be migrated, if the output document template

associated with it already exists in the target org and there is a mismatch between

source and target orgs with respect to the child section name, count, or sequence

SFM Wizards:

o The newly created SFM Wizards in the target org are not automatically added to

the layout configuration

o If a wizard has a step associated with an SFM Custom Action and the action refers

to a VF page / Apex class, those dependent items are not migrated

o Wizard steps associated with SPRL Processes are not migrated

ServiceMax Configuration Profiles

o Salesforce profiles associations are not migrated.

o Existence of any custom fields configured in any of the settings is not checked

in target org, at any stage of validation or migration. This is also applicable to

fields defined for DC Field updates and iPad settings.

Mobile Configurations

o Mobile Configurations are not migrated if associated ServiceMax Group

Profiles are not available in the target org

SFM Mobile Permissions

o SFM Mobile Permissions are not migrated if associated ServiceMax Group

Profiles are not available in the target org

Translations defined using the ServiceMax Translation Workbench

o All available translations are migrated for all supported languages


of 23

o Any existing translation will be overwritten

o Translations for Wizard Step Description for all selected SFM Wizards, and

Description for Search Objects in all selected SFM searches will not be

migrated

SFM Expressions and Advanced Download Criteria:

o When an SFM Expression and an Advanced Download Criteria expression

have the same name in the source org, the item migrated first is overwritten by

the item migrated last to the target org

SFM Formulas

o Existence of any custom fields used in SFM Formulas is not checked in target

org, at any stage of validation or migration

All the migrated configuration items:

o Existence of any referenced JavaScript code snippets, VF pages, and Field Sets

is not checked in target org, at any stage of validation or migration

o The history of migrations is not recorded in the target org against the individual

migrated items, for a quick and intuitive reference. However, the details of each

individual migration are captured in the ServiceMax Job record created in the

target org and the completion status email sent to the target org user, to both of

which a log file is attached

o There is no option to save the list of items selected for migration, for future use


of 23

Tips for Troubleshooting

Scenario / Issue Solution

Get the details of dependent items migrated

Look for ServiceMax Job record of Type Configuration Migration Tool, and check the attachment named SVMX Migrated Items.txt.

Validation result for an item selected for migration indicates a missing custom object, custom field, or Apex class

Ensure that any referenced entity reported as missing is deployed to the target org before commencing migration

Validation result for an SFM Transaction is This item will not be migrated

Check if the associated page layout already exists in the target org, and if there is a mismatch between source and target orgs with respect to child section name, count, or sequence. If yes, clone the page layout in target org and associate the other SFM Transactions with the cloned page layout. Alternatively, clone the page layout in source org and associate the cloned page layout with the SFM Transaction(s) to be migrated. If the error message lists any missing fields, ensure that they are created in the target org before re-trying the migration

Validation result for an Output Document is This item will not be migrated

Check if the associated output document template already exists in the target org, and if there is a mismatch between source and target orgs with respect to child section name, count, or sequence. If yes, clone the template in target org and associate the other output documents with the cloned template. Alternatively, clone the template in source org and associate the cloned template with the Output Document(s) to be migrated. If the error message lists any missing fields, ensure that they are created in the target org before re-trying the migration

Validation result for a Mobile Configuration is This item will not be migrated

Check if the associated ServiceMax Configuration Group profile is available in the target org. If no, migrate the configuration profile to the target org. Check if any custom field is referenced in any expressions related to download criteria or advanced download criteria. Create a similar custom field in the target org, with the same API name as in the source org.

Validation result for Inventory Process is This item will not be migrated

Check if any custom field / custom record type is referenced in the process. Create a similar custom field / custom record type in the target org, with the same API name as in the source org.


of 23

Scenario / Issue Solution

Validation result for SFM Mobile Permissions is This item will not be migrated

Check if the associated ServiceMax Configuration Group profile is available in the target org. If no, migrate the configuration profile to the target org. Check the SFM processes that associated with the selected profile for any meta data issues (like the ones mentioned in validation results for SFM Transactions above). Try migrating the processes independently to isolate the issue.

Validation result shows The user does not have sufficient permissions on the target org to proceed with the migration. Contact your System Administrator for details.

Ensure that the logged in user’s Salesforce profile has all field and object-level permissions to ServiceMax configuration objects such as ServiceMax Processes, ServiceMax Config Data, Page Layout, Page Layout Details, SFM Events and so on.


of 23

Appendix

List of Supported Dependent Items

SFM Transactions:

o SFM Expressions

o SFM Mappings: Field and Value maps

o Source Object Updates

o Page Layouts with Lookup Configurations

o SFM Data Validation Rules

o SFM Formulas

o Advanced Options:

Attachment configuration

Field Sets

Linked Process (the SFM Transaction configured as the linked process will

also get migrated automatically)

Multi-Source Configuration (the SFM Transaction configured as the sub-

process will also get migrated automatically)

Sorting

Translations loaded using ServiceMax Translation Workbench for all

supported languages

SFM Wizards:

o Wizard Steps, including any associated custom SFM Transactions (including

Output Documents), SFM Custom Actions, and custom Inventory processes

o Criteria to show a Wizard / enable a Wizard Step

ServiceMax Configuration Profiles:

o Standard modules, submodules and settings

o Custom Modules, submodules and settings

Mobile Configurations:

Download criteria: Objects, their ownership and filtering expressions

Synchronization settings and Other settings

Advanced Download criteria

SFM Mobile Permissions:

Assigned SFM View and Standalone create processes