C Using emctl partool Utility

This appendix introduces you to the emctl partool utility and explains how you can use it to perform critical tasks such as exporting Deployment Procedures as PAR files, importing PAR files, and so on. In particular, this appendix covers the following:

Note:

Provisioning Archive Files that were exported from any Enterprise Manager version prior to 12c can not be imported into Enterprise Manager 12c.

C.1 Overview of Provisioning Archive Files

Provisioning Archive (PAR) files are archive files that contain a collection, or bundle of Deployment Procedures and Software Library entities that are used in numerous Lifecycle Management tasks like Provisioning and Patching applications.

In case of a Deployment Procedures, partool exports only the User-defined procedures, and not the Oracle-owned procedures. While exporting the User-defined procedure, the complete deployment procedure is not exported, only the customization (delta changes) are exported.

Also, note that in case of upgrade all the procedures that were created pre-12c can not be exported using the partool export utility.

Note:

For importing PAR files that contain Software Library entities, ensure that your Software Library is configured. For information on Configuring Software Library, see Oracle Enterprise Manager Cloud Control Administrator's Guide.

C.2 Overview of emctl partool Utility

Over a period of time, you might have customized some Deployment Procedures, and you might want to reuse them in another instance of Cloud Control. Under such circumstances, you might want to export the customized Deployment Procedures from one instance of Cloud Control, and deploy them to another instance of Cloud Control.

emctl partool utility is a tool offered by Cloud Control that helps you perform these functions using the command line interface. Essentially, emctl partool utility helps you:

Export Deployment Procedures and its associated components and directives as PAR files
Import PAR files to the same instance or any other instance of Cloud Control

The emctl partool utility is located in the $ORACLE_HOME/bin directory.

The following is the usage information displayed when you run $ORACLE_HOME/bin/emctl partool:

emctl partool <deploy|view> -parFile <file> -force(optional)
emctl partool <deploy|view> -parFile <file> -force(optional) -ssPasswd <password>
emctl partool <deploy|view> -parDir <dir> -force(optional)
emctl partool export -guid <procedure guid> -file <file>    -displayName <name> -description <desc> -metadataOnly(optional)
emctl partool check
emctl partool help

Table C-1 describes the additional options that can be used with the emctl partool utility.

Table C-1 emctl partool Options

Option	Description
-repPasswd <repPassword>	Indicates the repository password. User will be prompted for the repository password if -repPasswd is not specified on the command line. Note: Providing a password on the command line is insecure and should be avoided in a production environment.
-force	Forces the Software Library entities to be created or uploaded again. If already present, it creates a new revision.
check	Checks whether the Software Library is configured.
-file <file>	Represents the PAR file.
-action <deploy\|view\|export>	Deploys, views, or exports PAR files.
-verbose	Indicates verbose mode.
help	Displays Help information.
-displayName <displayName>	Indicates PAR file name.
-parDir <dir>	Directory where the PAR files are located.
-metadataOnly	Flag for metadata-only exports.
-guid <guid>	Procedure GUID to export. To export multiple procedures, provide the GUIDs separated by ","
-parFile <file>	Path to the PAR file.
-description <description>	PAR file description.
-ssPasswd <secretStorePassword>	This is optional. If used with -action export; if any of the exported Software Library entity contains a secret property, an Oracle Wallet is created to store the value of the secret property. Oracle Wallet is created using the specified password. You are prompted to enter a password if -ssPasswd switch is used and if password is not supplied as a command line argument. You must use the same password while importing the PAR file in a new repository. If used with -action <deploy\|view>; if the PAR file contains any password protected Oracle Wallet (that stores an entity's secret property values), then this parameter is required to open the store. You are prompted to enter a password if -ssPasswd switch is used and password is not specified as a command line argument.

C.3 Checking Oracle Software Library

Before running the emctl partool utility to export or import PAR files, ensure that the $ORACLE_HOME environment variable is set to the Oracle home directory of Oracle Management Service (OMS) and a Software Library path is configured.

To check the Software Library, run the following command:

$ORACLE_HOME/bin/emctl partool check

C.4 Exporting Deployment Procedures

To export Deployment Procedures, you must first obtain the GUID of those Deployment Procedures, and then run the emctl partool utility to create a PAR file. This section explains the following:

C.4.1 Obtaining Deployment Procedure's GUID

To obtain the GUID of a Deployment Procedure using Cloud Control, follow these steps:

In Cloud Control, from the Enterprise menu select Provisioning and Patching, and then click Procedure Library.
On the Provisioning page, right click the deployment procedure name and from the menu select Copy Link Location.
Paste the copy the link to a notepad, and then search for guid.

For example: https://adc2171248.us.example.com:14500/em/console/paf/procedureView?guid=B3B4B6C76AE46A67E040E50A65751782

The GUID is B3B4B6C76AE46A67E040E50A65751782

Alternately you can use the following EMCLI command to retrieve the GUID of the procedure:

emcli get_procedures [-type={procedure type}] [-parent_proc={procedure associate with procedure configuration}]

Example:
emcli get_procedures -type=DemoNG -parent_proc=ComputeStepTest

Output Column: 
GUID, Procedure type, name, display name, version, Parent procedure name

Note:

For information about setting up EMCLI, see Oracle Enterprise Manager Command Line Interface Guide.

C.4.2 Creating PAR File

To create a PAR file that contains one or more Deployment Procedures, run the emctl partool utility with the export option as the action, and quote the GUIDs of the Deployment Procedures you want to export. Ensure that you separate the GUIDs by a comma.

$ORACLE_HOME/bin/emctl partool export -guid <GUID> -file exportedDP.par -displayName "User exported DP" -description "<description>"

For example, if the GUID of the Deployment Procedure that you want to export is FAC05DD31E3791C3E030579D23106C67, then run the following command:

$ORACLE_HOME/bin/emctl partool export -guid FAC05DD31E3791C3E030579D23106C67 -file exportedDP.par -displayName "User exported DP" -description "Deployment Procedure to be copied to other OMS"

After you run this command, a new PAR file named exportedDP.par is created in the directory where you ran the command. You can then import this PAR file to the same instance of Cloud Control or another instance, multiple times.

To export multiple deployment procedures, separate the GUIDs with commas as follows:

$ORACLE_HOME/bin/emctl partool export -guid "06B62B6ED5DA20BCE040578C850862A7,0C96E96D9818BC5FE040578C8508620F,09AEFF331025AAD0EE40578C85FB5772" -file $ENV{T_WORK}/tvmgf_partool_multi_dp.par -displayName "partool multi dp test" -description "partool multi dp test description" -repPasswd sysman

Note:

When a procedure is exported using emctl partool, any directives or components referred by the procedure are also exported. However, only the latest revision of these directives or components will be exported. If you do not want to export components or directives, you can specify the -metadataOnly flag when running emctl partool.

C.5 Importing PAR Files

You can import PAR files using the command line interface or the graphical user interface offered by Cloud Control, that is, the console. This section explains the following:

Note:

Importing an existing PAR file (from the previous releases) into Enterprise Manager Cloud Control 12c is not supported. For example, you cannot import a Enterprise Manager 11g Grid Control Release 1 (11.1.0.0) to Enterprise Manager Cloud Control 12c.

C.5.1 Importing Using Command Line Interface

This section covers the following:

C.5.1.1 Importing Specific PAR File

To import or deploy a specific PAR file, run the following command:

$ORACLE_HOME/bin/emctl partool deploy -parFile $ORACLE_HOME/sysman/prov/paf/<par_file_name>

For example:

$ORACLE_HOME/bin/emctl partool deploy -parFile $ORACLE_HOME/sysman/prov/paf/asprov.par

Note:

If Software Library or the procedure already exists in Enterprise Manager and you want to create a new revision of the PAR file, then you can use the -force attribute as follows:

$ORACLE_HOME/bin/emctl partool deploy -parFile $ORACLE_HOME/sysman/prov/paf/asprov.par -force
If you have multiple OMSes in your environment, then you need to run the emctl partool utility only once to deploy any PAR files or to perform other related operations.

While importing PAR files if the user procedure already exists in the setup, then it will always import this procedure with revised (bumped up) version.

C.5.1.2 Importing All PAR Files

To import or deploy all the PAR files in a directory, run the following command:

$ORACLE_HOME/bin/emctl partool deploy -parDir $ORACLE_HOME/sysman/prov/paf/ -force

C.5.2 Importing Using Cloud Control Console

To import PAR files or deploy them to an OMS, you can use the emctl partool utility. Alternatively, you can import then from Cloud Control .

For importing the PAR files, follow these steps:

In Cloud Control, from the Enterprise menu select Provisioning and Patching, and then click Procedure Library.
On the Deployment Procedure Manager page, select the procedure, and from the drop down menu select Import, and then click Go.
On the Upload Procedure File page, select:
- Upload from Local Machine to upload the PAR file from the local machine. Click Browse to select the PAR file. Click Import to import the file.
- Upload from Management Agent Machine to select the Management Agent target. Enter the Normal or Privileged Host Credential details to access the Management Agent machine where the file is present, and then click Import to import the file.