Resolving the mapping file

The mapping file produced by the export process of a workload application contains a list of elements, some of which are dependent on the topology of the environment in which it is used. These elements need to be customized to reflect the target environment.

To use the workload application in a new environment, modify the mapping file to reflect the destination environment using the information provided in the reference file and then perform an import operation. The import operation is performed passing the mapping file and the definition file as input to the wappman command.

The wappman command can be used to import, export, replace, list, display, and delete a workload application. See wappman for the complete command line usage and syntax to perform these actions on a workload application and any special considerations to be aware of.

During the export process, the objects contained in the workload application are extracted to the definitions file with the same definition they have in the source environment. The definitions file can contain a complete object definition or in some cases, only a name or reference to the object that is extracted. Simple references and not a full object definition is extracted for those objects that require to be mapped to an object already present in the target environment. For some objects extracted by reference, the object definition is written to the mapping file which requires a customization to map the objects in the HCL Workload Automation source environment to the environment where the workload application will be deployed.

The mapping file can be viewed and edited with a text editor. It is organized in sections and contains comments to assist you in assigning the correct values to the elements.

As an alternative, when the import process is performed from the wappman command line, you can optionally request that the mapping file is automatically modified according to rules defined using regular expressions and specified in one of the following ad-hoc files:
  • workload applicationname_BasicRegExpMapping.UTF8.rules
  • workload applicationname_AdvancedRegExpMapping.UTF8.rules
These files are produced by the export process and, if used, must be properly customized. For additional details, see Using regular expressions to modify the mapping file.
The following table outlines all of the objects that can be contained in a workload application or that are referenced by another element in the workload application and how the export process manages them.
Table 1. Objects extracted during the export process
Object type What is exported to the definitions file? What requires customization in the mapping file? What happens during the import?
Folder Reference only Folder name. Map the original folder name to either the root, or to an existing folder in the destination environment. The folder is not imported.

A definition is not imported because the folder is already defined in the target environment, however, the folder names need to be mapped.
Job stream Object definition including the job stream start condition, if specified.

Workstation
Job stream name
Job alias
Job stream
start condition,
if specified

 Job stream is created in the database.
Restriction: If the job stream has a dependency on a job stream or job external to the workload application, the mapping file contains a reference to the name of the external job stream or job and the relative workstation definition, however, the definitions file does not contain the job stream or job definition. The name in the mapping file must be mapped to an existing job stream or job in the target environment to successfully import the workload application.
Job Object definition

Workstation
Job name
Affinity
Password variables
  found in the JSDL

Job is created in the database.

If the job has a dependency on a job that is defined in a job stream external to the workload application, the mapping file contains a reference to te following objects: the name of the external job stream, the job defined int he external job stream, the workstation definitions of the job stream, and the workstation definitions of the job. However, the definitions file does not contain the job definition. The name in the mapping file must be mapped to an existing job stream or job in the target environment to successfully import the workload application.

Affinity relationships cause jobs to run on the same workstation. The workstation on which the first job runs is chosen dynamically and the affine job or jobs run on the same workstation. The jobs must belong to the same job stream. When a job with an affinity is exported, the name of the job is added to the mapping file.

Variables in the JSDL use the format ${password:ws#user}. Only workstations are generically represented. The user field is copied as is to the target environment. Variables should be used for user names.
Run cycle variable tables

Job stream variable tables

 Object definition

Table name
Variable name

Variable table is created in the database.

Workstation and default variable tables are extracted by reference and written to the map file.

The value associated to the variable can be modified, but not variable names.

Avoid associating the default variable table to job streams and run cycles.
User Nothing. Neither an object definition nor a reference is made in the reference file.

The user must exist in the target environment.

Variables should be used to refer to users to make the workload application more flexible for reuse.
Calendar Object definition Calendar name Calendar is created in the database
Run cycle Object definition Run cycle name Run cycle is created in the database
Run cycle group Object definition Run cycle group name Run cycle group is created in the database
Internetwork dependencies Referenced job or job stream is not exported since it belongs to a different engine. Name of the network agent workstation that handles the follows dependencies between the local network and the remote network. Internetwork dependency is added to the job or job stream.
External dependencies

The referenced job or job stream is exported only if it belongs to the workload application template.

 If the referenced job or job stream does not belong to the workload application template, assign a name to the job, or job stream that corresponds to a job or job stream that already exists in the target environment. External dependency added to the job or job stream
Resources Object definition

Workstation
Resource name

 Resources are created in the database
Global prompts Object definition Variables used in the definition

Global prompts are created in the database.

Variables can be used. Since they are resolved using the default table, the variable used in a global prompt can be mapped to a variable in the target environment.
Workstations Reference only Name

Not imported.

Workstations are extracted to the definition file as a reference. A definition is not imported because the workstations are already defined in the target environment, however, their names do need to be mapped.
Workstation class Reference only Name

Not imported.

Workstation classes are extracted to the definition file as a reference. A definition is not imported because the workstation classes are already defined in the target environment, however, their names do need to be mapped.
Variable Object definition Value

Imported.

Variables are used in several places in a job stream definition. A reference is added to the definitions file.
Event rules Object definition Name

Event rules are created in the database for the workstations and job streams included in the template.

Note: Any scheduling objects referenced in the Actions and Events defined in the event rule that do not belong to the user's security domain are not imported into the target environment and the import operation fails.

Example

The following are excerpts from some of the files contained in the compressed file, created by the export of the workload application, that are used to ready the files for deployment in the target environment.
Table 2. Resolving the mapping file

Summary for complex table
Definitions file Mapping file Reference information file 
<model:JobStream carryforward=
  "true" draft="false" folder=
   "$FOLDER_/APPS/APP1$/"
 iskey="false" limit="55" name=
  "$JOBSTREAM_BADPBN34_JS1_1I$"
 onrequest="false" priority="100"
 workstation="$WORKSTATION_
  BADPBN34_WC1$">
     <model:runcycles/>
     <model:matching>
       <model:sameDay/>
     </model:matching>
     <model:restrictions/>
     <model:dependencies/>
     <model:jobs>
     <model:job confirmed="false" 
definition=
   "$WORKSTATION_MDM112097$
  #$JOB_BADPBN34_J1$"
 isCritical="false" iskey="false"
  name="$JOB_BADPBN34_J1$" 
priority="10">
       <model:restrictions/>
       <model:dependencies>
        <model:predecessor target=
         "$WORKSTATION_BADPBN34_
         WC1$#$JOBSTREAM_BADPBN34_
         JS2$.@">
          <model:matching>
           <model:previous>
          </model:matching>
       </model:predecessor>
      </model:dependencies>
     </model:job>
    </model:jobs>
</model:JobStream>

#Folder names
#Replace the value with the 
name of a Folder that already
exists in the target environment.
#
FOLDER_/=/
FOLDER_/APPS/APP1=/APPS/APP1
#
#Job stream names
#Job stream names in this 
section refer to job streams
that will be created during
the import process.
#Assign a name for the job 
stream that does not already 
exist in the target environment.
#
JOBSTREAM_BADPBN34_JS1_1I=
  BADPBN34_JS1_1I
#
#Workstation names
#Replace the value with the name
 of a workstation that already 
 exists in target environment
#Refer to the MAIN_TEMPLATE_
  SourceEnv_reference.txt file 
  for details about the 
  workstation.
#
#This workstation is of type 
  Manager
WORKSTATION_MDM112097=MDM112097
#This workstation is of type 
  Agent
WORKSTATION_MDM112097_1=
  MDM112097_1
#This workstation is of type 
  Broker
WORKSTATION_MDM112097_DWB=
  MDM112097_DWB
 
CPUNAME $WORKSTATION_MDM112097$
  DESCRIPTION "Sample master domain 
   manager"
  OS UNIX
  NODE MDM112097.romelab.it.ibm.com 
   TCPADDR 35111
  TIMEZONE Europe/Rome
  DOMAIN MASTERDM
  FOR MAESTRO
    TYPE MDM
    AUTOLINK ON
    BEHINDFIREWALL ON
    FULLSTATUS ON
    SERVER A
END
The reference information file indicates that the workstation named, MDM112097, is of type, master domain manager, running on a UNIX operating system. The definitions file contains references to the name of the workstation so, the entry in the mapping file, WORKSTATION_MDM112097=MDM112097, must be updated. Replace MDM112097 with the name of a workstation that already exists in the target environment, and has the same characteristics as those outlined in the reference information file.

Definitions file<screen><model:JobStream carryforward="true" draft="false" folder="$FOLDER_/APPS/APP1$/" iskey="false" limit="55" iskey="false" limit="55" name="$JOBSTREAM_BADPBN34_JS1_1I$" onrequest="false" priority="100" workstation="$WORKSTATION_BADPBN34_WC1$"> model:runcycles/> <model:matching> <model:sameDay/> </model:matching> <model:restrictions/> <model:dependencies/> <model:jobs> <model:job confirmed="false" defintion="$WORKSTATION_MDM112097$#$JOB_BADPBN34_J1$" isCritical="false" iskey="false" name="$JOB_BADPBN34_J1$" priority="10"> <model:restrictions/> <model:dependencies> <model:predecessor target="$WORKSTATION_BADPBN34_WC1$#$JOBSTREAM_ BADPBN34_JS2$.@"> <model:matching> <model:previous> </model:matching> </model:predecessor> </model:dependencies> </model:job> </model:jobs>< /model:JobStream> </screen>