Senzing v4 SDK Breaking Changes

Items listed in this section are breaking changes from Senzing v3 to Senzing v4.

Note

In the following sections, C/C++ language function names are listed. The function names are very similar for C#, Java, and Python. For example:

  • C/C++: Sz_addRecord
  • C#: AddRecord
  • Java: addRecord
  • Python: add_record
  • sz_command: add_record

File changes

Senzing Engine Configuration File

  • The Senzing project install etc/G2Module.ini file is now renamed etc/sz_engine_config.ini. This file is the equivalent of the SENZING_ENGINE_CONFIGURATION_JSON environment variable

Package Structure Changed

  • senzingsdk-runtime (was senzingapi-runtime)

  • senzingsdk-tools (was senzingapi-tools)

  • senzingsdk-setup (was senzingapi-setup)

  • senzingsdk-poc (was senzingapi)

Install Path Changed

  • /opt/senzing/er/ (was /opt/senzing/g2/)

Executables Removed

  • dbexport: A program used for retrieving data from the G2 database repository, originally built for working with different non-sql database types

Executables Changed

  • bin/sz_configupgrade (was bin/g2configupgrade)

  • bin/sz_dbupgrade (was bin/g2dbupgrade)

Python Scripts and Utilities Changed

  • bin/sz_audit (was python/G2Audit.py)

  • bin/sz_command (was python/G2Command.py)

  • bin/sz_configtool (was python/G2ConfigTool.py)

  • bin/sz_explorer (was python/G2Explorer.py)

  • bin/sz_file_loader (was python/G2Loader.py)

  • bin/sz_setup_config (was python/G2SetupConfig.py)

  • bin/sz_snapshot (was python/G2Snapshot.py)

Python Scripts Removed

  • CompressedFile.py
  • DumpStack.py
  • G2S3.py

Function Changes

Function Prefix Changed

All C/C++ functions now start with the prefix Sz. Any existing functions have been renamed from G2 to Sz.

SzEngine (G2Engine) Functions Added

  • Sz_preprocessRecord

SzEngine (G2Engine) Functions Renamed

  • Sz_closeExportReport (was Sz_closeExport)

  • Sz_findPathByEntityIDWithAvoids (was G2_findPathExcludingByEntityID)

  • Sz_findPathByEntityIDWithAvoids_V2 (was G2_findPathExcludingByEntityID_V2)

  • Sz_findPathByRecordIDWithAvoids (was G2_findPathExcludingByRecordID)

  • Sz_findPathByRecordIDWithAvoids_V2 (was G2_findPathExcludingByRecordID_V2)

  • Sz_findPathByEntityIDIncludingSource (was G2_findPathIncludingSourceByEntityID)

  • Sz_findPathByEntityIDIncludingSource_V2 (was G2_findPathIncludingSourceByEntityID_V2)

  • Sz_findPathByRecordIDIncludingSource_V2 (was G2_findPathIncludingSourceByRecordID_V2)

  • Sz_getRecordPreview (was Sz_preprocessRecord)

SzEngine (G2Engine) Functions Removed

Several SDK functions have been removed from the SDK. In most cases, another function exists with the same functionality as the previous function, but with an improved signature. If applicable, a remediation is suggested.

  • G2_addRecordWithReturnedRecordID: Use Sz_addRecord and always pass in a RECORD_ID

  • G2_addRecordWithInfoWithReturnedRecordID: Use Sz_addRecordWithInfo and always pass in a RECORD_ID

  • G2_whyEntityByEntityID: Sz_howEntity is the preferred method for explaining resolutions

  • G2_whyEntityByRecordID: Sz_howEntity is the preferred method for explaining resolutions

  • G2_process: This was internal, though we were using it in 3.x for the G2_getRedoRecord/G2_process pattern, which is now Sz_getRedoRecord/Sz_processRedoRecord

  • G2_processWithResponse: This was internal, and is now fully removed

  • G2_processWithResponseResize: This was internal, and is now fully removed

  • G2_exportConfig: Equivalent functionality is now available in the SzConfigManager SDK

  • G2_exportConfigAndConfigID: Equivalent functionality is now available in the SzConfigManager SDK

  • G2_checkRecord: Internal function now fully removed

  • G2_purgeRepository: Moved to the internal SzDiagnostic SDK. Now an internal function

WithInfo Functions

  • The G2_addRecordWithInfo and G2_deleteRecordWithInfo functions have been removed from the Java SDK and Python SDK. The WithInfo functionality has now been included in the Sz_addRecord and Sz_deleteRecord functions when the SZ_WITH_INFO flag is used.

  • G2_processWithInfo: This was internal, though we were using it in 3.x for the G2_getRedoRecord/G2_process pattern, which is now Sz_getRedoRecord/Sz_processRedoRecord. The WithInfo functionality has now been included in the Sz_processRedoRecord function when the SZ_WITH_INFO flag is used.

  • The Sz_addRecord, Sz_deleteRecord, and Sz_processRedoRecord functions now return a null value if the SZ_WITH_INFO flag is not used.

Internal SzConfig (G2Config) Functions Renamed

  • SzConfig_registerDataSource (was G2Config_addDataSource)

  • SzConfig_unregisterDataSource (was G2Config_deleteDataSource)

  • SzConfig_getDataSourceRegistry (was G2Config_listDataSources)

Internal SzDiagnostic Functions Added

  • SzDiagnostic_purgeRepostiory: Moved here from the main SDK

  • SzDiagnostic_getRepositoryInfo (undocumented)

Internal SzDiagnostic Functions Removed

We removed the following functions, all of which were undocumented, and for internal-use only.

  • G2Diagnostic_getPhysicalCores: (undocumented)

  • G2Diagnostic_getLogicalCores: (undocumented)

  • G2Diagnostic_getTotalSystemMemory: (undocumented)

  • G2Diagnostic_getAvailableMemory: (undocumented)

  • G2Diagnostic_getDBInfo: (undocumented)

  • G2Diagnostic_getDataSourceCounts: (undocumented)

  • G2Diagnostic_getMappingStatistics: (undocumented)

  • G2Diagnostic_getGenericFeatures: (undocumented)

  • G2Diagnostic_getEntitySizeBreakdown: (undocumented)

  • G2Diagnostic_getEntityDetails: (undocumented)

  • G2Diagnostic_getResolutionStatistics: (undocumented)

  • G2Diagnostic_getRelationshipDetails: (undocumented)

  • G2Diagnostic_getEntityResume: (undocumented)

  • G2Diagnostic_getEntityListBySize: (undocumented)

  • G2Diagnostic_fetchNextEntityBySize: (undocumented)

  • G2Diagnostic_closeEntityListBySize: (undocumented)

  • G2Diagnostic_findEntitiesByFeatureIDs: (undocumented)

  • G2Diagnostic_getFeature: (undocumented)

Internal SzAudit (G2Audit) Functions Deprecated

This SDK is now considered to be fully deprecated, and should not be used anymore.

Engine Flag Changes

Flag Prefix Changed

All flags now start with the prefix SZ_. Any existing flags have been renamed from G2_ to SZ_.

New Flags

  • SZ_ENTITY_INCLUDE_RECORD_TYPES: Include record types in the entity documents

  • SZ_ENTITY_INCLUDE_RELATED_RECORD_TYPES: Include record types for related entities in the entity documents

  • SZ_ENTITY_INCLUDE_RECORD_UNMAPPED_DATA: Include unmapped data in the entity documents

  • SZ_ENTITY_INCLUDE_MATCH_KEY_DETAILS: Include a more detailed version of the match keys for entities and relationships

  • SZ_FIND_PATH_MATCHING_INFO: Include the relationship matching info for entity relationship paths

  • SZ_FIND_NETWORK_MATCHING_INFO: Include the relationship matching info for networks of related entities

  • SZ_FIND_NETWORK_DEFAULT_FLAGS: Similar to G2_FIND_PATH_MATCHING_INFO, but more focused on graphs

  • SZ_HOW_ENTITY_DEFAULT_FLAGS: Provides recommended information for the SDK how-functions

  • SZ_RECORD_PREVIEW_DEFAULT_FLAGS: Provides record feature details for getRecordPreview

  • SZ_SEARCH_INCLUDE_MATCH_KEY_DETAILS: Include the detailed match key information in search results

  • SZ_WHY_ENTITIES_DEFAULT_FLAGS: Similar to the removed flag G2_WHY_ENTITY_DEFAULT_FLAGS, focused specifically on the whyEntities* SDK functions.

  • SZ_WHY_RECORDS_DEFAULT_FLAGS: Similar to the removed flag G2_WHY_ENTITY_DEFAULT_FLAGS, focused specifically on the whyRecords* SDK functions.

  • SZ_WHY_RECORD_IN_ENTITY_DEFAULT_FLAGS: Similar to the removed flag G2_WHY_ENTITY_DEFAULT_FLAGS, focused specifically on the whyRecordInEntity* SDK functions

  • SZ_WITH_INFO: Provides an AFFECTED_ENTITIES list of new, updated, or no-longer-valid entities when using addRecord or deleteRecord

  • SZ_VIRTUAL_ENTITY_DEFAULT_FLAGS: Provides recommended information for the SDK virtual-entity functions

Renamed and Modified Flags

  • SZ_EXPORT_DEFAULT_FLAGS(was G2_EXPORT_DEFAULT_FLAGS): Reduced the information returned for each entity, to match the normal entity defaults

  • SZ_EXPORT_INCLUDE_MULTI_RECORD_ENTITIES (was G2_EXPORT_INCLUDE_RESOLVED)

  • SZ_EXPORT_INCLUDE_SINGLE_RECORD_ENTITIES (was G2_EXPORT_INCLUDE_SINGLETONS)

  • SZ_EXPORT_INCLUDE_ALL_HAVING_RELATIONSHIPS (was G2_EXPORT_INCLUDE_ALL_RELATIONSHIPS)

  • SZ_FIND_PATH_DEFAULT_FLAGS(was G2_FIND_PATH_DEFAULT_FLAGS): Returns more path-based information, and less entity information

Removed Flags

  • G2_ENTITY_INCLUDE_RECORD_FORMATTED_DATA: This provided the mapped input data in a specialized format. This has been removed, but unmapped data is now available with the SZ_ENTITY_INCLUDE_RECORD_UNMAPPED_DATA flag

  • G2_WHY_ENTITY_DEFAULT_FLAGS: This used to work with the various why* functions. It has been divided into new, more specific flags for the individual functions

JSON Response Document Changes

The format and contents of the JSON response documents has changed significantly.

Sz_findNetwork Response Document

Sz_findNetwork response document includes all Sz_getEntity* response document changes.

  • Added ENTITY_PATH_LINKS section

  • Added ENTITY_NETWORK_LINKS section

RESOLVED_ENTITY Section

  • Removed LAST_SEEN_DT

  • Added FIRST_SEEN_DT

  • Added RECORD_TYPES section

FEATURES Section

  • Added ELEMENT values

RECORD SUMMARY Section

  • Removed FIRST_SEEN_DT and LAST_SEEN_DT

RECORDS Section

  • Added FIRST_SEEN_DT

  • Added UNMAPPED_DATA section

  • Removed ENTITY_TYPE, ENTITY_KEY, ENTITY_DESC, and MATCH_LEVEL

  • Removed NAME_DATA, ATTRIBUTE_DATA, IDENTIFIER_DATA, ADDRESS_DATA, PHONE_DATA, RELATIONSHIP_DATA, ENTITY_DATA, and OTHER_DATA sections

  • Added MATCH_KEY_DETAILS

  • Added RECORD_TYPES section

  • Removed MATCH_LEVEL

  • Removed FIRST_SEEN_DT and LAST_SEEN_DT

  • Removed FIRST_SEEN_DT and LAST_SEEN_DT from RECORDS subsection

Sz_getRecord Response Document

RECORDS Section

  • Added FIRST_SEEN_DT

  • Added UNMAPPED_DATA section

  • Removed ENTITY_TYPE, ENTITY_KEY

  • Removed NAME_DATA, ATTRIBUTE_DATA, IDENTIFIER_DATA, ADDRESS_DATA, PHONE_DATA, RELATIONSHIP_DATA, ENTITY_DATA, and OTHER_DATA sections

Sz_howEntity Response Document

Sz_howEntity response document includes all Sz_getEntity* response document changes.

  • Added WHY_KEY_DETAILS section (equivalent to MATCH_KEY_DETAILS)

FEATURE_SCORES Section

  • Renamed INBOUND_FEAT to INBOUND_FEAT_DESC, CANDIDATE_FEAT to CANDIDATE_FEAT_DESC

  • Added ADDITIONAL_SCORES subsection that contains the different component scores

Sz_searchByAttributes Response Document

Sz_searchByAttributes response document includes all Sz_getEntity* response document changes.

RESOLVED_ENTITY Section

  • Added MATCH_KEY_DETAILS to MATCH_INFO subsection

  • Removed MATCH_LEVEL from MATCH_INFO subsection

FEATURE_SCORES Section

  • Renamed INBOUND_FEAT to INBOUND_FEAT_DESC, CANDIDATE_FEAT to CANDIDATE_FEAT_DESC

  • Added ADDITIONAL_SCORES subsection that contains the different component scores