Administrator Scripts

Scripts that may be useful for administrators.

Various Jython scripts are provided to make administration easier. Typically, they are invoked by doing the following on the primary ACS server:
  1. Open a command shell.
  2. cd /d %lspeed_home%\iEngine\python
  3. jython <<scriptname>>.py

Invoking a script with no command line arguments typically prints out usage instructions. Sometimes a script interactively prompts for input. In a few cases, the script just performs its intended task. It is best to read the script before executing it, unless Astoria support has supplied specific instructions on how to run a script.

Here are administrator scripts you can use:
Name Description
disableWasteBasket When invoked without arguments, the waste basket is disabled so that all deletions are immediate and non-reversible. When invoked with a parameter of enable, waste basket functionality is re-enabled.
findOrRemovePIs Removes unwanted processing instructions preceding the first element of a document. Imports a TopLeaf folder into the database. Parameters are:
  • The folder to import
  • The directory to which the imported folder and its contents are shadowed
  • Optional pattern argument to cause files that match the pattern to be ignored

For example:

jython C:\Users\Don\TopLeaf\Astoria C:\Styles .*\.png

In this example, the script ignores all files that have the .png extension. Prunes obsolete custom attributes from DITA maps that can degrade Workbench performance when viewing or editing those maps. See the task Post-Upgrade Script in the ACS Installation and Configuration Guide for Astoria 6.5. Registers DITA-OT transtype parameters to a list of watched parameters. When one of these parameters is present in a transtype parameters map during the composition process, it will trigger Astoria to switch the naming convention of the output file.

Traditionally Astoria names its output files in the format [name].[extension]. However the presence of a registered parameter will alter the naming to be of the format _id_[astoria_object id]_[name].[extension]. This naming convention is required for certain transtypes to work, such as EditLink. See About the EditLink Plugin. However, Astoria automatically adds the three EditLink plugin custom parameters to the watched parameters during an upgrade or installation, so customers who subsequently install the EditLink plugin do not need to run the script to add the parameters. The script is supplied for customers who may install other plugins that require similar functionality to work correctly.

Supported commands are:
  • add - requires a parameter argument. Adds a parameter to the watch list.
  • remove - requires a parameter argument. Removes a parameter from the watch list.
  • list - does not require a parameter argument. Lists all of the currently watched parameters.

The parameter argument is the name of the parameter to register to watch. Enables logging of repository activity, creating an Activity DITA map in the Administration cabinet's Logs > Deletions folder, and creating a new DITA topic in the map identifying the activity performed in the repository per day. Logon and logout events are always included by default. An administrator can specify the duration of a session. If a user doesn't perform any operations for the session duration, a logout event is captured.

The Event Queue Properties sheet for Deletions can specify which optional types of events are logged. Logon and logout events are always included by default. This script configures Acrolinx settings to use SSO and compatibility with Acrolinx API (1.0.8). An administrator can configure:
  • Acrolinx host
  • Signature
  • API token
setATMConrefOption Sets translation option that determines if conref text is included as an attribute in the exported translation file.
setAppAdmins Sets or Lists the application administrators group.
setCachingOption Sets the option that determines whether caching is enabled or disabled for certain operations and objects
This setting affects the HTML output during Review of structured documents and files and provides hints to the browser about how to handle caching of graphics and HTML. This affects review in and out of the Workbench as well as on mobile platforms.
  • none - browsers are instructed not to cache text or graphics
  • graphics - browsers are instructed to cache graphics and not text
  • HTML - browsers are instructed to cache text and not graphics
  • graphicsAndHTML - browsers are instructed to cache both text and graphics
setCheckinOption Configures checkin dialog constraints.

´╗┐This option controls whether users are required to checkin validated XML without detected errors. This is done by forcing the Validate and Cancel on Errors buttons of the checkin dialog to be checked and disabled.

This script can also set require a minimum length for checkin notes, which can be used to force all users to provide a checkin note for every checkin.

This script can set a control to prevent users from altering the Version Name when checking in an object.

setClientDefaults The Astoria repository database defaults to 500-second connect and read timeouts. Run this script to specify values that override the default timeouts limits.

Increase the read timeout limit to eliminate errors when importing large document sets. After you run the script, close all Workbenches and then restart them.

setClientExceptionLogging Enables an administrator to configure a global policy for the client logging of stack traces. The default policy is that client stack traces are logged in the client log. For additional security, an administrator can configure the policy to instead have those traces logged in ACS read servlet logs. The script also enables the administrator to override the global policy on a per user basis. The script prompts the user with the various options and does not take any command line parameters.

For examples of client logging and servlet logging when configured to override the global policy, see the topic Configuring Stack Trace Logging in the ACS Installation and Configuration Guide for Astoria 6.5.

setDiagnosticMail Configures the email address used for the diagnostic tool.
setDitaErrorPolicy Configures if DITA-OT should generate output when non-fatal errors are detected. The default is true. In either case, the log will report all errors.
setDITAOTClasspath The script automatically locates all folders starting with DITA-OT inside of the %lspeed_home% directory and constructs the classpath for each DITA-OT version automatically. However, the user is still prompted for VMArgs for each DITA-OT. If the user simply presses Enter at this prompt, the default VM args are used.
Note: This script is called by the Run DITA-OT Integrator command after it has made changes to the DITA-OT files on the server.
setDITAOTEntityMappings Defines how to convert a character entity to a character during DITA-OT composition
setDITAOTFilenameCharacters Configures which characters to exclude from filenames when exporting for composition. Specifies where structured document references (sub documents) are stored in the repository when importing a structured document.
Policy options are:
  • 1 - No hierarchy - All subdocuments are placed in the specified folder for the import operation.
  • 2 -Hierarchy Tranche - Documents are tranched (broken up into separate folders), each folder containing a maximum of 100 documents.
  • 3 - No Hierarchy First Tranche - This is the default value. The first 100 documents are stored in the specified folder for the import; additional documents are tranched into subfolders, each containing a maximum of 100 documents.

When you run the script, the current policy value is displayed. Click Enter to accept the current policy, or click an option number to change the policy. A changed policy takes effect immediately for subsequent imports.

setDomain Attach a domain name to all users.
setDTDDataPreload Clears and configures DTDs to be cached in ACS Servlets Changes the polling frequency with which the bridge verifies network access to the server. By default, the polling is disabled. To enable polling, enter the number of seconds between polling intervals.
setElementDescriptions Adds or changes element descriptions via script rather than from Workbench dialog.
setEntityFileWhereUsed Enables and lists if only first level of documents referencing a file via entity reuse is listed, or if all levels (the default) should be listed.
setEntityNamePrefix Sets the prefix characters to be prepended on entity names created by the 'Create Database Entity' dialog used by the LAN Bridge Sets an Enumeration Limit. This is the maximum number of objects that will be listed in any container in the Workbench. When you click on a folder, or an administrative object, such as an event queue, the children of that object are displayed in the Details view. By default, all items are listed. If you set the Enumeration Limit to X, then only the first X items will be listed.

If you set a limit and an object exceeds the limit, the Details view indicates you have reached the Enumeration limit, and shows the number of additional items not displayed.

Leave the default value of no limit unless you are directed to limit the number by Astoria technical support.

setFileNameFiltering Configure file name filtering for export, compose, and translate operations.
setFilterAttributeInfo Configures filtering emphasis of elements. Both the background color and list of elements can be listed and changed.
setForceExternal Configures the xml importer behavior regarding external references.
setFTPConnectMode Sets active or passive FTP behavior for Compose or Reports batch jobs.
Note: Background Export jobs use the same settings as those for Compose jobs.
setGlobalApp This is a general purpose script for storing configuration data. As an example, administrators can configure the pattern used for altering folder item names when duplicates occur during import and move operations. The following commands configure Astoria to use a Windows-like format.
  1. jython 0 com.astoria.database folderItemUniqueName prefix " ("
  2. jython 1 com.astoria.database folderItemUniqueName counter 2
  3. jython 0 com.astoria.database folderItemUniqueName suffix ")"
Note that in this example, the counter is the seed value for duplicate names. The first copy would have (2) appended.
setGraphicsImportPolicy Specifies where graphics and external file references are stored in the repository when importing a structured document.
Policy options are:
1 - No Hierarchy
All files and external files are placed in the specified folder for the import operation.
2 - Hierarchy Tranche
Files are tranched (broken up into separate folders), each folder containing a maximum of 100 files.
3 -No Hierarchy First Tranche
Default value. The first 100 files are stored in the specified folder for the import; additional files are tranched into subfolders, each containing a maximum of 100 files.

When you run the script, the current policy value is displayed. Click Enter to accept the current policy, or click an option number to change the policy. A changed policy takes effect immediately for subsequent imports.

setLocaleMappings Configures locale mappings used in translation.
setIngeniuxSettings Sets the Astoria Portal Ingeniux location and Ingeniux login properties for Publish to Astoria Portal. The script will prompt you for the settings. See Configuring the Astoria Portal for Ingeniux Server.
setNameOrDescriptionOfStructuredDocuments Changes the name or description of documents using regular expressions.
setNewXmlDocumentGeneratedId Configures the automatic generation of ids when creating a new structured document. Both Automatic and Semi-automatic policies are available.

Settings include the seed and the pattern. The seed is a number to start ids with, which will increment for each new Id. The pattern allows you to add text to each new Id, and must contain {0}.

For example, if you enter:
  • seed = 4
  • pattern = id_{0,number,##########}

    The first new id will be id_4, the next will be id_5, etc.

Use this script in conjunction with setNewXmlDocumentIdMode.

See Configuring New XML Document Options

setNewXmlDocumentIdMode Controls the backstop value for requiring the user to specify a document id when creating a new structured document.
  • absent - the id field is will not be shown in the dialog
  • optional - the id field is available but is not required to be set
  • required - the id field is available and is required
  • semiautomatic - the id field is available, initialized with a generated value, and is required
  • automatic - the id field is displayed, initialized with a generated value, but not revisable.
Use this script in conjunction with setNewXmlDocumentGeneratedId.
Note: The specified template document must contain an id attribute on the root element for the Document Id field to be present in the dialog.
Note: You must restart the Workbench if you change this setting.

See Configuring New XML Document Options

setNewXmlDocumentTitleMode Controls the backstop value for requiring the user to specify a title when creating a new structured document.
Note: The specified template document must contain a title element as a first level child within the root element in order for the Document Title field to be present in the dialog.

See Configuring New XML Document Options

setNodeVisitorTransactionCount Controls the checkpointing frequency when processing structured documents. This is a balance between operation performance and interference with other user operations.
setOverrideBasedir Configures DITA-OT to use the override directory.
setParentApprovalFlavor Defines Bookmaps as the "ParentsExistingApprovals" document flavor. When the Add Snapshot dialog is displayed, the existing snapshot labels of parent documents that are bookmaps will be listed.
setPermissions Configures permissions for specified groups or roles on an object. Can change the visibility of Products icon in the Navigation view.. Specify a value of 1 to enable Release Management.

Can control whether workflow status is copied when documents are branched. See Preserving Workflow Status when Branching an Object.

Can define a named user (must be in the Administrators group) that is allowed to hold locks on objects without preventing merge operations to succeed. See Allowing a Merge When the Object is Locked to a Named User.

setRestrictedFileExtensions Configures whether files with specific filename extensions are either allowed or not allowed to be imported into the repository. By default, all filename extensions are allowed. Enter filename extensions (without the leading .) to identify restricted or allowed file types. You can also prevent files with no extension from being imported. The script displays the current list and prompts the administrator to designate the list type.

Updates are active automatically within an hour of invoking the script, or immediately upon restarting Astoria services on all ACS servers. Changes have no impact on files already residing in the repository.

setSendLinkOption When using the Publish > ViewLInk or Location Link commands, this setting controls the database default, the value for users who have not configured their own value. Options include prompting the user, putting the link on the clipboard, and launching the email client program.
setShowHistoryDisableDocumentMode Configures backstop value controlling if document mode is enabled on the show history dialog.
setSlowpokeInfo Controls the duration of jobs considered to be run in slowpoke mode.
setTopicrefAttributeBehavior Configures if and how topicref attributes are copied.
setupCoolbar Controls what coolbar items initially appear in a user's workbench.
setupDITALogging Configure where DITA-OT logging is written.
setupEditorCaching Configures the use of caches for some WAN editors.
setupFolderFormFlavors Registers/Unregisters flavored forms and folders.
setupMakeUniqueFolderItemNames Configures string patterns when copy or move operations would result in duplicate names in folders.
setupProfileFiltering Configures Profile filtering to use a particular webform.
setupSearchFilters Enables Search Filters.
setupThumbnailing Configures image thumbnails.
setupValidationOfDependents Configures the behavior of some WAN editors when saving data to the repository. Dependency validation can be set off, warning, or failure.
setupWebServicesClientExtensions Configures workbench customization.
setupWebServiceExtensions Configures server side customization.
setupWebServiceGranularity Configures frequency of transaction checkpointing to optimize performance while minimizing contention.
setupWorkbenchCommandExtensions Adds, lists, and deletes Workbench commands utilizing configuration information stored in the Astoria repository, not in jars deployed as part of Workbench startup.
setViewLinkOption Configures user and backstop option of behavior when a repository link is clicked in an email or browser.
setWaitTimes Configures how long to wait for a session before asking again.
setWhereUsed Configures if whereUsed for structured documents returns all structured documents that reference a part of the specified structured document or only those that directly reference some part of the specified structured document.
setXMLDocumentExtensions Displays or replaces the list of file extensions for XML documents. Files of these extensions, when encountered as references during import structured document processing will be parsed and create repository structured documents. See Configuring the Repository to Manage SVG Files as Structured Documents.
setXMLDocumentFlavors Enables registration of additional structured document flavors which are in addition to those which Astoria already configures. Enables replication of XML attribute values as custom attributes on xml documents upon checkin. See the topic Configuring Replicating XML Attribute Values as Custom Attributes on XML Documents in the ACS ICI Guide.