|
Dynamic Mappings |
Scroll |
Dynamic mappings can provide runtime invocation of a user process that provides the SOURCE MAPPINGS parameter values in JSON format for each fully qualified SOURCE object (table) name not specified by Static MAPPINGS.
Syntax
MAPPINGS EXIT
/+
<mapping_exit_name> [<parm1> [, <parm2>] ...]
+/
Keyword and Parameter Descriptions
Static Mappings Optional syntax and parameters
<mapping_exit_name> Fully qualified name of the mapping exit.
<parm1>, ...<parmn> One or more optional parameters that will be passed to the mapping exit. One additional parameter will be automatically added containing the name of the fully qualified SOURCE object (table) enclosed in double quotes.
Notes:
1.One or more Static MAPPINGS Source(s) may precede the MAPPINGS EXIT statement and will take precedence over the Exit.
2.The content between /+ and +/ will be taken verbatim, if necessary a space will be added at the end and the quoted fully qualified source object (table) name will be appended. The resulting string will be used to invoke the specified mapping exit process. The stdout of that process will be parsed by the Replicator Engine as JSON.
3.Typically used to accommodate "new" source objects when they have not yet been specified by a Static MAPPINGS SOURCE entry. The exit may dynamically generate JSON TOPIC/SUBJECT/ALIAS object and value pairs. The exit may also perform exception processing, that terminates execution of the Replicator or instructs the Replicator to "ignore" the SOURCE object.
4.Kafka may or may not be configured to allow a PRODUCER to create unregistered Topics.
Example 1:
The Replicator Engine will call the exit "mysqdata_mappings" along with a parameter specifying the environment. This will occur both at startup and again each time it receives a source record from the Capture indicating a new or altered Source object not preceeded by STATIC MAPPINGS.
MAPPINGS EXIT
/+
/var/sqdata/app/mysqdata_mappings --env=prod
+/
;
The Replicator Engine will then call the an Exit configured as a bash shell script once for each Source object published.
/usr/local/bin/mysqdata_mappings.sh --env=prod
The shell script might contain the following instructions:
#!/bin/bash
echo "{"subject":"$1-%(env)-value","topic":"$1-%(env)","alias":"$1","namespace":"sqdata"}"
The Exit would return the following, if the Source object (Table Name) of the first such CDC source record is EMPLOYEE:
{ "subject":"employee-prod-value", "topic":"employee-prod ", "alias":"employee", "namespace":"sqdata" }
The "subject", "topic", "alias" and "namespace" of the returned JSON object are recognized. If present they must be of type “string”. Any other fields are silently ignored and the result will essentially identical to a Static Mappings statement, had it been specified:
MAPPINGS
SOURCE 'IVP_HR.EMPLOYEE'
TOPIC 'employee-prod'
SUBJECT 'employee-prod-value'
ALIAS 'employee'
NAMESPACE 'sqdata'
;
Example 2:
By default the Replicator Engine will automatically generate a new Kafka message Topic when it encounters a source object not accommodated by a Static MAPPINGS or or by logic within a Dynamic Mappings exit. The MAPPINGS EXIT can also be used to terminate the Replicator rather than generate the Topic.
MAPPINGS EXIT
/+
/var/sqdata/app/terminate_on_unknown_source.sh
+/
The Exit might, for example then return:
{ "error":"SQData Replicator has encountered unknown source table: <table_name>" }
Example 3:
Often source data may be captured before a Replicator Engine has been configured to process the data. Such data can be accommodated either by the default generation of a new Topic or a Mappings Exit that constructs the SOURCE MAPPINGS parameters for a new Topic. Alternatively the Replicator Engine can "ignore" such data using either the OPTIONS IGNORE NOMAPPING or a MAPPINGS EXIT that specifies "ignore".
MAPPINGS EXIT
/+
/var/sqdata/app/ignore_unknown_source.sh
+/
The Exit might, for example then return:
{ "ignore":"SQData Replicator has encountered unknown source table: <table_name>" }
