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 Configure > Deploy > Import Rule Sets.

  2. Click New.

  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 Configure > Deploy > Imports.

  2. Click New.

  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 Run.

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 ways:

  • 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>

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 Configure > Automate > Folders.

  2. Click New.

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

  7. Click New.

  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.
Copy 
{
  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 Job Definitions, and these Job 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 Configure > Deploy > Import Rule Sets.

  2. Click New.

  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 Job 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 Job 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 Configure > Automate > Folders.

  2. Click New.

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

  7. Click New.

  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.
Copy 
{
  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 Configure > Automate > Folders.
  2. Create a Folder named Example in the GLOBAL Partition.
  3. Create a Folder named MSLN_Temporary in the GLOBAL Partition.
  4. Navigate to Configure > Deploy > 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 Job Definition of type RedwoodScript named RS_MSLN_TestImport, with {} as the Source and MSLN_Temporary as the application.
  9. Navigate to Configure > Automate > Job Definitions and export the RS_MSLN_TestImport Job Definition (without its related Objects).
  10. Delete the RS_MSLN_TestImport Job Definition.
  11. Submit the System_ProcessKeepClauses Job Definition to run Now.
  12. Navigate to Configure > Automate > Folders 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 Configure > Automate > Job Definitions and locate the Job Definition named RS_MSLN_TestImport. Note that its application is set to Example.
Copy 
//@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. Run 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 Configure > Deploy > Import Rule Sets.
  2. Click New.
  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.
Copy 
{
  Partition p = jcsSession.getPartitionByName("REDWOOD");
  Queue q = jcsSession.getQueueByName(p, "MSLN_Queue");
  q.release();
}

Post-Persist - Submit a Job after Import

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

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

  1. Navigate to Configure > Deploy > Import Rule Sets.
  2. Click New.
  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.
Copy 
  //Get imported process Definition
  Partition p = jcsSession.getPartitionByName("REDWOOD");
  JobDefinition jd =  jcsSession.getJobDefinitionByName(p, "MSLN_Installer");
  Job j = jd.prepare();