In a previous blog I talked about the emdef utility and how it can help to manage and standardize calendars across multiple environments. In this blog we will deal with folders definitions in the Control-M/EM database. This can be used to extract data as a backup, or for migration from one to another environment.

The emdef need some parameters which vary according to the method to be executed, methods related to folders are:

  • exportdeffolder: Exports folders and SMART Folders
  • deffolder: Imports folders and SMART Folders
  • updatedef: Updates specified parameter

Basic parameters definition

Basic parameters not change between calendars and folders method, so to run emdef there are some fixed parameters whatever the method used, the syntax should be like:

emdef <METHOD_TO_USE> [-USERNAME <userName> [-PASSWORD <password>] | -PASSWORD_FILE <passwordFile>] -HOST <guiServerName> ...
  • userName: The Control-M/EM user name
  • password: The control-M/EM user password
  • passwordFile: Here you have the choice to put the user and password in the command line, or use the passwordFile which is a file containing an unencrypted user name and password on separate lines in the below format:
    user=userName
    password=password

    I personally recommend this practice to avoid adding user/password in the command line, on the other hand you have to correctly set file permissions!

  • guiServerName: Control-M/EM GUI server host name or IP address

Let’s move to methods to better understand this utility.

Methods definition

exportdeffolder

The exportdeffolder utility exports folders from the Control-M/EM database to a file. To do so, a file of arguments should be prepared and contains statements that specify an existing folder, SMART Folders and Sub-folders. The specified folders are exported to an output file. Then, output files created with the exportdeffolder utility can be used as import files with the deffolder utility.

For example, on DEV you can define, test, and validate jobs configuration, then export job definitions to an output file using exportdeffolder, make modifications (needed on TEST Env) to the definitions, and use the file modified as the input file when running deffolder on Test environment. In this way, you can be sure that jobs are identical between DEV and TEST environments.

To run the exportdeffolder utility, you need to specify basic parameters shown before plus the below one:

-arg <argFileName> -out <outputFileName>

=> Path and name of the arguments file containing the exportdeffolder specifications, and the output file you want.
Example: Export all folders configuration with name match DEV*

  1. Create an argument file “exportALLdevfolder.xml” like the following:
    <TERMS>
      <TERM>
        <PARAM NAME="FOLDER_NAME" OP="LIKE" VALUE="DEV*"/>
      </TERM>
    </TERMS>
    
  2. Create password file credentials.txt:
    user=emuser
    password=MyEmUserPass
    
  3. Execute the command:
    emdef exportdeffolder -pf <passwordFile> -s <guiServerName> -arg <argFileName> -out <outputFileName>

    Which correspond to:

    emdef exportdeffolder -pf credentials.txt -s guiserverhostname -arg exportALLdevfolder.xml -out AllDevFolders.xml 

deffolder

The deffolder utility imports folders and SMART Folders into the Control-M/EM database. The input file is usually a file generated from exportdeffolder or from the gui, anyway it should contains statements that specify an existing folders or new folders (valid for SMART Folders).
So, if the folders don’t exist, the utility creates them. If the folders already exist, a message is issued indicating that the folders already exist, there is a way to overwrite the existing folders.

To run the deffolder utility, you need to specify basic parameters shown before plus the below one:

-src <srcFileName> [/a] [/o] [/t] [/v]

=> -src: to specify the imput xml file that contains the folders definitions
=> /a: directs the utility to automatically reset the “Created By” parameter to the current Control-M/EM user when these two values do not match – OPTIONAL
=> /o: directs the utility to overwrite any existing folders – OPTIONAL
=> /t: Operate on a single folder at a time, to reduce process memory – OPTIONAL
=> /v: Used to receive verbose messages – OPTIONAL

Example: Import folders configuration that has been exported in the previous method

  1. Use the same file credentials.txt created before
  2. Execute the command:
    emdef deffolder -pf <passwordFile> -s <guiServerName> -src <srcFileName>  [/a] [/o] [/t] [/v]

    Which correspond to:

    emdef deffolder -pf credentials.txt -s guiserverhostname -src AllDevFolders.xml /o

updatedef

The updatedef utility updates specified parameter values in the in the Control-M/EM database, e.g.:
– Folder definitions
– SMART Folder definitions
– Sub-folder definitions

To run the updatedef utility, you need to specify basic parameters shown before plus the below one:

-arg <argFileName> [/a]

=> -arg : arguments file containing updatedef specifications. The syntax of this xml file is not complex but contain a lot of cases so don’t hesitate to ask if you have any question!
=> [/a]: directs the utility to automatically reset the “Created By” parameter to the current Control-M/EM user when these two values do not match – OPTIONAL

Example: Modify the Job name of a jobs in APPLICATION_1 and datacenter DC_0:

  1. Create an argument file “UpdateJobs.xml” like the following:
    <UPDATE>
    	<JOB>
    		<FOLDER_NAME FROM="APPLICATION_1"/>
    			<DATACENTER FROM="DC_0"/>
    			<JOBNAME FROM="src*" TO="dbi*"/>
    ...
  2. Use the same file credentials.txt created before
  3. Execute the command:
    emdef updatedef -pf <passwordFile> -s <guiServerName> -arg <argFileName> [/a]

    Which correspond to:

    emdef updatedef -pf credentials.txt -s guiserverhostname -arg UpdateJobs.xml

Now you are able to manage folders and calendars using emdef utility, this tool will help you to easily and automatically export, migrate, make bulk update on Control-M definitions.