The REPL tool was built against ICS running on OCI Classic. As this is no longer available the tool has been withdrawn

Oracle A Team

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 to install Python and then depending upon your version of Python update the installer and retrieve a number of 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 find out more about ensuring the Python installer is up to date here.

Using the REPL Tool

With the tool installed, we need to set up 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 downside 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 either in an interactive mode, or to run a script that is a composition of commands. The following screenshot shows the REPL tool showing its help. Then being started in its interactive mode providing our configuration file  (python repl.py –servers instance.txt).

REPL Command Line illustration

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

Connecting with REPL

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. This connection will now remain used until we tell REPL to close the connection, open another or 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. 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 results 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 file 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 may be 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, at least in the interactive mode.

This selected set will remain our selection of integrations until we select a new set, or use 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 screenshot. 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 new 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 2

REPL output in script mode part 1…

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

Related Posts