Earlier in 2017 the Oracle A-Team released a Python library that abstracts the ICS REST API to make some management tasks that you may wish to perform easier. For example identifying a set of integrations and activating or deactivating them, or simply importing and exporting them. In this Definitive Tip we will look at the REPL tool and its benefits. The REPL tool can be downloaded here.

Getting setup on Windows at least is a little fiddly as you need as you need to install Python and then depending upon your version of Python update the installer and retrieve a number additional libraries. REPL itself is available here.

Assuming Python 3 is installed the following commands will complete the installation:

python -m pip install -U pip  setuptools
pip install pytz
pip install requests
pip install tabulate
pip install pyreadline

You can finds out more about ensuring Python installer is upoto date here.

Using the REPL Tool

With the tool installed we need to setup the file that will tell the tool which ICS instance(s) are available. This allows us to store multiple instance details. So if you have an ICS pod for development and another for production then both instances can be identified in the file and have short names attributed to them. An example of the file can be seen here:

REPL Config File Example

The only down side is that the password is clear text form, so the file does need to be protected through means of access control. Of course you can modify the Python script to make it a bit more secure.

We can then use the tool eithere in an interactive mode, or to run a script which is a composition of commands. The following screen shot shows the REPL tool showing its help. Then being started in its interactive mode providing our configuiration file  (python repl.py –servers instance.txt).

REPL Command Line illustration

With the interactive mode we can develop the steps needed to complete out task and then copy them into a simple script.

The first step once we have started the REPL tool is to connect to the relevant instance, we can do this using our shorthand names provided in the configuration file provided as shown next.Connecting with REPLThis connection will now remain used until we tell REPL to close the connection, open another or we leave the application. (deliberately or accidentally). It should be noted that the tool at the time of writing if it encounters an error will drop you back to the OS shell if it experiences an error. For those who are used to Windows’ tolerance to case sensitivity may get caught out by Python’s unforgiving nature here. BUT, a small price to pay as we can noex combine the operations and entities recognised by REPL with pure Python.

To illustrate how REPL can make things very easy we can issue commands like list_integrations or list_connections and get resoluts as follows:

List_integrations with REPL

Not only has it got the ICS integration, descriptive name but also the status, date changed etc.  We can build on this sort of capability. As long as understand the entity and attribute we can select specific groups of integrations. For example the object relating to integrations is called iar – to remember it is also the filke extension of an exported integration). In the following image, we have mixed the select_integrations function REPL provides us with the Integrations entity and pure Python to locate the integrations that have been used for our Definitive Guide articles.

Select integrations with REPL usinfg an expression

Note, there maybe possibly be a bug in REPL, where the select_integrations won’t work until you have used the list_integrations to seed the local cache of entities, atleast in the interactive mode.

This selected set will remain our selection of integrations until we select a new set, or iuse the clear_selection operation. Which means we can issue instructions for the same set. For example we could just list the selection (list_selection) as shown in the previous example.

More meaningful actions would be to for example export the selected Integrations, which is what we have done in the next screen shot. Currently the export function requires that the target folder not exist before the command is executed. But as you can see in the screenshot we can see a nee folder with the relevant .iar files.

Using REPL to export a selection of integrations

We can then of course convert this into a script as follows:

connect ICS1
list_integrations
select_integrations "DG" in iar.name
export_selection e:\ORACLE\ICSREPL\export\

Then run it adding the -f parameter as shown next:

Running REPL in script mode

The outcome is the same as when we run the commands interactively as the tool steps through each line at a time. As you can see here:

REPL output in script mode part 1
REPL output in script mode part 2

Command List

  • list_available_servers – lists the servers in your configuration files
  • Connect
  • list_integrations
  • list_connections
  • select_integrations {optional Python expression}
  • select_connections {optional Python expression}
  • clear_selection
  • activate_selection
  • dump_integration_json {target file}
  • dump_connection_json {target file}
  • export_selection {target directory for output}
  • import_dir {source Directory}
  • update_connection {connection Id} {propertypairs}
  • update_connection_security {connection Id} {securitytype} {propertypairs}

Entities

Currently the only additional entity is the iar object. This represents all the entities in each integration, you can see the definition of the attributes available by using the dump_integration_json command.

Additional Resources