Using Import Rule Sets to Customize Imports

You use import rule sets to customize your imports. Import rule sets allow you to organize the flow of processes between Development, Test (Quality Assurance) and Production systems. You can adapt default values of parameters, for example, to the target system. Import rule set actions allow you to further customize the objects during the import process with RedwoodScript.

When you import an object, except for tables (see below), the object is overwritten with the object in the CAR archive.

note

The Promotion Module requires the Module.ImportExport license key.

Tabs & Fields

The following sections cover the tabs in the Import Rule Set editor screen.

Import Rule Set

Field	Description
Partition	The partition of the import rule set.
Name	The name must start with a letter and contain only US ASCII letters, numbers, and underscores (_). Limited to 80 characters.
Application	The application of the import rule set. Applications are used to group different objects for easy migration.
Description	Free text description; you can use any printable UTF-8 characters; note that depending on the platform/browser, some characters of the symbol and other Unicode tables will not be displayable. Limited to 255 characters.
Variable Prefix	The variable prefix is used when you import the special System_Values table. New rows that were added during the import will be prefixed by the value of this property. This field accepts free text, any printable UTF-8 character combination.

Partition Renames

Field	Description
Old Partition	All objects that were in a partition named like this will be moved to the New Partition in the current system
New Partition	The new partition for all objects that resided in the Old Partition in the old system.

This will not take care of partitions specified in Redwood Expression Language (REL) expressions. You use the $ to specify the partition of the process definition or chain definition in REL; it will be replaced with the partition of the process definition or chain definition on which it is specified. You keep objects in the same partition as the process definition or chain definition, and promote these objects along with those that reference them. See REL Functions and Contexts for more information.

Import Rules

Import rule sets can hold one or more import rules. When you create an import, you may specify an import rule set according to which Parameters, like INSTANCE, CLIENT, or USERNAME for SAP process definitions, can be adjusted to the new system with overrides.

Field	Description
Name	The name of the rule must start with a letter, can only contain US ASCII letters, numbers, and underscores (_); limited to 80 characters.
Description	The description of the rule, will be used as the name of the rule when set. Free-form text, any printable UTF-8 character combination is allowed; note that depending on the platform/browser, some characters of the symbol and other Unicode tables will not be displayable. Limited to 255 characters.
Documentation	A comment about the rule. Free-form text, any printable UTF-8 character combination is allowed; note that depending on the platform/browser, some characters of the symbol and other Unicode tables will not be displayable. Limited to 255 characters. Limited to 1000 characters.
Object Type	Rules can be created for either process definitions (JobDefinition) or chain processes (JobChainCall) and allow you to change parameters or scheduling parameters.
Matching	This field groups the match criteria for a process definition/chain process and process/scheduling parameter.
Matching > Name	The name to match, you can use GLOB wildcards (*, ?). Empty means all process definitions or chain process will match.
Matching > Script Run-as-user	The Run As User to match for the process definition.
Matching > Parameter	Used to match zero or more parameters.
Matching > Parameter > Mapping Expression	Used with chain process only, it is the parameter mapping that the parameter has in the chain definition.
Matching > Parameter > Default Expression	Used with process definitions, this is used to differentiate parameters with the same name but different default values.
Matching > Hold On Submit	The Hold on Submit value to match.
Matching > Queue	The queue value to match.
Matching > Priority	The priority to match.
Replaces	This field groups the new values of the previously matched items.
Ignore Failure	When the new value is invalid, by default, the import will fail. You can override this with the Ignore Failure for specific changes.
Replaces > Script Run-as-user	The new Run As User for the process definition/chain process.
Replaces > Parameter	The new value(s) of the parameters.
Replaces > Hold On Submit	The new value for the Hold on Submit scheduling parameter.
Replaces > Queue	The new default queue of the process definition/chain process.
Replaces > Priority	The new priority of the process definition/chain process.

Import Action Parameters

Field	Description
Name	The name of the parameter must start with a letter, contain only US ASCII letters, numbers, and underscores. Limited to 80 characters.
Description	The description of the parameter can contain free-form text, any printable UTF-8 character combination is allowed; note that depending on the platform/browser, some characters of the symbol and other Unicode tables will not be displayable. Limited to 255 characters.
Documentation	A comment about the parameter. Free-form text, any printable UTF-8 character combination is allowed; note that depending on the platform/browser, some characters of the symbol and other Unicode tables will not be displayable. Limited to 255 characters. Limited to 1000 characters.
Default Value	Free text default value that will be used when the parameter has not been set elsewhere; can contain any printable UTF-8 character combination. Limited to 1000 characters.
Optional	When this checkbox is checked, then the value of the parameter is allowed to be empty. Note that the parameter in question will be initialized with a null value in the import action; when this checkbox is checked, null checks need to be in place in the import action.

Import Actions

Import rule sets support pre-import and post-import actions; the pre-import action is executed before the CAR file is scanned for contents, the post-import action is executed after the CAR is scanned immediately before the objects are committed to the database. The ImportActionScriptObject.getObjects() method is empty during execution of the pre-import action.

Field	Description
Name	Pre Import - executed prior to the import, a DataContainer Map is available for storing information for the actual import Tost Import - actual import, has access to DataContainer and UnresolvedObjects Maps (the latter provided you specify //@pragma:Unresolved on the first line of your script source). Post Import - action that allows you to perform post import operations, such as submit a process to clean up or prepare the environment.
Library	The library to add to your classpath; this allows you to call code from the library in your import action source.
Source	You fill your code into this field.

Using Import Actions

Actions on import rule sets allow you to specify RedwoodScript code to be executed against the imported objects after Redwood Server has imported the objects, resolving all references in the process (default), and before the objects are written to the database. The code is specified on the Actions tab and optionally makes use of the classes that you have stored in a library.

The following table lists predefined objects that you use in your source code:

Object	Class	Example Code
jcsSession	com.redwood.scheduler.api.model.SchedulerSession	jcsSession.getQueueByName("PRD_QUEUE");
jcsImportRuleSet	com.redwood.scheduler.api.scripting.variables.ImportActionScriptObject	for (Object o : jcsImportRuleSet.getObjects()) {...} Iterator i = unresolved.values().iterator(); //Map is <Long, ImportActionUnresolvedObject>
jcsOutLog	com.redwood.scheduler.infrastructure.logging.api.Logger	jcsOutLog.warn("This does not look good!");
jcsErrLog	com.redwood.scheduler.infrastructure.logging.api.Logger	jcsErrLog.fatal("Cannot determine the application of imported object.");

note

You should not persist the session in import rule set actions as this is done for you at a later stage.

Modifying Objects

Import rule sets have built-in functions to modify objects.

• You use Partition Renames to change the partition.
• You use Import Rules to change parameters on process definitions or chain processes.
• You use the Variable Prefix for tables you import; this prefix allows you to flag newly created table rows for inspection.

You use the ImportActionScriptObject.getObjects() call to retrieve a List of objects that are to be imported.

Resolving Objects

When you import objects that reference other objects that do not exist in the CAR file nor in the target system, you must replace these references with valid references to objects in the target system. Since the import action is executed after references have been resolved you specify //@pragma:Unresolved (case-sensitive) on the first line of your code. When you set this comment, you can call ImportActionScriptObject.getUnresolvedObjects() to retrieve a map over all unresolved objects. These need to be replaced with valid references, see Importing Objects with Import Rule Sets for a specific example.

Note that if you fail to replace all invalid references, the import process will fail; the strerr.log file will contain the number of invalid references. To get a list of all invalid references, run the import processes without ImportRuleSet.

Importing Tables

The import will fail when you import existing tables that differ in contents, except for the special System_Values table. This special table, when imported, will append additional rows that are found in the CAR archive to the existing table, modified rows will, however not be modified during the import.

Import Rule Set Parameters

Import rule sets accept parameters that can be set in the following manners:

• In the The properties of the import rule set (ImportRuleSetProperties) parameter of System_Import_Archive.
• Embedded in the CAR file in META-INF/ImportRuleSet-parameters.properties.
• On the command line using the api-tool.jar.

The parameters can be retrieved in the import rule set action using the jcsImportRuleSet.getProperty(<name>) method, where <name> is the name of the property of which you want to retrieve the value.

Embedded Import Rule Sets

Import rule sets can be embedded in CAR files, this allows you to specify any import rules, such as partition renames, directly in the CAR file.

The import rule set must be named ImportRuleSet.xml and reside in the META-INF/ directory in the CAR file, alongside the export-info.xml file.

Partition Renaming in Embedded Import Rule Sets

Import rule sets embedded in CAR files can specify a partition variable that can be set in the import rule set action using the ${TargetPartition} variable; a default value can be specified using the ${TargetPartition}:<default_value> syntax. If no default value is specified in the export rule set, the parameter is mandatory and must be set on the command line, for example.

The following excerpt of an import rule set specifies a partition rename with default value; when no TragetPartition variable is set for the import rule set, all objects will be imported into the DEFAULT_PARTITION partition.

<ImportRuleSetPartitionRename>
  <ProcessOrder>0</ProcessOrder>
  <OldPartition>GLOBAL</OldPartition>
  <NewPartition>${TargetPartition:DEFAULT_PARTITION}</NewPartition>
</ImportRuleSetPartitionRename>

Context-Menu

Import rule sets support the following context-menu actions:

Action	Description
Submit Import Job	Submits an import process with the current import rule set
Edit Security	Edit the security of the import rule set
Duplicate	Make a copy of the import rule set to create a similar one
Delete	Delete the import rule set
Export > Export	Export the import rule set into a CAR file
Export > Export with related objects	Export the import rule set into a CAR file including referenced objects
Promote > Promote to system	Promote the object to a remote system
Promote > Edit further then promote	Edit the export rule set prior to promoting
Promote	Promote the import rule set to another Redwood Server instance
Edit	Edit the import rule set
Show permalinks	Show links that can be used from third party applications to link to the object
Add to navigation bar	Add the current object to the navigation bar
New import rule set	Create a new import rule set
Filter > New Filter	Create a new import rule set filter
Filter > Edit Filter	Edit current import rule set filter
Filter > Delete	Delete current import rule set filter
Filter > Duplicate Filter	Create a copy of the filter
Filter > Export Filter	Export the filter into a CAR file
Filter > Add to navigation bar	Add the filter to a navigation bar
Filter > Create filter from search	Create a filter from the current IntelliSearch query

Finding Import Rule Sets

You can search for import rule sets using filters and the Search Import Rule Sets box, known as the IntelliSearch box, located under your username on the top right-hand side of the user interface. Filters allow you to specify a list of objects with static criteria. IntelliSearch allows you to specify complex queries in a simple way using prefixes. Prefixes are used to specify which property you are searching in and have short as well as long syntaxes. For example, if you want to display all import rule sets with the term dev in the comment, you would use the search criteria as follows:

c:dev

You can search more than one property, as follows:

c:dev n:ORA

note

No spaces should be entered before or after the colon (: ).

See the Advanced Object Search for more information.

The following table illustrates the available prefixes for import and export rule sets:

Prefixes	Description
n, name	searches the name property
c, comm, comment	searches the documentation property
d, desc, description	searches the description property
a, application	searches the application property
cb, changedbefore	(internal) search for import rule sets that changed before a certain ISO-8601 period

Security

Privilege	Description
ImportRuleSet.Create	Create import rule sets
ImportRuleSet.Delete	Delete import rule sets
ImportRuleSet.Edit	Edit import rule sets
ImportRuleSet.View	Access import rule sets

You can grant privileges on two levels, Access and Admin; a privilege granted on Admin level allows the grantee to grant the privilege to other users. These privileges can be granted per partition or system-wide.

note

The Promotion Module requires the Module.ImportExport license key

• Granting and Revoking System Privileges
• Granting or Revoking Object Privileges

See Also

• Importing Objects with Import Rule Sets
• Importing Objects
• Importing Redwood Server Objects with Imports
• Migrating Objects with the Promotion Module
• Privileges Required to use ImportRuleDefinition
• Privileges Required to use ImportRuleSets
• Privileges Required to use ImportSources
• Export Rule Sets
• Creating Export Rule Sets
• Exporting Redwood Server Objects
• Promoting Objects with Remote Systems

ImportRuleSet import rule set