Working with Import Rule Sets

You can use Import Rule Sets to customize object imports.

Creating an Import Rule Set

To create an Import Rule Set:

1. Navigate to Promotion > Import Rule Sets.

2. Click .

3. Choose a Partition and enter a Name.

4. If you want to rename partitions during import, click the Partition Renames tab and add some partition renaming rules.

5. If you want the Rule Set to contain one or more import rules, click the Import Rules tab. Click Add to add an import rule, then choose an option from the Object Type dropdown list. The controls below this field change depending on which type of object you select. See below for details.

6. To specify pre-import, post-import, and post-persist rules, click the Import Action tab.

7. Fill in the details and choose the Import Rules Tab.
8. Click Save & Close.

Using Import Rule Sets

To use an Import Rule Set during an import:

1. Navigate to Promotion > Imports.

2. Click .

3. On the Select CAR file screen, select the CAR file you want to import or enter its URL.

4. On the Import Rule Set screen, select the Import Rule Set you want to use.

5. On the Import Details screen, select the import options you want to use.

6. Click Submit.

Import Rule Set Tab

Partition Renames Tab

These renaming rules will not change partitions specified in Redwood Expression Language (REL) expressions. You can use the $ character to specify the partition of a 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 can 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 Tab

Import Action Tab

You can specify code to be run at any or all of the following points during import.

• Pre Import: Executed before the CAR file is scanned. A DataContainer Map is available for storing information for the actual import. The ImportActionScriptObject.getObjects() method is empty during execution of the pre-import action.

• Post Import: Executed after the CAR file is scanned, but before the objects are persisted to the database. Has access to DataContainer and UnresolvedObjects maps (the latter is provided if you specify //@pragma:Unresolved on the first line of your script source).

• Post Persist: Executed after the objects are persisted to the database. This allows you to perform post-import operations, such as submitting a process to clean up or prepare the environment.

Tip: You can use the ImportActionScriptObject.getObjects() call to retrieve a list of objects that are to be imported.

Variables List

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

Warning: Do not persist the session in Import Rule Set actions, because this is done for you at a later stage.

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 can specify //@pragma:Unresolved (case-sensitive) in the first line of your code. If you add this comment, you can call ImportActionScriptObject.getUnresolvedObjects() to retrieve a map over all unresolved objects. These will need to be replaced with valid references. For a specific example, see Working with Import Rule Sets.

Warning: 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 the Import Rule Set.

Importing Tables

If you try to import tables that exist in the target system but have different contents (except for the special System_Values table), the import will fail. If you import the System_Values table, rows that are not found in the target system will be appended, but existing rows not be modified during 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 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 for which you want to retrieve a value.

Using Embedded Import Rule Sets

You can embed and Import Rule Set in a CAR file by exporting the Import Rule Set and then extracting it out of the car file. Set the Name to ImportRuleSet, the partition to GLOBAL, and the Library to GLOBAL.None. The resulting XML file can be copied into the target CAR file at the following path: META-INF/ImportRuleSet.xml.

A properties file can also be embedded in the car file and will be used in combination with the Import Rule Set, provided it is located in the CAR file under META-INF/ImportRuleSet-parameters.properties.

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. You can specify a default value 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 (for example) on the command line.

The following excerpt from an Import Rule Set specifies a partition rename with a 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 options.

Note: For generally applicable object context menu options, see Object Context Menu.

Security

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

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

Examples

Pre Import: Hold a Queue Prior to Import

Assume that you want to prepare the environment for the objects to be imported, and that requires you to hold a Queue (in this example, the Queue named "MSLN_Queue"). To make this happen:

1. Navigate to Applications.

2. Click .

3. Select the GLOBAL partition.
4. Enter Example into the Name field.
5. Click Save & Close.
6. Navigate to Promotion > Import Rule Sets.

7. Click .

8. Enter a name.
9. Click the Import Action tab.
10. Click Pre Import enter fill the code below into the Source field.
11. Click Save & Close.

{
  Partition p = jcsSession.getPartitionByName("REDWOOD");
  Queue q = jcsSession.getQueueByName(p, "MSLN_Queue");
  q.hold();
}

Post Import: Using Import Rules to Change Objects During Import

Assume you want to import a CAR archive containing multiple Process Definitions, and these Process Definitions all have a parameter named SAP_SYSTEMS that needs to be assigned a new default value. Assume further that the default value in the CAR file is Q2A, and you want to replace that with PR2 to match the new system. The parameter CLIENT also needs to change from 200 to 800. To accomplish this:

1. Navigate to Promotion > Import Rule Sets.

2. Click .

3. Select the GLOBAL partition.
4. Enter a name.
5. Click the Import Rules tab.
6. Click Add to create a new import rule.
7. Enter Q2A_TO_PR2 in the Name field and choose Process Definition from the Object Type dropdown list.
8. In the Matching area, click New next to Parameter and enter the Name SAP_SYSTEMS and the Default Expression Q2A.
9. In the Replaces area, click New next to Parameter and enter the Name SAP_SYSTEMS and the Default Expression PR2.
10. Add an additional import rule.
11. Enter 200_TO_800 in the Name field and choose Process Definition from the Object Type dropdown list.
12. In the Matching area, click New next to Parameter and enter the Name CLIENT and the Default Expression 200.
13. In the Replaces area, click New next to Parameter and enter the Name CLIENT and the Default Expression 800.
14. Click Save & Close.

Post Import: Using RedwoodScript to Change Objects on Import

The following procedure creates an Import Rule Set that assigns the Example application to all objects in an import.

1. Navigate to Applications.

2. Click .

3. Select the GLOBAL partition.
4. Enter Example into the Name field.
5. Click Save & Close.
6. Navigate to Promotion > Import Rule Sets

7. Click .

8. Enter a name.
9. Click the Import Action tab.
10. Click Post Import and enter the code below into the Source field.
11. Click Save & Close.

{
  Partition part = jcsSession.getPartitionByName("GLOBAL");
  Application application =  jcsSession.getApplicationByName(part, "Example");
  for (Object o : jcsImportRuleSet.getObjects())
  {
    if (o instanceof ApplicationObject)
    {
      ((ApplicationObject) o).setParentApplication(application);
    }
  }
}

Post Import: Using RedwoodScript to Repair Missing References

All referenced objects that are not in the CAR file must be in the target system. If, for example, an application referenced by objects in the CAR file is neither in the CAR file nor in the target system, that creates an unresolved reference. Unresolved references must be updated via the UnresolvedObjects Map.

1. Navigate to Applications.
2. Create an application named Example in the GLOBAL partition.
3. Create an application named MSLN_Temporary in the GLOBAL partition.
4. Navigate to Promotion > Import Rule Sets.
5. Create a new Import Rule Set and click its Import Action tab.
6. Click Post Import and enter the code below into the Source field.
7. Click Save & Close.
8. Create a Process Definition of type RedwoodScript named RS_MSLN_TestImport, with {} as the Source and MSLN_Temporary as the application.
9. Navigate to Definitions > Processes and export the RS_MSLN_TestImport Process Definition (without its related objects).
10. Delete the RS_MSLN_TestImport Process Definition.
11. Submit the System_ProcessKeepClauses Process Definition to run Now.
12. Navigate to Applications and delete the application named MSLN_Temporary.
13. Submit an import with the Import Rule Set and select the exported CAR file.
14. Navigate to Definitions > Processes and locate the Process Definition named RS_MSLN_TestImport. Note that its application is set to Example.

//@pragma:Unresolved

import com.redwood.scheduler.api.model.Application;
import com.redwood.scheduler.api.scripting.variables.ImportActionUnresolvedObject;
import java.util.Map;

{
  Map<Long,ImportActionUnresolvedObject> unresolved = jcsImportRuleSet.getUnresolvedObjects();
  Partition part = jcsSession.getPartitionByName("GLOBAL");
  Application exampleApp = jcsSession.getApplicationByName(part, "Example");
  unresolved.forEach((k, v)->
  {
    jcsOutLog.info("type: " + v.getObjectType());
    jcsOutLog.info("path: " + v.getPath());
    if (exampleApp != null
        && Application.OBJECT_TYPE.equals(v.getObjectType())
        && "GLOBAL.MSLN_Temporary.$2".equals(v.getPath())) //Check the application path in the source system, ensure you specify the correct path here
    {
      v.replaceWith(exampleApp);
    }
  });
}

Tip: If your import action does not replace all unresolved objects, a RuntimeException will be thrown with the number of unresolved references. Submit the import without the import action to get a list of unresolved references.

Post Persist: Release a Queue

To release the Queue named MSLN_Queue after the imported objects have been persisted to the database:

1. Navigate to Promotion > Import Rule Sets.
2. Click .
3. Select the GLOBAL partition.
4. Enter Example into the Name field.
5. Click the Import Action tab.
6. Click Post Persist and fill the code below into the Source field.
7. Click Save & Close.

{
  Partition p = jcsSession.getPartitionByName("REDWOOD");
  Queue q = jcsSession.getQueueByName(p, "MSLN_Queue");
  q.release();
}

Release Queue REDWOOD.MSLN_Queue after the objects have been imported.

Post Persist - Submit a Process after Import

Assume you want to submit the Process Definition named MSLN_Installer after import to cleanup or prepare the environment for the newly imported objects.

Note: The Process Definition can have been imported in the import where this runs.

1. Navigate to Promotion > Import Rule Sets.
2. Click .
3. Enter a name and then click the Import Action tab.
4. Click Post Persist and enter the code below into the Source field.
5. Click Save & Close.

  //Get imported process Definition
  Partition p = jcsSession.getPartitionByName("REDWOOD");
  JobDefinition jd =  jcsSession.getJobDefinitionByName(p, "MSLN_Installer");
  Job j = jd.prepare();