Skip to main content

psaHarmonize Installation and User Guide

PSA Support
  • Updated

Table of Contents

 

 NOTE: Syniti’s Professional Service Accelerators (psa) have been developed and are supported by

a team of senior consultants. The psas are designed to supplement the Stewardship Tier delivered features with content and automation that accelerate the progress of the project. If you have any questions or encounter any issues while using a psa, please submit a support ticket and be sure to select the psa on the form.

The attached PDF file contains the contents of this article.

Professional Service Accelerators (PSAs) are licensed separately from the SST. For more information, please email NASMT@syniti.com. To download or install a PSA, submit a request to Syniti support.

 

Overview

psaHarmonize will harmonize any and all data into logical groupings that business users can confirm and use to load downstream objects. psaHarmonize makes setup and the user experience straightforward and simple. There are switchboards that contain metrics at a glance, and dashboarding to visually represent progress and potential issues.

 

Key Features:

  • Relevancy and Address Cleansing solutions included
  • Grouping Algorithm included
  • Integration with Data Services Address Cleansing and Harmonization solutions
  • Application comes preconfigured with common harmonization values
  • All Waves and Objects included
  • User Interface to allow business users to determine golden records from groupings
  • Reports to show statistics
  • User Enrichment of records
  • Application is designed to be customized to client request using configuration pages.

Install psaHarmonize

Install the application on Syniti Solutions DSP versions 7.0.1 and above.

Prerequisites

Install psaPerformanceBench prior to installing psaHarmonize. Refer to the psaPerformanceBench Application Guide for install details.

Download the Application & License

The psaHarmonize application and/or license are obtained by opening a support ticket at support.syniti.com

Perform the following steps to retrieve the necessary information for a license request:

  1. On the SST application server, locate the Hardware Identifier program (called “HardwareIdentifier.exe") included in a zip file along with the SST installation software and documentation previously downloaded from Syniti.
  2. Open the program.
  3. Click Generate.
  4. Copy the automatically generated ID and collect the following additional information. All information below pertains to the application server running SST; no information is needed regarding the database server:
    • Hardware ID (as mentioned above)
    • Windows computer name
    • Number of processor cores (as shown in the Task Manager CPU tab)
    • Usage of the SST instance, as in, DEV, TEST (or QA) or PROD
  5. Syniti Licensing will deliver the license file via the support ticket.

Install the License

Perform the following steps to install the license:

  1. Log in to the SST site as an Administrator.
  2. Select Admin > Configuration > Product Licenses in the Navigation pane.
  3. Click the Upload a file icon in the FILE NAME column next to the Upload a New Product License link.
  4. Locate the license file that was provided by Syniti Licensing.
  5. Click Open.
  6. Verify the license is uploaded.
    NOTE: If the Navigation pane does not display all the licensed components as expected, use the
    browser refresh button or the F5 key to refresh the screen. At this point the full vertical menu will appear.

Install the Application

Perform the following steps to install the application:

  1. Right-click on psaHarmonizes.zip and select Properties. Unblock the file if needed.
  2. Unzip the file.
  3. Navigate to the SST Installation folder. (e.g., D:\BOA\DSP or C:\Program Files (x86)\BOA\DSP)
  4. Back up the DSP Install\BOA\DSP folder to a compressed zip file.
  5. Back up all Syniti-supplied SQL Server databases or verify that a complete recent backup already exists
    NOTE: Supplied databases: AutoGen, cMap, cMap_Data, cMass,
    cMass_Data, Console, CranPort, CranSoft, DataConstructionServer, DataDialysis, DataGarage, DBMoto_Client, DGE, DGE_Data, dgReports, dgSAP, dspAddOn, DSPCommon, dspMonitor_AccPak, dspMonitorConfig, DSW, IGC, Integrate, IntegrateStaging, InterfaceServer, MC, & RADToolkit
  6. Stop IIS.

    This process disconnects all active SST users, so it is highly recommended to perform the install when no users are on the system. This process stops IIS on the web server.

    1. Open Windows Start Menu.
    2. Open the Command Prompt (run as Administrator).
    3. Type: IISReset –stop.
    4. Press the Enter key.
    5. Leave the Command Prompt window open for later use.
  7. Stop all services that start with “Cransoft Service …”

    This process stops all SST background jobs, so it is highly recommended to perform the install when no scheduled operations are running on the system.

    1. Open Windows Start Menu.
    2. Select Administrative Tools.
    3. Run Services.
    4. Right-click the SST service.
    5. Select Stop.
    6. Repeat the previous two steps for any additional SST services.
  8. Copy the Web folder from the zip file to the existing SST install\Web folder. If prompted, replace the files in the destination.
  9. Copy the Databases folder from the zip file to the existing SST install\Databases folder. If prompted, replace the files in the destination.
    NOTE: When copying the Databases\Apps folder, do not replace files in that folder.
  10. Navigate to SST install\Databases and execute file psaHarmonize_Install.bat (run as Administrator)
  11. Start all services that start with “Cransoft Service …”
    1. Open Windows Start Menu.
    2. Select Administrative Tools.
    3. Run Services.
    4. Locate the SST service(s).
    5. Right-click the SST service.
    6. Select Start.
    7. Repeat the previous two steps for any additional SST services.
  12. Start IIS.
    1. Open Windows Start Menu.
    2. Open the Command Prompt (run as Administrator).
    3. Type: IISReset –start.
    4. Press the Enter key.

Post Install Steps

If desired and approved at your client site you can choose to use a CLR (Common Language Runtime) version of the levenschtein algorithm. The benefits to using a CLR is improved performance over a normal SQL function. These steps are options and require administrative rights on the SQL server potentially requiring a SQL DBA to execute.

  1. Navigate to the DSP Install\Web\User Area folder.
  2. Open the folder named D29C8C60-12B8-4200-B09D-0AACC80EF33A.
  3. Locate the SQL Script named CLR_Enable.sql.
  4. Ensure you have administrative privileges on the SQL Server (If not a DBA will be required to execute the script). Also verify that the client site approves safe CLRs to be used.
  5. Open a new query window in SQL Server.
  6. Copy the contents of CLR_Enable.sql into the query window and execute.
  7. Now the CLR version of the levenschtein algorithm will be used when harmonize processing occurs.
    NOTE: A backup of the original function has been saved as boaLevenschteinScore_Bak.
    If at any time you need to revert you can run the script CLR_Disable.sql to switch back to the function and disable CLR functionality on the database.

     

Configure psaHarmonize

psaHarmonize comes preconfigured with default values in the configuration tables, but they will require modification per specific client needs.

If the Navigation pane in SST does not show psaHarmonize, then perform these steps:

  1. Log in to the SST site as Administrator.
  2. Select Admin > Configuration > Product License in the Navigation pane.
    • Ensure that psaHarmonize displays.
  3. Select Admin > Configuration > Site Menu in the Navigation pane.

    NOTE: Ensure that psaHarmonize displays. If psaHarmonize does not display:

    1. Click Add.
    2. Enter a priority in the PRIORITY field.
    3. Enter psaHarmonize as the label for the site menu option in the LABEL field.
    4. Select the psaHarmonize : psaHarmonize page from the LINK TO PAGE ID list box.
  4. Select Admin > Configuration > Parameters in the Navigation pane.
    1. Click Clear Cache.
    2. Reload the browser tab.

If the psaHarmonize application cannot be accessed, review the “Define Security Roles” article in the SST Online Help to ensure the SST user has access to psaHarmonize. The SST Online Help is accessible from the question mark icon in the top-right corner of all DSP pages. Also, open a ticket at support.syniti.com for assistance.

Security Configuration

Prior to users being able to log in and view data in psaHarmonize, security must be configured. psaHarmonize uses the ObjectID to control user access. In order to provision a user access to an ObjectID the following steps must be completed.

  1. Select Admin > Security > Security Management > Security Roles in the Navigation pane..
  2. Click the Keys icon for the Security Role group to provision access. (e.g., Migration Developer)
  3. Click the Keys icon for the ‘psaHarmonize Object Roles’ security definition.
  4. Add the Objects relevant for that grouping. (e.g., Customer/Vendor/Business Partner)

Grouping Configuration

Grouping Configuration controls all aspects of groups of data such as Customer, Vendor or Business Partner is processed.

psaHarmonize_1.png

Navigate to psaHarmonize > Config > Grouping.

Validate the ObjectID exists that will require harmonization (e.g., BusinessPartner)

  1. ObjectID – The name of the object that will be harmonized (Customer/Vendor/BusinessPartner).
  2. SteadyState – This object to be used after go-live as an ongoing process (normally unchecked).
  3. SteadyStateObjectID – The ObjectID to be used after go-live as the steady state ongoing process (Only populated if above is checked).
  4. Match Threshold – The minimum confidence score a record can have in common with another and become a grouping.
  5. Auto Approval Threshold – The lowest confidence score a grouping can have and become auto approved.
  6. Name – The SQL field values that will be used to generate the names for groupings.
  7. Status – Contains all of the grouping statuses and if they indicate if the grouping is complete or not
  8. Algorithm – Contains the keys that will be used by the algorithm to perform matches
    • Overall Weight – The overall weight that the algorithm will have (only valid when more than 1 algorithm is active)
    • Levenschtein Max (The maximum number of differences in a string that can be different before the algorithm stops and doesn’t score the comparison. For performance, 10 should be the max)
    • Candidate Threshold – The score that the grouping must be equal to or greater than to become a match
    • Active – If the algorithm is active or not
    • Field Config – The fields and SQL rules to create the key for grouping.
      • Dimension Field – The name of the key to hold data (must exist in ttBusinessPartner or ttMaterial).
      • Dimension Field SQL – The SQL required to generate the key.
    • Dimension SQL – The SQL that is used to update the Dimension Key field.
  9. Segment – If the records in the grouping are sufficiently large (generally over 10k) segmentation is suggested. This is achieved by entering a value in the max segment field. The page will then automatically split your grouping into multiple segments for processing.
  10. Sources – This should contain all zSource values for the Object.
    • Golden Record – Can this source be used to create a golden record?
    • Auto Approval – Can this source be used to auto approve records?
    • Allow Enrichment – Can this source be enriched (values updated through psaHarmonize and not the source)?
  11. Processing – This page contains all the operations required from start to finish to harmonize the selected object. Processing is done from this page. The user is encouraged to customize this page to fit their individual processing strategy for harmonization.

Grouping Status Configuration (Vertical View)

psaHarmonize_2.png

Additional functionality on the vertical view.

  1. Multiple Master – Toggles on/off functionality if Multiple Masters need to be selected within a single grouping.
  2. Subordinate – Toggles on/off functionality if records within a grouping need to be identified as Subordinates to a master record.
  3. Duplicate – Toggles on/off functionality if records within a grouping need to be identified as Duplicates to a master record.

Grouping Name Configuration

psaHarmonize_3.png

Specify the Grouping Name SQL that will be used to generate names for the groupings.

Grouping Status Configuration

psaHarmonize_4.png

Create or modify Grouping Status for each ObjectID.

  1. Grouping Status – The short name used by the system to indicate what the status represents.
  2. Description – A full description of the status for users to see.
  3. ImageID – The SST Image ID that will display as an icon for the image.
  4. Image – The icon users will see (based on the ImageID value)
  5. Active – Determines if the Status is active
  6. Complete – Does the status mean that the grouping is completed

Dimension Field Configuration

psaHarmonize_5.png

Set up the Keys that will be used to generate groupings.

  1. Dimension – The name of the key that will hold the values (must exist in ttBusinessPartner/ttMaterial table).
  2. OverallWeight – The weight that the individual key will be given. If you are using just 1 key make this 100%. If using multiple keys make sure the total between all equals 100%. (e.g., NameKey 40%, AddressKey 60%, 40+60 = 100%)
  3. LevenshteinMax – The maximum number of characters that do no match before the algorithm stops attempting to generate a score. (Default is 10)
  4. CandidateThreshold – The loweset percentage score that will be considered for generating a grouping with another record.
  5. Active – If the Key is active or not
  6. Field Config – Configuration for each SubKey to generate the Dimension
  7. DimensionSQL – If using multiple subkeys this controls the order of the FieldConfig (SubKeys) should be concatenated together.

Segment Configuration

psaHarmonize_6.png

Segmentation is required for large data sets (>10,000 records) that need to be harmonized. Segmentation allows smaller chunks of records to process and prevents timeouts.

  1. Max Segment – The maximum number of records desired for each segment. (Default 2,000)
  2. Row Count – Automatically generated from looking at the source data counts.
  3. Segment Count – Automatically generated based on dividing the MaxSegment by RowCount.
  4. Process Segment – Controls which segment is being processed (Set to 1 when processing, the system will increment it until finished).

Primary Source Configuration

psaHarmonize_7.png

Set up Source information and control how it is handled.

  • zSource – The name of the Source System
  • Master Record – Will this source be the master record when it is contained in a grouping with other sources. Only 1 source can be selected. (Example SAP_ECC could be the Master Record when grouped with other sources)
  • Auto Approval – Will this source be Auto Approved when there is just 1 source record in a grouping. (Can only be selected if Master Record is checked)
  • Allow Enrichment – Allows source data be modified within psaHarmonize by users.

Processing Configuration

psaHarmonize_8.png

This screen provides end to end Harmonization process within one page for easy understanding of all the different pieces that are required. All Events can be processed from this page.

  • Active – Determines if the Event is active or not.
  • Priority – Priority of the Event.
  • Description – Description of the Event.
  • EventType – Determines what type of Event will be processed.
  • {} – Parameters for the Event.
  • LinkToPage – Provides a link to the page when applicable.
  • JobStatus – Status of the job.
  • Job Start Time – Time the job was started.
  • Duration – Duration the Job took to execute.

 

Region Configuration

Cross reference from country code to country description.

 

Security Configuration

Set up field level access based on the psaHarmonize Role

 

Workflow Configuration

Set up the look and feel of the workflows that will be distrubted. Also choose if the workflow is active and what users are signed up to receive workflow.

 

Implementation Configuration

  • Message Type Config – Controls which Notes will be created and will send workflow if field HasResponse is checked.
  • Event Type Config – Configure additional Event Types for processing.
  • Event Type Param Config – Configure additional parameters for processing.
  • Logical Synonyms Config – Choose what words are replaced to improve matching (e.g., West to W).

Transform

Navigate to Transform > Central Wave and map data to the valid source table (e.g., ttCustomerGeneral). Validate relevancy rules

  1. Process Central Wave - Validate that ttBusinessPartner_Relevant is populated.
  2. Process Harmonize Wave - Validate ttBusinessPartner, ttCandidates and ttCandidatesGroup are populated.

    NOTE: On the initial run, use a subset of data (500 records or less to test the process).

Automate

Automate comes pre-loaded with interfaces to support initial batch load with segmenting.

  • psaHarm_Initial - This interface processes the Harmonize Busienss Partner – Ddup targets per segment.
    NOTE: Ensure the table psaHarmonization.dbo.ztSegmentProcess is set to 1 for the ObjectID being processed.
    NOTE: Run this through the psaHarmonize > Config > Grouping Config > Processing > psaHarmonize Initial Load by Segmentsprocess and ztSegmentProcess will automatically be reset.
  • psaHarm_Steady - This interface processes the Steady State objects under Business Partner DDup to support ongiong harmonization support. This can be scheduled to run every minute/hour/day to support client needs.
    NOTE: Cutover target must be run prior to using Steady State.

     

User Guide

The user guide will provide information on psaHarmonize pages and functionality.

 

Getting Started

Request access to the SST system with access to the psaHarmonize webapp.

Log in to the SST and navigate to the psaHarmonize WebApp (Using the site menu).

 

Harmonize Switchboard

psaHarmonize_9.png

The Harmonize Switchboard contains all Objects that are being harmonized on one page for easy access. This page provides an overview of the harmonization statistics and progress. Clicking the hyperlink on each column shows you the records that make up the count.

Field Description of the field
ObjectID The ObjectID that has been harmonized (e.g., BusinessPartner)
Total Records The total number of records considered for harmonization
Unique Records Records that did not find a similar record and therefore could not form a grouping
Grouped Records Records that find similar records to become a grouping
Total Total number of groupings created
Not Started Groupings that have not been touched by a business user
In Progress Groupings that have been touched by a business user but not completed
Complete Groupings that have been completed by a business user
Auto Approve Groupings that have been automatically approved by a transform rule
Master Records The number of records to be loaded into the Target system
Ungrouped Records that were in a grouping but were broken out by a business user
Recent Source Change Records in a grouping that were impacted by a source record change or creation
Xref View the cross reference data that will be used by downstream waves based upon the harmonization effort

 

Candidate Groups

The Candidate Group page organizes the candidates within higher level groups. These Groups can have a grouping status of NotStarted, InProgress or Complete.  This page has the ability to merge two groups together if they are found to be similar. Also, other records may be added to the grouping.  Finally, notes may be added to contact a manager with questions or to keep track of work and changes. Clicking the count under the Candidates column will drill down to the Candidates Detail page.

psaHarmonize_15.png

 

Candidate Details

psaHarmonize_11.png

The Candidate Details Page shows the individual Candidates under the selected grouping. This page has the following actions:

Image Field Name Field Description
psaHarmonize_16.png Mark All Master Marks all records in the grouping as master records. This is desired when all records within the grouping are unique.
psaHarmonize_17.png Move To Grouping Removes the selected candidate from the grouping and assign to another grouping.
psaHarmonize_18.png Add To Grouping Find a record from another grouping and move it from that grouping to the current grouping.
psaHarmonize_19.png Ungroup Removes record from the group and adds it to a new group by itself. This record will show up as Ungrouped on the Candidate Switchboard.
psaHarmonize_20.png Enrich Allows users to enrich fields on records marked as Primary BP, Primary Cust or Primary Vend different values that are more complete (Example Name1 – Corp, Name2 – Corporation).
psaHarmonize_21.png Reset Grouping Resets the entire grouping by unchecking Primary BP, Primary Cust and Primary Vend records as well as updating the Group Status to NotStarted.
psaHarmonize_29.png Mark Complete Marks the record with a Grouping Status of Complete. (Must have selected a Primary BP and Primary Cust/Primary Vend)
psaHarmonize_22.png Audit Log Page displays all changes made to the selected candidate.
psaHarmonize_23.png Additional Details Shows all the fields for the selected Candidate record. Can be used to determine which record to choose for a Primary BP, Primary Cust or Primary Vend.

NOTE: A click on this icon on the toolbar shows data for all candidates in the grouping
psaHarmonize_24.png Bank Details Shows bank details for the selected candidate.  Can be used to determine a primary record.

NOTE: A click on this icon on the toolbar shows data for all candidates in the grouping
psaHarmonize_25.png Company Code Shows company code details for the selected candidate.

NOTE: A click on this icon on the toolbar shows data for all candidates in the grouping
psaHarmonize_26.png Sales Org Shows sales org details for the selected candidate.

NOTE: A click on this icon on the toolbar shows data for all candidates in the grouping
psaHarmonize_27.png Purchasing Shows purchasing details for the selected candidate.
NOTE: A click on this icon on the toolbar shows data for all candidates in the grouping
psaHarmonize_28.png Partner Functions Shows partner function details for the selected candidate. NOTE: A click on this icon on the toolbar shows data for all candidates in the grouping
  Master Record Marks the record as the master record for the grouping. Multiple masters can be selected based upon configuration in the Config > Grouping > Vertical view page
  Subordinate Marks the record as a subordinate.
  SubordiinateTo Enter the master record that the record is a subordinate of. Only required if Multiple Masters are chosen in the grouping.
  Duplicate Marks the record as a duplicate
  DuplicateTo Enter the master record that the record is a duplicate of. Only required if Multiple Masters are chosen in the grouping.
psaHarmonize_30.png Notes Allows users to keep notes on the candidate or to raise a question to management.

 

Dashboards

The Dashboard page shows graphs for candidate groups with different groupings applied.

Candidate Group Chart The first and most important chart shows the number of candidates in different Grouping Statuses.  This can be used to monitor progress to determine how many records are left to be completed.
Candidate Group – Ungrouped – Chart This chart shows groupings that only have one record assigned, showing that they are unique. These groupings should be manually inspected to insure there are no other records similar.
Candidate Group – Country – Chart This chart shows candidates by country with their corresponding status. This allows users to work with the candidates by country.
Candidate Group – Account Group – Chart This chart shows the Group Status by Account Group allowing users to work the candidates by account group.

psaHarmonize_12.png

 

Troubleshooting

Troubleshooting Guide for troubleshooting the psaHarmonization web application.

 

Site Menu missing psaHarmonize link

When the psaHarmonization application is not visible in the site menu.

Request access to the psaHarmonization webapp to be able to view the application. Access can be granted at a user level, configurator or administration level.

 

No Data on the Candidate Switchboard

The Candidate Switchboard page shows the grouping status of the candidate groups for each ObjectID. The data becomes populated by adding a source table under the ttBusinessPartner object in the Central Wave in Transform.  Verify you have a source with data under the ttBusinessPartner object in the central wave. Also verify you are populating the Name and Address fields along with ObjectID, ObjectDataType, BusinessPartnerKey, zSource, zLegacyBusinessPartnerNumber and zLegacyBusinessPartnerSource fields. Once complete you must navigate to the Processing page in the psaHarmonization application and click the Process All button to refresh the data.

psaHarmonize_13.png

 

Cannot Enrich Candidates

Pencil Toolbar button is dithered on Candidate Details screen. The configuration table Config > Grouping Config > Source Config must be populated with the Source System value in field zSource and the Allow Enrichment checkbox must be checked.

psaHarmonize_14.png

 

License is Expired

Open a ticket with Syniti Solutions to request a new license key. Once the new license key is applied the application will be available again.

 

 

Updated on September 1st, 2021

 

Related articles