Updating parameter files from REST

One of the most important and time consuming things to do with Oracle GoldenGate is to build parameter files for the GoldenGate processes.  In the past, this required you to access GGSCI and run commands like:

GGSCI> edit params <process group>

After which, you then had to bounce the process group for the changes to take effect.  This process has improved a good bit and can be a bit more dynamic in my opinion.  

In a previous post (here), I showed you have to build an Extract using the associated REST API end-point and JSON.  Being able to build extracts/replicats by using a REST API and JSON is a huge step forward with how administration of the Oracle GoldenGate environment is done.  In this post, I want to show you how quickly you can update your parameter files by using REST API and JSON.

Note: I’m assuming you have some basic understand of how cURL works.  If not, refer to a tutorial that can be easily found on the internet.

The first thing you need to do is fine the contents of the parameter file for the extract/replicat.  Depending on your environment, this would be found in $DEPLOYMENT_HOME/etc/conf/ogg.

When you look at the above image, you can see that I have a few parameter files.  If I was to do a cat on the the IEXTTPC.prm file, you would see contents like:

extract IEXTTPC
useridalias CGGATE domain OracleGoldenGate
exttrail zz
sourcecatalog oggtst1
table tpc.categories;
table tpc.categories_descriptions;
table tpc.customers;
table tpc.customers_info;
table tpc.customers_lkup;
table tpc.next_cust;
table tpc.next_order;
table tpc.orders;
table tpc.orders_products;
table tpc.orders_status_history;
table tpc.orders_total;
table tpc.products;
table tpc.products_description;
table tpc.prodcts_to_categories;

The contents of this parameter file is quite simple.  

Let’s take the example of the requirement to add a new table to the parameter file.  This table is called blc.totals.  This table needs to be added to the bottom of the parameter file.  In the traditional process, I would have to access AdminClient and perform an edit params IEXTTPC; however, you want to do this without touching the server.  

The process to do this would be to use the Update (PATCH) cURL commands to modify the parameter file.  For more information on how to patch option, you can refer to GoldenGate REST API documentation (here).

What you nee to look at in the documentation, is the body section.  Within the body section, the config option.  This is an optional array parameter that takes text strings into the configuration.  The end result of what the contents of the parameter would look like:

{
"config":[
"extract IEXTTPC",
"useridalias CGGATE domain OracleGoldenGate",
"exttrail zz",
"sourcecatalog oggtst1",
"table tpc.categories;",
"table tpc.categories_descriptions;",
"table tpc.customers;",
"table tpc.customers_info;",
"table tpc.customers_lkup;",
"table tpc.next_cust;",
"table tpc.next_order;",
"table tpc.orders;",
"table tpc.orders_products;",
"table tpc.orders_status_history;",
"table tpc.orders_total;",
"table tpc.products;",
"table tpc.products_description;",
"table tpc.prodcts_to_categories;”,
“table blc.totals;"
] 
}

Notice that we are just taking all the contents of the parameter file and adding the table that needs to be added to the bottom.  Now you can use this JSON block to update the parameter file.  The cURL command to update the parameter file would look something similar to this:

curl --request PATCH \
--url https://localhost:16001/services/v2/extracts/IEXTTPC \
--header 'authorization: Basic b2dnYWRtaW46V0VsY29tZTEyMzQ1IyM=' \
--data '{
"config":[
"extract IEXTTPC",
"useridalias CGGATE domain OracleGoldenGate",
"exttrail zz",
"sourcecatalog oggtst1",
"table tpc.categories;",
"table tpc.categories_descriptions;",
"table tpc.customers;",
"table tpc.customers_info;",
"table tpc.customers_lkup;",
"table tpc.next_cust;",
"table tpc.next_order;",
"table tpc.orders;",
"table tpc.orders_products;",
"table tpc.orders_status_history;",
"table tpc.orders_total;",
"table tpc.products;",
"table tpc.products_description;",
"table tpc.prodcts_to_categories;”,
“table blc.totals;"
] 
}'

After running the above cURL command, you will see a message output that says the parameter file passed validity check:

{
“$schema”: “api:standardResponse”,
“links”: [
{
“rel”: “canonical”,
“href”: “https://localhost:16001/services/v2/extracts/IEXTTPC”,
“mediaType”: “application/json”
},
{
“rel”: “self”,
“href”: “https://localhost:16001/services/v2/extracts/IEXTTPC”,
“mediaType”: “application/json”
}
],
“messages”: [
{
“$schema”: “ogg:message”,
“title”: “Parameter file IEXTTPC.prm: Validity check: PASS”,
“code”: “OGG-10183”,
“severity”: “INFO”,
“issued”: “2019-12-10T16:06:36Z”,
“type”: “http://docs.oracle.com/goldengate/c1910/gg-winux/GMESG/oggus.htm#OGG-10183”
}
]
}

As long as you have a successful message on the validity check the parameter file has been updated.  This can be confirmed by going to and look at the parameter file by either the HTML5 web page or by reviewing the parameter file as identified earlier.

The only thing left to do after updating the parameter file is to restart the extract/replicat.  This can be done manually or automated via the REST API call as well.

You should not be able to quickly modify your parameter files on the Oracle GoldenGate Microservices Architecture.

Enjoy!!! 

Please follow and like: