Creating and Managing Objects

 

To perform an export on the Scheduler object, or any Folder or Plan, right-click on the desired object, then select Import/Export, then Export. To perform an export on all other object types, right-click on the desired object then select Export. 

 

 

The Export dialog above is what you will see when exporting the Job Scheduler object, or any Plan or Folder object. There are variations of the Export dialog, depending on the object selected to export. The variations do not include any additional checkbox options (as depicted above), but rather, some checkbox options will not be present because they do not apply to the object being exported.  

 

Let’s go over all the Export dialog checkbox options.

 

Export this container recursively (this container and all its child objects) - checked by default.

• You will see this Export option when you select the following object types to export: Scheduler object, Folder or Plan (which are referred to as the three ActiveBatch “containers”).

• When checked, the container object and all its nested child objects will be included in the export.  

• When not checked, only the single container object is exported.  

  Please note that when exporting a container recursively, some of the export security options discussed next may be applicable to the container itself, and/or the container’s child objects. For example, if a Plan and one of its jobs both have secured variables defined, and the Plan is exported recursively, checking “Remove secured variable values on export” would remove the secured variable values from both the Plan and the nested Job.

SecuredExport - not checked by default

• This Export option provides you with a way to quickly select/deselect all the security-related subitem checkboxes. 

• When any or all of the SecuredExport subitems in the image below (the 3 “remove” options) are present in the Export dialog, it means the object(s) the user has chosen to export could possibly  include some or all of the items that can optionally be removed.  If any “remove” option is checked, and it is not applicable to any object(s) in the export (e.g. there are no secured variables), then the removal is simply ignored. 

 

 

Remove encrypted passwords on export

 

This option is not checked by default. This action enhances password security.

• You will see this Export option when you select the following object types to export: Scheduler object, Folder, Plan, and User Account object.

• When checked, an encrypted password configured in the User Account object will have its value removed (cleared out). If encrypted passwords are removed on export, the user performing the import will be prompted to provide a new password after object(s) are successfully imported. They can opt to skip this and update the User Account password later, if desired. 

Depending on the User Account object’s “Credential Type” that has been configured, the field that is encrypted and therefore removed may vary.  For example, the “Username/Password” Credential Type will have the encrypted password removed on export.  As another example, when the Credential Type is “REST API Connection” the following fields will be removed, based on the REST API Connection type selected: 

 

API Key: Value field

OAuth2.0 - all 3 grant types: Client ID and Client Secret fields AWS Signature:

Access Key ID and Secret Access Key fields

 

Remove secured variable values on export - not checked by default. This action enhances the security of sensitive variables.

 

Note about secured variables: For almost all the object types that support the creation of variables, securing (hiding) the variable value is accomplished by enabling the “Secured” property checkbox, located on each individual variable’s property sheet. Securing a variable in the Service Library object, when using the REST Adapter (V2) is done a bit differently. Local or Global REST Adapter (V2) variables are secured by selecting a variable in the Variables grid, then clicking on the lock icon.

• You will see this Export option when you select the following object types to export: Scheduler object, Folder, Plan/Plan Reference, Job/Job Reference, Queue (Execution and Generic), User Account, and Service Library. These are all the objects that support the creation of secured variables. 

  • When checked, any variable marked “Secured” will have its value removed (cleared out) upon export.  After the objects have been successfully imported, the user will be prompted to enter the secured variable’s value. They can opt to skip this and update the variable(s) later, if desired. 

 

Remove dependency identifiers on export - not checked by default.  This action allows for object sharing (e.g. a REST Adapter) with other people within or outside your organization without exposing internal paths to dependency objects. 

 

To clarify what a dependency is, a dependency is any object that another object depends on (is using). For example, a Job object always has at least 2 required dependencies, a Queue and User Account object.  Dependency objects are not part of an export unless a container is exported that includes the dependencies. By default, when a single Job is exported, the ID and full path of the Job’s dependencies are included in the XML file, but not the actual dependencies themselves.

 

• The “Remove dependency identifiers on export” is an Export option you will see when you select any object type to export.

• When the “Remove dependency identifiers on export” option is checked, the identifiers of the dependency(s) are removed (cleared out) from the object(s) that are being exported. This is true when the dependency(s) are not part of the current export. As an example, if you export a single Job, it is not possible for dependencies to be included in the current export. Therefore, in this example, removing the dependency identifiers would apply. If a container is exported that includes some but not all the dependencies, then the dependency identifiers would only be cleared out for the dependency objects not included in the export. 

  • Upon import, the user will be prompted to select dependency(s) in the target environment for the objects where the dependency identifiers have been removed. They must select dependency(s) before the import can proceed.  

• When “Remove dependency identifiers on export” is not checked, the dependency paths are not removed. If the dependency paths do not resolve upon import, meaning the dependency cannot be found on the target system, and they are not part of the current export, then the user performing the import will be prompted to resolve the missing the dependency(s). 

 

See below the “Export Dependency Mappings” heading for more information related to this topic.

 

Sign this export - checked by default. This action enhances the security of the XML export file.

• “Sign this export” is an Export option you will see when you select any object type to export.

• When checked, a signature tag is included in the XML file. This prevents the import of an XML file that has been modified outside of ActiveBatch. Do not check this option if it is your intent to make changes to the XML file manually outside of ActiveBatch.

• When “Sign this export” is not checked, a user will not be prevented from importing a file that may have been modified outside of ActiveBatch (they will be warned that the file was not signed).  

 

This ends the discussion of the Export dialog options. After configuring them, click OK when you are ready to proceed with the export. 

 

Next, an “Export Dependency Mappings” window will pop up if the export includes any dependencies that are not part of the export.

 

Export Dependency Mappings

 

This window displays a list of one or more dependencies that are not part of the current export.  In the list are 3 columns: ID, Path and Description.  The ID and Path are read-only columns that identify the dependency’s object ID and full path.  

 

• The Description column is user-editable and initially empty. 

  • The purpose of entering a Description is to provide some context for the user performing an import if they need to resolve missing dependencies. If the import user is presented with a “Resolve Dependencies” window, that means they must map dependencies to objects on the target system. The Description property should offer information that will help the user identify what objects they should select to resolve the dependencies.  

  • The Description is required when the Export option “Remove dependency identifiers on export” is checked, because the dependency identifiers are being intentionally removed, therefore resolving  dependencies will be a required task upon import.

  • The Description is not required when the Export option “Remove dependency identifiers on export” is not checked, because the dependency may very well resolve upon import, and therefore the user will not be prompted to resolve any missing dependencies.  But, if for some reason any dependency(s) fail to resolve upon import, the Description field would be useful to aid the user in mapping the dependency object. 

• The Description field can be entered manually, or the user can click on the “Import Object Description” button. This will import the dependency’s “Description” property (if set), located on the dependency’s General property sheet. This can be quite useful if you will be repeatedly mapping objects when importing.  

 

After all the Export-related dialog is complete, you will be prompted to save the file. Navigate to a directory to save the

file in, then enter the file name. Click Save. The XML export file will be created.

To import an XML export file, right-click on the target container (Scheduler object, Plan or Folder) that you would like the object(s) to be imported into. Select Import/Export from the menu, then select Import. An Import window will appear. Click on the Select File button, then navigate to the desired XML export file, select it, then click on Open.

 

 

Let’s discuss the options you see in the Import dialog. 

 

Conflict Resolution -   Conflict resolution refers to what to do if an existing object is already present in the system where the import is taking place. Your choices are: Ignore (the default), Copy, Update, Force Update. 

 

• Ignore – Objects in the import file will not be imported.

• Copy – Objects in the import file will be added to the target Job Scheduler with the words “Copy of” inserted as part of the Name/Label of the object. 

• Update - Objects in the import file will replace the matching objects in the target Scheduler only if the target Scheduler's object revision ID is lower than the revision ID of the object in the import file. Higher revision IDs in the target imply a more recent modification (and typically you do not want a lower revision to replace a higher revision).

• Force Update - Objects in the import file will replace the matching objects in the target Job Scheduler in any situation, regardless of the revision ID.

 

Restore original owner – When checked, the imported objects will retain their original owner as they were set when exported. If this box is not checked, the user performing the import will be the new owner.

 

Restore original security – checked by default. When checked, the imported objects will retain their original security settings as set when exported. If this box is not checked, the Scheduler will obtain its security from target Scheduler default policies set and/or - if any imported objects had "inherit security checked", the objects will inherit their security from the parent container.

 

In general, you will typically want to select the “Restore” options when importing to the same system you exported from. If you are importing from a different Job Scheduler, like a QA system, you will probably not want to restore either the original owner or security settings because they are likely to be different in the new environment (for example, Production).

 

Import Tags – When checked, the system will import Tags that were associated with the exported objects.

 

Disable Objects on Import – When checked, objects that support the basic disable feature will be disabled upon import.  This provides you with an opportunity to decide what to enable in a controlled manner on the target system. 

 

Verbose – When checked, an informational Audits window will pop-up after the import, as depicted in the image below.  This will provide you with information on what objects were imported. 

 

The audits table will include 3 columns, the Date and Time the import occurred, the imported object’s name and full path and ID, and the Description (what happened during the import).  

 

 

Let’s look at the different values you may see in the Audit’s Description column.

 

Description column values when the object(s) are newly added to the target environment

 

In the above image, the description value is “Created”, which you will see when the objects did not already exist in the target environment, and therefore were added. You will also see “Created” if the objects already existed in the target, but the Confliction Resolution property was set to “Copy” (so a copy of the object was created). When a copy is created, the object copied will have _Copy in the object name. 

 

Description column values when the object(s) already exist in the target environment

 

The “Object has not been updated” description would indicate the Confliction Resolution property was set to “Ignore”. 

 

The “Modified” description would indicate the Conflict Resolution property was set to “Update” and the imported object had a revision that was higher than the one that already existed in the target. It could also mean the Conflict Resolution property was set to “Force Update”, where revisions are not considered, and the updates always take place. 

 

The “Object has a newer revision” description would indicate the Conflict Resolution was set to “Update” and the existing target object is newer (the target object will not be updated). 

 

Check in Comment – This property allows you to enter a check-in comment, to describe what is being imported. Objects that are added or updated (in any way, not just via an import), result in the automatic creation of a Changeset,  under-the-hood.  You can see the comment when you view the changeset history, accessible by right-clicking on the imported object, then selecting View, then Changeset History. 

 

Let’s now look at what to expect upon import when the following Export options are checked.

 

Remove encrypted passwords on export 

 

When the Export option “Remove encrypted passwords on export” is checked, you will be prompted to provide the password (or value for any field in the User Account object that is encrypted) during an import. This is depicted in the image below, where the User Account object’s Credential Type property is Username/Password. You can enter the password, then click OK.  Or, you can check “Ignore item”, then click OK.  Note, if there is more than one User Account object being imported, they will all be in a list, and each account will need its password entered. 

 

 

If “Ignore item” is checked, you will be prompted to confirm your choice. Later, you can modify the User Account object and enter the password. One possible reason for ignoring an update on import is another user may need to update the password, not the user performing the import.  Until the password or other encrypted User Account property value (e.g. REST API Connection API Key) is updated, any job depending on it will fail. 

 

Remove secured variable values on export: 

 

When the Export option “Remove secured variable values on export” is checked, you will be prompted to provide the secured variable value during the import, as depicted in the image below. Note, if there is more than one secured variable, they will be in a list, each requiring a value. You can opt to enter a value, then click OK.  You could also check “Ignore item”, then click OK.

 

In the image below, JobZ has a secured variable configured named VarA.  Its value was removed upon export. The user is prompted to enter the variable value for VarA.  It will be saved as a secured variable.

 

 

If “Ignore item” is checked, you will be prompted to confirm your choice. One reason it may be ignored upon import is another user needs to update the variable value, not the user performing the import. Or, perhaps the value was not readily available at the time the import took place.

 

Let’s assume the variable was not updated upon import or after, and the job runs. The payload of the job echoes out the variable value to the job log file.  You will see ABAT_SECURE_VARIABLE_VALUE_REMOVED in the job log file, which is what happens when a variable’s value is removed upon export and not updated during or after the import. The variable can be modified with the correct value at any time. 

 

Remove dependency identifiers on export (Resolve Dependencies)

 

When the Export option “Remove dependency identifiers on export” is checked, dependency identifiers are removed from exported objects only when the dependency objects are not included in the export file. In addition, any dependencies that are missing that did not have this Export option checked, will also need to be resolved before the import can be performed. This is accomplished using the Resolve Dependencies window, which will only pop up during an import when dependencies must be resolved. 

 

In the Resolve Dependencies window, one or more missing dependencies will appear in a grid format.  If the reason for the missing dependencies is because the “Remove dependency identifiers on export” option is checked, then the grid will have 3 columns - Type, Description and Mapping.  If the reason for the missing dependencies is not due to the “Remove dependency identifiers on export” option being checked, then the grid will consist of the same 3 columns, plus a fourth column named “Path”, which is the full path of the dependency object that is not present on the target Scheduler.  

 

Type: The type of object (e.g. Queue, User Account, etc.)

 

Description: Its purpose is to offer information to help resolve the missing dependency.  The user performing the export was required to enter a description when they selected “Remove dependency identifiers on export”. It was optional to enter a description when the remove dependency identifiers feature was not checked, but it can be helpful if dependencies do not resolve for unexpected reasons.

 

Mapping: A dropdown list that displays a picklist of ActiveBatch objects, filtered by the “type” of object you need to select for the mapping. 

 

Path: The full path of the missing Dependency object – this column is only present when the “Remove dependency identifiers on export” option is not checked.

 

New button:  If you need to create a new object to resolve the dependency, click the New button and configure the properties for the new object.

 

Let’s look at an example. In the image below, a job was exported with its dependency identifiers removed on export. Upon import, the Resolve Dependencies window pops up. The user who performed the export entered the information you see in the Description column. The Mapping column is initially empty, but based on the helpful description entered during the export, the user performing the import was able to select the User Account and Queue objects by clicking on the dropdown arrow in the Mapping column and navigating to the object for selection.  

 

 

After mapping dependencies or creating new dependency objects, then clicking OK, the object(s) will be imported.  

 

If any secured variables or User Account object encrypted values were removed during the export, the user will be prompted to enter that information, as described above. This occurs after the objects are imported. 

Signed Export

Just before the import is about to take place, the system checks to see if the export file was signed or not. If the export file was not exported with a signature (“Sign this export” was not checked) a warning message will pop up, as depicted below. Whether to proceed or not is up to the user. 

 

 

If the file selected for import did have the Export option “Sign this export” property checked when the export was performed, the signature is validated to ensure it matches. If the signature does not match, an error is thrown, as per the image below, and the import fails. If this happens, you must create a new export and perform the import again. If the signature does match, then no popup window relating to a signature will appear, and the import will proceed.