This feature allows the target location for items to be based upon rules which use source item metadata properties. For example, documents should go to a folder called ‘Financial Records’ if the value of a Department property = ‘Financial’. In the examples discussed below, only the Target Folder is being assigned for the item, but just like normal structure mapping, the mapping can define Site Collection, Library and Folder within the target.

 

 

NOTE: The Pseudo code examples below are not how the rules are structured but serve to explain the capabilities that this feature can provide.

Example 1: 

IF Department=” Finance” AND CustomerType=”Top50” THEN           Target Folder=” Large Accounts Finance Data”

Example 2:

Target Folder=”All Non Financials” ;  (You can define a ‘catch all’ target folder) IF Department=”Finance” AND CustomerType=”Top50” THEN         Target Folder=”Finance Large Accounts” ELSE              IF Department=”Finance” THEN                 Target Folder=” Finance Small Accounts”        ENDIF ENDIF

 

NOTE: When using this feature, it’s essential to take a two pass approach to the migration.  When in the migration phase, first execute up to Step 3-Transform ONLY.  This will generate the necessary information about the location items will be migrated to.  After this has been executed for all items, then Step 4 – Load can be executed.

 

7.4.1.  Configuration Steps for Restructuring using Item Metadata

Metadata structure mapping works by defining a ‘Target Assignment Expression’ whose resulting output is examined for a match in the structure mapping table to determine the target to assign the item to.

Configuration Steps:-

1. Specify Target Assignment Expression
2. Populate the structure mapping table with values to compare with the output from step 1 and the target location.

The process to configure it will be explained by the example below.

Step1: Defining Target assignment expression

Scenario: Assign items to Target based upon the value of source metadata field ‘ItemDepartment’. The name of source metadata fields that can be used are visible in Populating Target metadata field form.

Example Target Assignment Expression

Department=’{ItemDepartment}’

Example Source Item Metadata

Item No	ItemDepartment	Result from Expression Evaluation
1	HR	Department =’HR’
2	Finance	Department =’Finance’
3	Security	Department =’Security’

 

Example Structure Mappings

SourcePath	TargetPath
Department =’HR’	HR Items
Department =’Finance’	Finance Items

 

When Item No. 1 is processed, during the Transform step, the Target Assignment Expression is read, the value from the metadata field ItemDepartment is retrieved and replaces the field name in the expression to generate the result, Department=’HR’  This is then used to scan for a matching entry in the structure mappings table and a row with the matching value is found so the TargetPath is read and that item is assigned with a TargetPath of “HR Items”.

Similarly for Item No. 2,the result is Department=’Finance’ and the item is assigned to “Finance Items”.

Item 3 would generate a result of Department=’Security’ but wouldn’t find a match in the structure mapping table and so the item would fail to be migrated because no target would be assigned.

In Target Assignment Expressions, the variable name shown in this example ‘Department’ can a be any string, what’s essential is that the output from the expression is in the structure mapping table.

NOTE: You cannot use comparators like “<>” nor Boolean operations like “OR” etc. in these Expressions.  In these examples comparators = and Booleans like AND are just text to make the expression human readable. It’s not the case that they’re used during expression evaluation.  Target Folders Assignment expressions are simply processed by replacing field labels with actual metadata values and the output value used to find exact matching entry in structure mapping.

 

7.4.2.  Advanced Target Assignment Expressions

Target Assignment expressions support have additional capabilities.

In this second example Finance Items related to Top50 customers goes to Finance Large Accounts, otherwise Finance Items go to Finance Small Accounts.  All other items will go to the “All Non Financials” folder.

In the example expression below, the first criteria is based upon two fields and then a second separate criteria is specified after the semi-colon.

Department=’{ItemDepartment}’ AND CustomerType=’{ItemCustomer}’ ; Department=’{ItemDepartment}’

Example Source Item Metadata

Item No	ItemDepartment	CustomerType	Output from Expression
1	HR		Department =’HR’
2	Finance	Top 50	Department =’Finance’ AND CustomerType=’Top 50’;Department='Finance’
3	Security		Department =’Security’
4	Finance		Department =’Finance’ AND CustomerType=’’;Department='Finance’

Example Structure Mappings

SourcePath	TargetPath
Department =’HR’	HR Items
Department =’Finance’ AND CustomerType=’Top 50’	Finance Large Accounts
Department =’Finance’	Finance Small Accounts

 

When Item 2 is processed the expression is evaluated and the first element of the output “Department =’Finance’ AND CustomerType=’Top 50’” is used to lookup on Structure Mapping and so assigns item to TargetPath ‘Finance Large Accounts’.

For item 4, the Customer Type is empty so the output from first expression is Department =’Finance’ AND CustomerType=’’ which has no matching entry in structure mapping so the next element of the output  Department='Finance’ is used for structure mapping lookup and so items are assigned to the TargetPath of Finance Small Account.

Target Assignment Expression order

It’s essential to understand that expressions are processed from left to right, so in the above example the more ‘specific’ criteria is evaluated first. Only if an item doesn’t meet the first criteria for ‘Department AND CustomerType’, is it then evaluated based on Department only.

Example of two expressions in the WRONG order.

Department=’{ItemDepartment}’ ; Department=’{ItemDepartment}’ AND CustomerType=’{ItemCustomer}’

This is evaluated as: -

Department=’Finance’ and then

Department=’Finance’ AND CustomerType=’Top50’

In this example every ‘Finance’ record would always meet the first criteria since it’s broader, even though the more specific second rule is what is intended for some items.

 

7.4.3.  Default Target Assignment

When using criteria to assign folders it’s possible that some folders may not match any of the criteria specified.  To cover this scenario, a ‘Default’ folder can be assigned to such items.  If no ‘Default’ folder is configured, then these items will not be migrated.

Scenario:  Items which don’t match any specific values in the structure mapping table should be assigned a specific target location

Effectively this is just a case of creating criteria that is evaluated last of all and will always have a matching entry in the structure mapping table.

Department=’{ItemDepartment}’ AND Customer=’{ItemCustomer}’ ; Department=’{ItemDepartment}’;Default

Example Source item metadata

Item No	ItemDepartment	Result of Evaluation
1	HR	Department =’HR’
2	Finance	Department =’Finance’
3	Security	Department =’Security’

In the structure mapping specify in the field SourcePath an entry for Default and a target value.

Example Structure Mappings

SourcePath	Target Folder
Department =’HR’	HR Items
Department =’Finance’	Finance Items
Default	All Non Financials

In this example, when an item that’s not in ‘HR’ or ‘Finance’ is processed the last entry is processed which is simple the string value of ‘Default’. This ‘result’ is used to scan the structure mapping table and finds a matching entry and assigns the item to that target folder specified. It will always find a match on ‘Default’ so items from the ‘Security’ department will be assigned to a target folder of “All non Financials”

Example Metadata_Expressions_Structure_Mapping.csv

 

7.4.4.  Metadata Structure Mapping Configuration Steps

These are the steps to follow to configure Metadata Structure Mapping.

1-Specify Target Assignment Expression

Select the  option on the Restructure using Item Metadata

Enter the expression as required. e.g.

Department=’{ItemDepartment}’ AND CustomerType=’{ItemCustomer}’ ; Department=’{ItemDepartment}’;Default

Once the above file is changed it’s essential for the PMA application is restarted.

2-Download Template

 

Select the Restructure using Item metadata and select the icon to download the template to use. 

In the template the evaluated expression result should be placed in the SourcePath column.  All other target related columns should be completed as required.  See Restructure using Folders/Containers for more information.

Once the structure mapping file is complete, select the Import icon to import the file.  The contents of the structure mapping will be displayed.