Export/Import Promotion Rules

The exportpromotionrule and importpromotionrule utilities enable you to perform mass updates of promotion rules where you can add or update a promotion rule in large numbers of existing promotion rules by using the following utilities:

• exportpromotionrule

• importpromotionrule

After you export the promotion rule using the exportpromotionrule utility, an output file is created. You can update or add the promotion rules to the output file, as described in Promotion Rules Output File. You can then import the promotion rules into Control-M/EM, using the importpromotionrule utility.

Once you have successfully imported your promotion rules, it is best to validate the changes and ensure that there are no errors.

exportpromotionrule

The exportpromotionrule utility enables you to do the following:

• Export promotion rules and perform a mass update of multiple promotion rules, where you can add or update a promotion rule for a large number of existing promotion rules, and import them into Control-M.

• When adding a new rule, add the rule in the Tools section in Control-M client, as described in Promotion Rules. This serves as a template in which you export using this utility.

• Export one or more promotion rules from one environment to another, between two environments on different Control-M/Enterprise Managers. In this case, you may want to make small changes to the rules before importing them into the destination environment. For example, some values might change between a test environment and a production environment.

Running the exportpromotion Utility

This procedure describes how to run the exportpromotionrule utility, which enables you to export promotion rules that are defined in Control-M .

Before You Begin

Create an arguments file, which contains the arguments that export the promotion rules from the Control-M/EM database.

Begin

1. Do one of the following:

   • UNIX: Log in to a Control-M/EM account.

   • Windows: Open a command prompt window where Control-M/EM is installed.

     For Windows client installations, open a command prompt window and navigate to the <EM Instance Name>\bin directory.

2. Type one of the following commands:

   • emdef exportpromotionrule [-u <user> [-p <password>] | -pf <password file>] -s <GUI Server Name> -arg <args file name> -out <file name> [-vv 2]

   • emdef exportpromotionrule [-USERNAME <user> [-PASSWORD <password>] | -PASSWORD_FILE <password file>] -HOST <GUI Server Name> -ARG_FILE <args file name> -OUT_FILE <file name> [-vv 2]

For more details about the exportpromotionrule parameters, see Export/Import Promotion Rule Parameters.

exportpromotionrule Arguments File Rules

The following rules apply to the exportpromotionrule arguments file:

• More than one promotion rule can be specified in an exportpromotionrule file.

• The arguments file is case-sensitive.

• All parameter values must be enclosed in " (quotation marks).

  JOBNAME="Job1"

• More than one PARAM parameter can be used in a TERM statement.

• The relationship between PARAM parameters in a TERM statement is AND.

• The exportpromotionrule arguments file is checked and processed. If there are any errors, a message is displayed specifying the lines with the errors. The exported promotion rules are saved to the output file that is specified in the -out<file name> parameter.

The exportpromotionrule utility validates the XML rule file according to the validation process in Control-M/EM, versions 9.0.19 and higher.

For an example of the two validation processes see emdef Validation Service Error Message Example.

exportpromotionrule Arguments File Parameters

The following table describes the exportpromotionrule arguments file parameters.

Promotion Rules Output File

After you run the exportpromotionrule utility, an output file is created in the destination you have specified in the utility command. The output file is an XML file, that contains the extracted Promotion Rules data. This file has a specific structure that must be adhered to, or else import fails.

Consider the following when making changes to the output file:

• When creating a new rule that you want to apply to multiple promotion rules, it is recommended that you add the promotion rule in the Tools section, as described in Promotion Rules. This serves as a template in which you export using the utility. You can then copy the rule to the promotion rules output file which you have exported. This ensures that you have the right structure of the rule, and prevents errors.

• After exporting the promotion rule, check the SourceName and TargetName to ensure they are correct. The SourceName and TargetName cannot exceed 100 characters.

• The description must not exceed 4,000 characters.

Update the Application Field: Output File

You must create a promotion rule to update the Application field to 123 from the source environment ENV1 to the target environment ENV2.

After running the exportpromotionrule utility, the following output file is generated:

  <PromotionEnvItem>
    <SourceName>ENV1</SourceName>
    <TargetName>ENV2</TargetName>
    <Name>ENV1-TO-ENV2</Name>
    <Description>env1 to env 2 rule updates Application field to be '123'</Description>
    <PromotionRule>
      <UpdateRows>
        <FindAndUpdateItem>
          <Type>Update</Type>
          <IsParent>false</IsParent>
          <Children/>
          <Operator>
            <OperatorName>Like</OperatorName>
            <OperatorValue>Like</OperatorValue>
            <OperatorEnumValue>LikeOperator</OperatorEnumValue>
          </Operator>
          <IsVisible>true</IsVisible>
          <IsChildrenVisible>true</IsChildrenVisible>
          <LegacyId>F_Application</LegacyId>
          <Level>0</Level>
          <IsSelected>true</IsSelected>
          <UpdateValue>123</UpdateValue>
          <Command>
            <OperatorName>assign</OperatorName>
            <OperatorEnumValue>AssignCommand</OperatorEnumValue>
          </Command>
          <UpdateOperator>
            <OperatorName>Update</OperatorName>
            <OperatorEnumValue>UpdateAction</OperatorEnumValue>
          </UpdateOperator>
        </FindAndUpdateItem>
      </UpdateRows>
      <CanMoveUpdateItemUp>false</CanMoveUpdateItemUp>
      <CanMoveUpdateItemDown>false</CanMoveUpdateItemDown>
    </PromotionRule>
  </PromotionEnvItem>

Update the Description Field: Output File

You must create a promotion rule that updates the Description field to Nightly job from source environment ENV1 to the target environment ENV3.

After running the exportpromotionrule utility, the following output file is generated:

<PromotionEnvItem>
    <SourceName>ENV1</SourceName>
    <TargetName>ENV3</TargetName>
    <Name>ENV1-TO-ENV3</Name>
    <Description>env1 to env 3 rule updates Description field to be 'Nightly Job'</Description>
    <PromotionRule>
      <UpdateRows>
        <FindAndUpdateItem>
          <Type>Update</Type>
          <IsParent>false</IsParent>
          <Children/>
          <Operator>
            <OperatorName>Like</OperatorName>
            <OperatorValue>Like</OperatorValue>
            <OperatorEnumValue>LikeOperator</OperatorEnumValue>
          </Operator>
          <IsVisible>true</IsVisible>
          <IsChildrenVisible>true</IsChildrenVisible>
          <LegacyId>F_Description</LegacyId>
          <Level>0</Level>
          <IsSelected>true</IsSelected>
          <UpdateValue>Nightly Job</UpdateValue>
          <Command>
            <OperatorName>assign</OperatorName>
            <OperatorEnumValue>AssignCommand</OperatorEnumValue>
          </Command>
          <UpdateOperator>
            <OperatorName>Update</OperatorName>
            <OperatorEnumValue>UpdateAction</OperatorEnumValue>
          </UpdateOperator>
        </FindAndUpdateItem>
      </UpdateRows>
      <CanMoveUpdateItemUp>false</CanMoveUpdateItemUp>
      <CanMoveUpdateItemDown>false</CanMoveUpdateItemDown>
    </PromotionRule>
  </PromotionEnvItem>

Update the Run as User Field and Set the Priority to High - Output File

In the following example, you must create two Promotion Rules from source environment ENV4 to target environment ENV2:

• Update the Run as User field to adminuser.

• Set the Priority to High.

After running the exportpromotionrule utility, the following output file is generated:

<PromotionEnvItem>
    <SourceName>ENV4</SourceName>
    <TargetName>ENV2</TargetName>
    <Name>ENV4-TO-ENV2</Name>
    <Description>env4 to env 2 rule updates 2 field: 1. Run As to be 'adminuser'. 2. Priority to 'High'</Description>
    <PromotionRule>
      <UpdateRows>
        <FindAndUpdateItem>
          <Type>Update</Type>
          <IsParent>false</IsParent>
          <Children/>
          <Operator>
            <OperatorName>Like</OperatorName>
            <OperatorValue>Like</OperatorValue>
            <OperatorEnumValue>LikeOperator</OperatorEnumValue>
          </Operator>
          <IsVisible>true</IsVisible>
          <IsChildrenVisible>true</IsChildrenVisible>
          <LegacyId>F_Owner</LegacyId>
          <Level>0</Level>
          <IsSelected>false</IsSelected>
          <UpdateValue>adminuser</UpdateValue>
          <Command>
            <OperatorName>assign</OperatorName>
            <OperatorEnumValue>AssignCommand</OperatorEnumValue>
          </Command>
          <UpdateOperator>
            <OperatorName>Update</OperatorName>
            <OperatorEnumValue>UpdateAction</OperatorEnumValue>
          </UpdateOperator>
        </FindAndUpdateItem>
        <FindAndUpdateItem>
          <Type>Update</Type>
          <IsParent>false</IsParent>
          <Children/>
          <Operator>
            <OperatorName>Like</OperatorName>
            <OperatorValue>Like</OperatorValue>
            <OperatorEnumValue>LikeOperator</OperatorEnumValue>
          </Operator>
          <IsVisible>true</IsVisible>
          <IsChildrenVisible>true</IsChildrenVisible>
          <LegacyId>F_Priority</LegacyId>
          <Level>0</Level>
          <IsSelected>true</IsSelected>
          <UpdateValue>High</UpdateValue>
          <Command>
            <OperatorName>assign</OperatorName>
            <OperatorEnumValue>AssignCommand</OperatorEnumValue>
          </Command>
          <UpdateOperator>
            <OperatorName>Update</OperatorName>
            <OperatorEnumValue>UpdateAction</OperatorEnumValue>
          </UpdateOperator>
        </FindAndUpdateItem>
      </UpdateRows>
      <CanMoveUpdateItemUp>true</CanMoveUpdateItemUp>
      <CanMoveUpdateItemDown>false</CanMoveUpdateItemDown>
    </PromotionRule>
  </PromotionEnvItem>

importpromotionrule

The importpromotionrule utility enables you to do the following:

• Perform a mass update on multiple promotion rules (after running the exportsitestandards utility) where you can add or update a promotion rule in a large number of existing promotion rules, and import them into Control-M.

• Import one or multiple promotion rules from one environment to another, between two environments on different Control-M/Enterprise Managers. If you import promotion rules that already exist in the database, you can use the overwrite flag (/o) in the utility command, which replaces existing promotion rules. If you do not use the overwrite flag, promotion rules are not imported and a message is issued informing you that promotion rules already exist.

Before using the importpromotionrule utility, note the following:

• The Source/Target name must be defined in the Environment Name field in the Promotion Rules tab in Control-M.

• Only one rule for each Source and Target combination is permitted. If the file contains two rules with the same Source and Target, an error message is issued when importing the rule.

The importpromotionrule utility validates the XML rule file according to the validation process in Control-M/EM, versions 9.0.19 and higher.

To run the utility, see Running the importpromotionrule Utility.

Running the importpromotionrule Utility

This procedure describes how to run the importpromotionrule utility, which enables you to import specified promotion rule values in the Control-M/EM database.

Begin

1. Do one of the following:

   • UNIX: Log in to a Control-M/EM account.

   • Windows: Open a command prompt window where Control-M/EM is installed.

     For Windows client installations, open a command prompt window and navigate to the <EM Instance Name>\bin directory.

2. Type one of the following commands:

   • emdef importpromotionrule [-u <user> [-p <password>] | -pf <password file>] -s <GUI Server Name> -src <data file name> [/o] [-vv 2]
   • emdef importpromotionrule [-USERNAME <user> [-PASSWORD <password>] | -PASSWORD_FILE <password file>] -HOST <GUI Server Name> -SRC_FILE <data file name> [/o] [-vv 2]

Export/Import Promotion Rule Parameters

The following table describes the parameters for exportpromotionrule and importpromotionrule utilities.