Automation Engine 11

ONE Automation Platform

Best Practices Guide

Version: 11.2.2
Publication Date: 2016-10
Automic Software GmbH
ii     Copyright

Copyright
Automic® and the Automic logo® are trademarks owned by Automic Software GmbH (Automic). All such
trademarks can be used by permission only and are subject to the written license terms. This
software/computer program is proprietary and confidential to Automic Software and is only available for
access and use under approved written license terms. 

This software/computer program is further protected by copyright laws, international treaties and other
domestic and international laws and any unauthorized access or use gives rise to civil and criminal
penalties. Unauthorized copying or other reproduction of any form (in whole or in part), disassembly,
decompilation, reverse engineering, modification, and development of any derivative works are all strictly
prohibited, and any party or person engaging in such will be prosecuted by Automic.

No liability is accepted for any changes, mistakes, printing or production errors. Reproduction in whole or
in part without permission is prohibited.

© Copyright Automic Software GmbH. All rights reserved.

 Automation Engine iii

Contents
1 Dos & Don'ts in Automation Engine 1

2 Test and Production System 2

3 Two-Installation Environment 4

Notes 4

III. Combine with a Proxy 6

4 Security in AE Systems 8

5 Controlled Computer Restart 9

6 Assigning and Using Values 11

7 Useful Calendar Keywords 14

Glossary 16

A 16

C 16

D 16

G 16

I 17

J 17

P 17

R 17

S 18

T 18

U 18

V 18

W 18
1 | Chapter 1 Dos & Don'ts in Automation Engine

1 Dos & Don'ts in Automation Engine

Automic strongly recommends keeping the following in mind in order to make best use of your AE system.

Dos

l Run an AE system for production plus a test system.

l Use an authorization system, encryption and authentication in order to ensure secure processing.
l Regularly maintain the AE database using the available utilities and database processes.
l Use AE's object orientation in order to keep your processing steps well structured.
l Store Calendar objects centrally in order to make them accessible for all tasks.
l Use Include objects in scripts wherever applicable.
l Check return codes for potential errors in all processing steps.

Don'ts

l Do not directly modify AE database contents without using AE programs.

l Do not implement modifications and extensions without prior planning.
l Do not use newly created or modified jobs, workflows etc. in your production system without
checking the test system beforehand.
l Do not assign object names without an adequate naming structure.
l Do not select non-descriptive names for objects, agents, script variables etc.
l Do not divert AE functions from their intended use.
l Do not activate traces without being assisted by the Automic Support team.
 Chapter2 Test and Production System | 2

2 Test and Production System

Guidelines for using AE

General
An AE system is an environment which can be handled and monitored with AE. This includes components
such as the Automation Engine and agents, their computers, applications and processing which can be
defined via objects.

We strongly recommend working with three AE systems. The first system serves to plan and create the
objects which represent your processes (development system). A second AE system should be used to
test all processes. The third one is used to execute your daily business processes (production system).

There is a clear philosophy behind this three-system environment. You business processes are extremely
important. Simply changing or adding workflows or system settings might put them at risk. Thus, they
must be tested in a separate system environment before they can be used for productive operation.

Three-System Environment
The following illustrations show how the three AE systems work together:

In the production system, you can use a separate client for the development system.

Test and production system must be physically separated in any case. This ensures that new procedures
can be tested without putting your business processes at risk.
Partition means:
3 | Chapter 2 Test and Production System

l Two AE systems
l Each AE system has its own Automation Engines, agents, etc.
l Both systems use different computers.
l Both are equipped with the same hardware and software (OS, database, third-party software etc.)
l Optimally, the AE systems run in different networks.
l The same authorizations and AE settings (variables, INI files etc.) apply for both systems.
l The test system has the same objects as the production system.

The test system should be as far as possible identical to the production system.

These settings ensure that newly created jobs are tested under productive conditions. The impact of
modifications can be optimally tested in a test system. Updates to new Automation Engine versions,
operating systems and databases can be carefully planned and tested with the most obvious advantage
still being that your production system is not put at risk. Improvements and modifications are only
transferred to the production environment after extensive testing.

Maintaining Your AE Systems

Regularly check compliance with the above rules and maintain the AE database on a regular basis using
AE's utilities and the relevant database-specific tools.

Objects can easily be transferred between the different AE systems using the Transport Case. As
opposed to imports, the Transport Case has been designed to transport numerous objects to an AE
system. Extensive tests in the test system are always recommended before objects are transferred to the
production system.

Analyze the log files of all AE systems. This is also possible in an automated form using a job that filters
particular keywords (such as "error") with the script element PREP_PROCESS_FILE.

See also:

Upgrading an AE System
 Chapter3 Two-Installation Environment | 4

3 Two-Installation Environment
Setting up a two-installation environment for the Zero Downtime Upgrade is the best practice in order to
have a base and a target installation ready to upgrade and test properly.

Notes
The ZDU is available as of v11.2 of the Automation Engine, therefore the following instructions refer to
that version as lowest possible base version.

In the documents pertaining to the ZDU, all references to base and target installation also mean base
and target version.

Two special modes exist for this upgrade function, the compatibility mode and the parallel mode.
Compatibility mode: This mode is started as soon as you choose the option BEGIN from the ZDU
wizard.
In this mode, which is in effect until you choose the option FINALIZE, certain system optimization
functions are not available. Also system performance will be reduced noticeably.
Parallel mode: A mode during the upgrade when base and target version processes are active at the
same time.

Whenever you upgrade your system, Automic strongly recommends using a test system for extensive
testing before installing upgrades on your production system.

General
In order to be able to seamlessly upgrade the Automation Engine without any downtime, using the Zero
Downtime Upgrade function, you have to set up two separate installations.
They serve to ensure that a base and target version are available for conducting the upgrade and testing
the proper running of tasks and jobs in the target version.
As base and target version CPs/WPs will be active during the parallel mode, you have to set up two
separate installations in separate bin directories.

Initially both installations will be the same. In the course of the upgrade one of them will be upgraded to the
target version, whereas the other (base) installation will subsequently be shut down, as soon as all
processes and tasks run satisfactorily in the target version.

These may be two installations on:

1. the same host (recommended)

2. two separate hosts

You can use 1. or 2. with a Proxy, details you find below.

The two alternatives can be realized using either two (new) AE installations or an existing AE installation,
by duplicating it.
5 | Chapter 3 Two-Installation Environment

I. Two-Installation Environment - Two Separate

Installations
1. Set up two installations of the AE system you want to upgrade from (v11.2 or higher).
a. Use either the same host and set up two separate installations.
b. Alternatively use two separate hosts and separate installations.
2. The installation that will be used as target version needs to be set up with the Automation Engine
directory and Utility directory only. Those are needed for upgrading.
3. The INI and configuration files of these two core components in the target version installation
have to contain the same configuration information as the ones in the base version installation.
4. You also have to configure double the amount of ports than are usually necessary for the correct
working of an AE system.
a. These ports have to be known to any clients that are going to connect to a CP, therefore
enter them either in the INI or the configuration files.
This is necessary, because at some point during the upgrade base and target version
CPs have to be active in the parallel mode at the same time.
5. Start the ZDU by starting the base version installation and the ZDU there.

Advantages:

l Using this kind of setup lets users continue their work without being disconnected.
l Agents can be phased out successively and connect to the new CPs.

Disadvantages:

l Setting up the system this way requires a little more preparation time at first.
l Additional ports are necessary, which have to be configured in Firewall and existing Proxies.
l All ports have to be known by all existing clients before you start the upgrade.

II. Two-Installation Environment - Duplicate an Existing

Installation
You will reuse the files of an existing AE installation, following these steps:

1. You have to use two separate bin directories, in which the INI and configuration files of the
Automation Engine bin directory and the Utilities bin directory will be contained.
2. Create a bin directory for the contents of the Automation Engine folder and the Utilities folder,
respectively, in a location of your choice.
3. Copy and paste all files from those two folders in the existing installation to the respective folders in
the new location.
This second location and the new folders there represent the target version installation for the
ZDU process.
4. Start the original installation and start the ZDU.

Advantage:

l Less time needed for configuring ports, as no additional ports are necessary.

Disadvantages:

l Shutting down CPs results in agents and users connected to those CPs being disconnected.
l System performance will be reduced to half of its usual amount.
 Chapter3 Two-Installation Environment | 6

III. Combine with a Proxy

You can execute the ZDU by using the most hassle-free solution and run a Proxy.

The Proxy combines and reroutes CP connections, while agents just connect to the Proxy, using the ports
or port ranges configured in it.

1. You have to set up one of the installation variants explained above, use a two-installation setup or
duplicate your existing installation.
2. Configure the second installation in the Proxy accordingly.
3. The Proxy will then reroute connections to either the base or target version CPs, as necessary.

Advantages:

l You do not have to configure any additional ports, either in the two-system environment or the split
system environment.
l The connections will be taken care of by the Proxy so that agents will be connected to whatever
system and CPs are active and in use, be it base or target system.

Illustration 1: Proxy-based two-system environment solution

7 | Chapter 3 Two-Installation Environment

See also:

Upgrading an AE System
 Chapter4 Security in AE Systems | 8

4 Security in AE Systems
How to protect your AE system with utmost security.

Measures
AE provides several functions which all serve to protect your AE system from unauthorized access:

l Use the highest possible encryption strength AES-256.

l Use the authentication method "Server and Agent".
l Deactivate the compatibility function.
l Use the authorization system and do not grant more AE system rights and privileges to users than
they really need.

Also use your intra-company security measures to achieve utmost security.

l Protect access to your Server rooms.

l Act with caution when assigning access rights to computers and files.

See also:

Advanced Security
Authorization System
9 | Chapter 5 Controlled Computer Restart

5 Controlled Computer Restart

Guideline for a monitored computer shutdown and start.

General
Daily processing means that numerous tasks are executed on your hosts day and night. Running tasks are
aborted if a computer shuts down unexpectedly. In order to avoid negative impacts, Automic recommends
preparing the agent for shutdowns and restarts.

Preparations
The following basic rules apply:

1. Ensure that no tasks are active when you shut down the computer.
2. Execute a workflow that processes finishing tasks shortly before you shut down.
3. Tasks should not start immediately after the agent has started.
4. Instead, execute a workflow that processes some preparatory tasks.

The following objects and configurations are required in order to implement these criteria:

1. The host characteristics include two settings that can be used to allow or prevent the start of tasks
on an agent. These settings are WORKLOAD_MAX_FT and WORKLOAD_MAX_JOB. Jobs or file
transfers do not start if the value "0" is specified in both of them. They wait until a positive value is
specified. You can do so using the script statement :SET_UC_SETTING. Create two Script
objects and specify the value "0" in one of them and a positive number or "UNLIMITED" in the other
one. Use a script variable in order to assign the agent name to the statement :SET_UC_SETTING.
In doing so, you can use the created Script objects for any number of agents.
2. Create two workflows. One serves to process finishing tasks before the computer is shut down and
the other one should be executed immediately after the computer has been restarted in order to
process some preparatory tasks. Use the function MODIFY_UC_OBJECT in the scripts of both
workflows in order to set them to "Ignore Agent Resource". This step is required because no other
tasks must run at this time. "Ignore Agent Resource" then applies to all objects that are started by
these two workflows.
3. Ensure that no tasks are active before starting the finishing workflow. Create an Event object that
uses the script function SYS_ACTIVE_COUNT in order to check in an interval of several minutes if
there are active tasks on the agent. Activate this event before you shut the computer down. It starts
the finishing workflow as soon as there are no active tasks on the agent or activates a notification if
there are tasks that have not finished at this point in time. In both cases, the event can end itself
using the script function CANCEL_UC_OBJECT.
4. Create a separate AE agent variable for the host characteristics. This variable can also be used for
several agents. The variable UC_EX_HOSTCHAR assigns them to the corresponding host
characteristics. Set the default value for the host characteristics' validity keys WORKLOAD_
MAX_FT and WORKLOAD_MAX_JOB to "0" in order to prevent that tasks start immediately when
the agent has been restarted. Enter the name of the workflow that should first be executed in the
option EXECUTE_ON_START. This workflow's final task must activate a script which sets a
higher value than "0" for the settings WORKLOAD_MAX_FT and WORKLOAD_MAX_JOB in order
to ensure that the regular processing of tasks can start.
 Chapter5 Controlled Computer Restart | 10

Procedure
Before shutting down the computer:

l Process the script that prevents the start of further tasks.

l Start the event that checks whether tasks are running.
l Activate the finishing workflow if there are no more active tasks.

After starting the computer:

l Only the introductory workflow is activated when the agent has been started due to the
configurations of the host characteristics.
l This workflow's last task is to start the script that releases task processing for this agent.
11 | Chapter 6 Assigning and Using Values

6 Assigning and Using Values

Guideline for using values

Various values are used in objects. They serve to specify the host on which jobs run, the files which
should be processed, the type of reaction to events etc. An advantage of AE's object orientation is that
these values can be dynamically set and processing can be controlled by the particular situation.

AE provides several ways of storing values and assigning them to other objects.

Variable Objects
Values that are relevant for many tasks are stored in static Variable objects. A client's objects can access
their contents and modify them using script elements.

The following illustration shows a static Variable object. It already contains the variable "HOST" with value
"unix01".

Example:

The responsible administrator is entered in the Variable object using the script statement :PUT_VAR. The
host name is changed to "unix02".
:PUT_VAR "DB_MAINTENANCE", "ADMIN", "Smith"
:PUT_VAR "DB_MAINTENANCE", "HOST", "unix02"
A task reads the host name using the script function GET_VAR:.
:SET &HOST# = GET_VAR("DB_MAINTENANCE", "HOST")
The script statement :DELETE_VAR deletes the host specification from the Variable object:
:DELETE_VAR "DB_MAINTENANCE", "HOST"
 Chapter6 Assigning and Using Values | 12

Object Variables
Values that are only relevant for individual tasks are stored directly in the object. Almost all executable
objects contain a Values tab which can be used to enter variables that should be used in the Process
tabs. These values can be used directly as script variables.

The following screenshot shows the object variable "&HOST#".

This variable can be immediately used in the script. The following example uses the object variable to
terminate the agent.
:TERMINATE ,&HOST#
There is a peculiarity which applies to object variables. They can be inherited from the superordinate
object. For example, tasks of a Schedule can use the object variables of its Schedule. This simplifies
maintenance because it is no longer necessary to store the values in all individual objects.

Input Buffer
Values relevant for a task that is started using ACTIVATE_UC_OBJECT can be stored in an input buffer.
This is done using the script statement :PUT_READ_BUFFER . The task reads the stored values with the
script statement :READ.

Example:

A job puts the name of its agent to the input buffer and then calls a notification:
:SET &att_host# = GET_ATT(HOST)
:PUT_READ_BUFFER host# = '&att_host#'
:SET &ret# = ACTIVATE_UC_OBJECT('CALLOP')
Notifications can read agent names:
:READ &host#,,
13 | Chapter 6 Assigning and Using Values

:PRINT "Agent: &host#"

 Chapter7 Useful Calendar Keywords | 14

7 Useful Calendar Keywords

Even if a company uses many company-specific calendar dates, there are some dates which are generally
helpful. The following Calendar object provides a collection of typical calendar keywords which can be
useful when processing tasks.

Weekly
Name Description
MONDAY, TUESDAY, WEDNESDAY, THURSDAY, Each individual day of the week is stored as
FRIDAY, SATURDAY, SUNDAY an individual calendar keyword.
WEEKDAYS_MON_TO_FRI Contains all Mondays, Tuesdays,
Wednesdays, Thursdays and Fridays
WEEKEND Contains all Saturdays and Sundays

Monthly
Name Description
15 | Chapter 7 Useful Calendar Keywords

FIRST_DAY_OF_ Contains the first day of a month

MONTH
Select day "1" in the calendar definition and the option Count the days from
the beginning of the month.
LAST_DAY_OF_ Contains the last day of a month
MONTH
Select day "2" in the calendar definition and the option Count the days from
the end of the month.

Yearly
Name Description
QUARTER_1, QUARTER_2, There is a calendar keyword for each quarter.
QUARTER_3, QUARTER_4
Select In a defined interval in the calendar definition and specify
the quarter's start and end date (e.g.: 01.01. until 31.03).

Group
Name Description
WORKDAYS Contains all weekdays from Monday to Friday except holidays

Select the calendar keyword WEEKDAYS_MON_TO_FRI in the calendar definition.

Enter the holiday calendar of your country (e.g. UC_HOLIDAYS.US with the
keyword TOTAL) in the setting AND none of the following Calendars apply.

Roll
Name Description
FIRST_ Contains the first workday of each month
WORKDAY_
Select the source calendar keyword LAST_DAY_OF_MONTH. Select adjust by
OF_MONTH
"+1" day. Specify the calendar keyword WORKDAYS for the option use valid
days from.
LAST_ Contains the last workday of each month
WORKDAY_
Select the source calendar keyword FIRST_DAY_OF_MONTH. Select adjust by
OF_MONTH
"-1". Specify the calendar keyword "WORKDAYS" for the option use valid days
from.
 Chapter Glossary | 16

Glossary
This glossary lists all specific technical terms in alphabetical order.

ABCDEFGHIJKLMNOPQRSTUVWXYZ

A
l ARA Client
Refers to a computer on which a ARA/Deployment Manager/Automation Engine user works.
l admin computer
Admin computer refers to the computer that is used by an administrator for e.g. Automation Engine
or database administration purposes.

C
l configuration
A set of constituent components that make up a system. This includes information on how the
components are connected including the settings applied.

D
l Download Center
The Download Center (http://downloads.automic.com/) is the place where you find everything you
need to know about your Automic solution to make sure you are using our products to their fullest
potential.
l database
A database is an organized collection of data including relevant data structures.
l department
Department name to which the Automation Engine user belongs.

G
l graphical user interface
A graphical user interface (GUI) is a human to machine interface based on windows, icons and
17 | Chapter Glossary

menus which can be operated by a computer mouse in addition to a keyboard. In contrast to

command line interface (CLI).

I
l ILM
Stands for Information Lifecycle Management, which refers to a wide-ranging set of strategies for
administering storage systems on computing devices.

J
l Java work process
The Java work process, implemented in Java, is used to host special services, which have been
developed in Java.

P
l package module
A package module is a group of related package types, e.g. Feature, Change Request, or Bug. It
defines how the packages are displayed in the GUI and the features enabled for each package type.
l password
A secret combination of characters for a Automation Engine user.

R
l RichClient
Deprecated Term. Replaced by: UserInterface
l rollback scope
The scope of a workflow to roll back. For a rollback on a job the scope is this single task while for a
rollback on a workflow the scope is this workflow and all sub-workflows in arbitrary depth.
 Chapter Glossary | 18

S
l Service Manager
The Service Manager serves to start, stop and access components such as the Automation Engine
processes or agents from a central point.

T
l token
A token is used for authentication within a session between a client and a server. A (soft) token is a
unique identifier which is generated and sent from a central server to a client software. The client
uses the token to authenticate each request.

U
l user name
Name of the Automation Engine user.

V
l vSphere
vSphere is a virtualization platform for building cloud infrastructures by VMware.

W
l web application
A web application is an application that is accessible over a network (Internet or intranet) and is
typically coded in a programming language like Java or JavaScript, combined with a markup
language like HTML. Web applications are provided on web servers and web browsers are used as
GUI on client computers.