Running ObjectManager commands

Run ObjectManager commands to import and export configuration data.
Note: If you're using IBM OpenPages® as a Service or Watsonx.governance as a Service, see IBM OpenPages CLI (ibmcloud openpages). In these deployment types, you use the ibmcloud openpages CLI to run ObjectManager commands.

The ObjectManager command file is named ObjectManager.cmd on computers running a Microsoft Windows operating system. The command file is named ObjectManager.sh on computers running a Linux® operating system.

ObjectManager commands use the following syntax:
ObjectManager.sh|.cmd <command> config|c <authentication> [parameters]

The ObjectManager command line must be:

  • Run from the bin directory.
  • Typed on a single line (no line breaks) in a command window.
Important: When using the ObjectManager tool, make sure that the OpenPages services are running.

ObjectManager command-line parameters

You can use various commands and parameters with the ObjectManager tool.

<command>
Required.
Value can be one of the following commands:
  • dump or d: Dumps (exports) data.
  • load or l: Loads (imports) data from a single loader file.
  • validate or v: Validates and verifies the data in a loader file.
  • batch or b: Runs ObjectManager in batch processing mode. Use batch mode to load multiple loader files in a single session. For more information, see Batch loader file syntax.
<authentication>
The authentication method that you need to use depends on the deployment type that you are using.
IBM OpenPages on Cloud and IBM OpenPages on premises
Use <user> and <password>.

Both parameters are required. Use your user ID and your password.

Some actions require a Super Administrator account.

IBM® Software Hub
Use one of the following combinations:
  • jwt and a IBM Software Hub JSON Web Token (JWT)
  • Your IBM Software Hub username and your IBM Software Hub API key

    You generate the API Key in IBM Software Hub. For more information, see Generating API keys for authentication..

To see examples of using these parameters, see Load command syntax.

Watsonx.governance as a Service on AWS
Use apikey <apikey>.

Replace <apikey> with your API key.

You generate API keys in the IBM SaaS Console. For more information, see Creating API keys

<loader-file-path>
Optional.

The file path to a single XML loader file.

The current directory is used if no file path is specified.

The ObjectManager.log file is written to this directory.

<loader-file-prefix>
Optional.

The user-defined portion of the loader file name.

By default, the ObjectManager tool attempts to load from or write to the file op-config.xml, if no prefix is specified.

<batch-loader-dir>
Required when you are using batch mode.

The file path to the XML loader files that are listed in the <batch-loader-list-file>. You can use a parent directory if loader files are in multiple subdirectories under that directory.

<batch-loader-list-file>
Required when you are using batch mode.

The fully qualified file path and name of a text document that contains a list of loader files for batch processing.

Load command syntax

This Windows-based example shows how to use a loader file that is named data1-op-config.xml that resides in the c:\import folder to import data into IBM OpenPages.

Procedure

  1. Open a Command Prompt window.
  2. Put the loader file, data1-op-config.xml, in the c:\import directory.
  3. Go to the \bin directory.
    For example c:\openpages-tools-client\bin
  4. Run the following command on a single line to load the data1-op-config.xml loader file: 
    ObjectManager.cmd l c <authentication> c:\import data1

    The log file is c:\import\ObjectManager.log.

    For example:
    IBM OpenPages on premises or IBM OpenPages on Cloud
    In this example, the ComplianceOfficer account is used for authentication. The command loads the c:\import\data1-op-config.xml file.
    ObjectManager.cmd l c ComplianceOfficer <password> c:\import data1
    IBM OpenPages on IBM Software Hub
    Use one of the following commands:
    • This example uses a IBM Software Hub JSON Web Token (JWT) to authenticate. 
      ObjectManager.cmd l c jwt <JSON-Web-Token> c:\import data1
    • This example uses a IBM Software Hub username, ComplianceOfficer, and an API key to authenticate. 
      ObjectManager.cmd l c ComplianceOfficer <API-Key> c:\import data1
    Watsonx.governance as a Service on AWS
    Use apikey <apikey>.
    ObjectManager.cmd l c apikey <API-Key> c:\import data1
    Replace <apikey> with your API key.

Dump command syntax

This Windows-based example shows how to export data to a file that is called config1-op-config.xml prefix that resides in the c:\export folder. If the folder does not already exist, the ObjectManager tool creates it.

Procedure

  1. Open a Command Prompt window.
  2. Go to the \bin directory.
    For example c:\openpages-tools-client\bin
  3. Update the objectmanager.properties file to configure the items to export.
  4. Run the following command on a single line to export data to c:\export\config1-op-config.xml: 
    ObjectManager.cmd d c <authentication> c:\export config1

    The file named config1-op-config.xml is created in the c:\export folder.

    For example:
    IBM OpenPages on premises or IBM OpenPages on Cloud
    In this example, the ComplianceOfficer account is used for authentication. The command loads the c:\import\data1-op-config.xml file.
    ObjectManager.cmd d c ComplianceOfficer <password> c:\export config1
    IBM OpenPages for IBM Cloud Pak for Data
    Use one of the following commands:
    • This example uses a Cloud Pak for Data JSON Web Token (JWT) to authenticate. 
      ObjectManager.cmd d c jwt <JSON-Web-Token> c:\export config1
    • This example uses a Cloud Pak for Data username, ComplianceOfficer, and an API key to authenticate. 
      ObjectManager.cmd d c ComplianceOfficer <API-Key> c:\export config1
    Watsonx.governance as a Service on AWS
    Use apikey <apikey>.
    ObjectManager.cmd d c apikey <API-Key> c:\export config1
    Replace <apikey> with your API key.

Batch loader file syntax

A batch loader list file is typically a text (.txt) file that contains a list of the XML loader files for batch processing by the ObjectManager tool.

The ObjectManager tool uses the following syntax for batch loading multiple loader files.
ObjectManager batch|b config|c <authentication> <batch-loader-dir> <batch-loader-list-file>
Where:
  • <batch-loader-dir> is the full path to the directory that contains the loader files. The loader files can be in sub directories under the <batch-loader-dir>.
  • <batch-loader-list-file> is the full path and filename of the batch loader list file. This file is typically a .txt file
A batch loader list file uses the following rules:
  • Any line starting with a number sign (#) is considered a comment.
  • Any line starting with greater than sign (>) is written to the screen for display.
  • All other lines are assumed to be the relative path to a loader file.
The following sample batch loader list file was created in a text editor. This example shows how to load files from a directory and a subdirectory. 
# If the <batch-loader-dir> was given as 
# c:\temp\myfiles, the following lines would
# write the "Loading…" message and then attempt to load the file
# c:\temp\myfiles\sample-add-user-op-config.xml 
> Loading example 1…
sample-add-user

# The following lines would write the "Loading…" message and then attempt 
# to load the files:
# c:\temp\loaders\samplefxrates-op-config 
# c:\temp\loaders\samplecurrencyfield-op-config 
# c:\temp\loaders\samplecurrencies-op-config 
> Loading examples 2-4…
loaders\samplecurrencyfield
loaders\samplecurrencies
loaders\samplefxrates

The sample file also shows how you can display an informational loading message (line starting with >) on the screen.

For this example, name the file my_loader_list.txt and save it in the c:\sample_batch\ directory.

The following steps show how to run the sample my_loader_list.txt file to load or import data.
  • The <batch-loader-dir> is c:\temp\myfiles. The \myfiles directory is used for the <batch-loader-dir> parameter because it includes the sample-add-user-op-config.xml and the \loaders subdirectory, which contains the other files to load.
  • The <batch-loader-list-file> is the full path and name of the batch loader list file. For this example,the path is c:\sample_batch\my_loader_list.txt.

Procedure

  1. Open a Command Prompt window.
  2. Go to the \bin directory.
    For example c:\openpages-tools-client\bin
  3. Run the following batch command to load the load-reports.txt batch loader list file:
    Replace <authentication> with the values for your environment. For more information, see ObjectManager command-line parameters.
    ObjectManager.cmd b c <authentication>  c:\temp\myfiles c:\sample_batch\my_loader_list.txt