HELP DOCUMENTATION UMRA USER GUIDE

(1)

UMRA

U

SER

G

UIDE

(2)

Copyright © 2013, Tools4Ever B.V. All rights reserved. No part of the contents of this user guide may be

reproduced or transmitted in any form or by any means without the written permission of Tools4Ever.

DISCLAIMER - Tools4ever will not be held responsible for the outcome or consequences resulting from

your actions or usage of the informational material contained in this user guide. Responsibility for the

use of any and all information contained in this user guide is strictly and solely the responsibility of that

of the user.

(3)

UMRA Help 1

1. UMRA Basics

UMRA is a full blown enterprise solution for managing user accounts and all associated network resources. To benefit fully from UMRA’s features, you need a basic understanding of the application’s key concepts. These are briefly explained in this section. The first section, UMRA scripting, explains the architecture of an UMRA script and how it is used to define a specific user or network management task. Such a task can be the creation of a user account for instance, together with a home directory, home share, group memberships, Exchange mailbox, etc.

In UMRA projects, it is explained how one and the same UMRA project can be configured to use input data from various different sources.

UMRA Components provides an overview of the various software components that together make up the UMRA solution.

Finally, UMRA project management provides a brief definition of UMRA projects and workspaces.

1.1. Introduction

UMRA is a full blown enterprise solution for managing user accounts and all associated network resources. To benefit fully from UMRA’s features, you need a basic understanding of the application’s key concepts. These are briefly explained in this section. The first section, UMRA scripting, explains the architecture of an UMRA script and how it is used to define a specific user or network management task. Such a task can be the creation of a user account for instance, together with a home directory, home share, group memberships, Exchange mailbox, etc.

In UMRA projects, it is explained how one and the same UMRA project can be configured to use input data from various different sources.

UMRA Components provides an overview of the various software components that together make up the UMRA solution.

(8)

6

1.2. UMRA scripting

1.2.1. Scripts, actions and properties UMRA Script

An UMRA script is used to perform a specific user account or network management task. This can be the creation of a user account for instance, together with a home directory, home share, group memberships, etc. for a new user.

Script actions

An UMRA script is made up of one or more script actions. An UMRA script for the creation of new users for instance,may include a script action to create a user account in Active Directory and a second script action to create a home directory for the new user. All the script actions together define the project script.

Figure 1: An UMRA script contains one or more script actions

The available script actions are fixed, which means that you cannot create your own script actions. Most script actions are however highly configurable, and some are very general, so this hardly imposes a limit. UMRA comes with a wide range of script actions, covering virtually every aspect of user account and directory management.

(9)

UMRA Help

7 Figure 2: Sample of available script actions in UMRA

Apart from these standard script actions, there are also script actions available to perform some basic programming tasks, like evaluating a certain condition.

Script actions are added to the script by dragging a script action object from the list of actions and dropping it in the script pane of the project.

Script action properties

The script action properties of a script action provide information which specify in detail how a script action should be executed. In case of a Create User script action for instance, the following properties are included:

 Name of the domain where the user account should be created

 Name of the Organizational Unit to which the user belongs

 Common name, which is the full name of the user account.

This concept is shown in the figure below. The user’s common name has been specified here as “John Williams” in the CN script action property. This user should be created in the domain “Tools4ever.com”, which is specified by the domain script action property, in the organizational unit “Sales\USA” as specified by the OU script action property.

For each script action, the script action properties that need to be specified are different. If we take a look at another script action,

Create directory, the properties include the following information:

(10)

8

 Name of the user’s home directory

Figure 3: Specifying how a script action should be executed

1.1.1 Variables

Let’s return to the example shown in the previous Figure. You will note that the script action properties for these two script actions are all specified as fixed values. This script action will only be able to create the user “John Williams” in the OU “sales\USA” of the “tools4ever.com” domain. But what if you want to create another user or if you want to specify another OU or domain?

To make a script generic, UMRA makes use of variables instead of hard set values such as “John Williams” or “sales\USA”. These variables represent a real value. This is shown in figure 4.

Figure 4: Specifying script action property values using variables

The name of the user ‘John Williams’ is now replaced with the variable %Name%. The name of the variable is not really relevant since it is only used as a placeholder to store the real value. When the script is executed, the variables will be replaced with their actual values and the network will be updated accordingly. In UMRA, the name of a variable is always placed between percentage signs:

 %Name%

 %Domain%  %HomeServer%  Etc.

The actual value of a variable is obtained from the input data to which the variable is linked. These input data may come from a (CSV) file, information provided by the end user, a database, etc. This is explained in more detail in UMRA Projects on page 9.

(11)

UMRA Help

9 1.2 UMRA Projects

Each and every UMRA project contains at least a project script, which is the project’s core component. There are two key areas that determine the nature and possibilities of an umra project:

1. Input Specification: Where and how does a script get the information required for its operation? 2. Execution control: Where and when should the project and script be run to perform its operations?

Input Specification.

A script consist of a sequence of script actions. What exactly a particular script action does, depends completely on the contents of the particular script action's properties at run time. These in their turn are completely determined by the value of the variables that the script uses. There are many ways to specify the contents of these variables. The major methods are listed here.

Information is directly specified in the script

Some of the required information may be explicitly provided in the script itself when the script is run. For instance a script may use the script actions "set variable" to explicitly set a value for a certain variable.

Information is the result of an other script action

Many script actions query the network for certain information. The resulting information is often stored in variables that are used by other script actions further in the script.

Information is gathered from external sources before the script is executed

The required information may also (additionally) be gathered by the project from external sources before the script is executed. These options are:

File input data – the information the script needs to work with comes from a (CSV) file. The project will repeatedly execute its script, once with the information found in each (selected) line of the file.

Network input data - the information the script needs to work with comes from a network call, the script is executed once for each (selected) object found in a network query.

Form input data – the information the script needs to work with is entered or selected in a simple form. The form is created by the administrator using UMRA and delegated to a non-admin (e.g. Helpdesk employees). This category is therefore also known as Forms & Delegation..

Application input data – the information for the project script is provided by another information system or program. An example of this is the command line interface of UMRA, where the values entered on the command line specify the value of the variables used by the script.

In the following sections these categories will be described in more detail.

Execution Control

There are several options as to where and when a project and script can perform its operations, the major methods are listed here.

Directly by the console

The console application can be used as a stand-alone application that executes the projects in the security context of the administrative user that is currently logged on. In this case the projects are stored locally on the on the machine running the console. This is often used by a network administrator to perform mass modifications to the network, for instance in order to create new user accounts and associated data from information available in a .csv file. This option can be used with either file input or network input data.

The software module that runs projects in this fashion is for historical reasons often referred to as the "mass module", although the term "console" module probably is a better description since much of the mass features have since been ported to other parts of the software. Whenever the term "mass module" is used, it refers to projects directly run by the console, and NOT to mass-like features in other parts of the software.

By the scheduler of the UMRA service

Projects can be executed at scheduled times by the Umra service. The console application is used to configure the service, and to create the umra projects, that are stored and maintained by the UMRA service. All script actions run in the security context of the UMRA service.

This option can optionally be used with either File Input Data or Network Input Data.

(12)

10

An end user can use the UMRA Forms client to access forms located on the UMRA service to execute their associated scripts and actions. All scripts and actions are run with the security context of the Umra service. Access control to the different forms is provided by security settings (ACL) in UMRA on the individual forms.

The scripts and the security settings are created and configured by an administrator by means of the UMRA console application.

By the UMRA service, initiated from the "umracmd.exe" command line application

From the windows command line, "umracmd.exe" can be run to execute the script of an project that is maintained on the server. Variables that are required by the script are read from the command line. The script runs in the security context of the Umra Service account. Access control to the different scripts is provided by the Umra service by security settings in UMRA on the individual scripts.

The scripts and the security settings are created and configured by an administrator by means of the UMRA console application.

By the UMRA service, initiated from UMRA Com

Umra projects can also be executed programmatically by using the UMRA COM (Component Object Model) objects, that are distributed with UMRA. For instance the "umracmd.exe" application uses these objects to communicate with the Umra Service. These objects can be used in VB, VBSCRIPT, C++, ASP, and many other languages and environments to initiate the execution of UMRA Scripts. Often this is used to access UMRA functionality from within a web application.

File input data

The input data may come from a (CSV) file which can be imported into UMRA. In the following figure , a CSV file is shown containing the users’ first name, middle name, last name and phone number. The first line of the CSV file contains the column headers “FirstName”, “MiddleName”, “Lastname” and “Phone”. For each row, these columns hold different data.

Figure 5: File input data contained in a CSV file

When this file is imported into UMRA, these data are transformed into a table with the columns FirstName, MiddleName, LastName and Phone.

Script execution

In an UMRA project that takes its input from a file, the script will be executed for each line.

It is easy to see that the script action property values should be different for each processed row. When your project script includes a Create User action for instance, the Surname script action property should have for example the value “Addams” for row 2, “Anderson” for row 3, etc. Hard entering the name “Addams” in the Surname script action property, would result in 14 users with the name “Addams”. The solution is therefore to link the relevant column (in this case the Lastname column) to a variable (e.g. %Surname%) which can then be used to specify the value of the script action property.

This concept is illustrated in the figure below. The Surname property value has been linked to the %LastName% column. UMRA will now obtain the Surname property values from the %LastName% column.

(13)

UMRA Help

11 Figure 6: Linking inpiut data columns to property values

When the project script is executed, the variables will be replaced with their actual value as found in the linked column. This is illustrated in the figures. The %LastName% variable has been linked to the second column of the input data. When the first row is processed, the %LastName% variable is set to “Williams”, for the second row it is set to “Smith”, and so on.

(14)

12

Form input data

In this case, the UMRA project contains a script which takes its input from a form. Such projects can be used to delegate a specific user account management task, such as resetting a user’s password or creating user accounts. An example of a simple form is shown in figure 8.

Figure 8: Example of a form to create new user accounts

By specifying some simple information (in this case the user’s first, middle and last name) and clicking the action button Create

Account, a user account is created using the specified name.

Form layout

To design the form layout, the administrator can use various different form fields. A form field is an object which is included in the form to describe the purpose of the form, to collect user information or to change the form’s appeal:

 Descriptive form fields– the form field Static text field is used to explain the purpose of the form and the

individual form fields to the end user. Examples: form title, input box description (“Please enter the domain name”), etc.

 Interactive form fields – the form fields Input text box, Checkbox, Radio button and Table are used to cater

for interaction with the end user. Examples: Allowing the end user to enter the domain name in an input box, presenting a list of users in Active Directory which can be selected, etc.

(15)

UMRA Help

13

 Action button – When the end user clicks the action button, the entered or selected data are submitted.

Figure 9: Using form fields to design a form

1 Picture

2 Static text field (title) 3 and 5 Vertical spaces

4, 6, 7, 8, 9 Static text fields (description) 10, 11, 12 Input boxes

(16)

14

Script execution

The interactive form fields (input box, radio buttons, checkbox, table column) of a form can be associated with a variable. These variables can be used by the project script. When the user clicks the action button, the project script will be executed, replacing the variables with the values entered or selected in the form.

Figure 10 – Execution of a project script taking its input from a form

In case of the Create User example shown in figure 10, the information which the end user has entered in the form for for the user’s first name, middle name and last name is associated with the variables %FirstName%, %MiddeName% and

%LastName%:

 %FirstName% = John  %MiddleName% = F.  %LastName% = Johnson

The project script includes the script action Create User (AD). This script action holds, amongst others, the script action properties Given-name, Initials and Surname. The values for these script action properties have been specified using the variables %FirstName%, %MiddleName% and %LastName%.

As soon as the end user hits the action button Create Account, the specified data “John”, “F” and “Johnson” are submitted and the project script is executed, substituting the variables %FirstName%, “MiddleName% and %LastName% with “John”, ‘F.” and “Kennedy” respectively. As a result, the network resource is updated.

Application input data

An UMRA project may also contain a script only which takes its input from other applications. This kind of integration, where other applications can use UMRA functionality, is achieved by using the Component Object Model (COM). This technology was developed by Microsoft to allow applications to interact with eachother. The most important Microsoft applications that support COM are:

 Internet Information Services  Office applications

All applications supporting COM use some kind of programming or script language to implement COM (ASP, VB(S), etc.). The procedure used is always the same:

1. The COM object is created;

(17)

UMRA Help

15

3. Returned variables can be processed in the application.

An application can use multiple COM objects and COM objects can use other COM objects. UMRA COM

User Management Resource Administrator contains several COM objects. With the UMRA COM objects registered, UMRA functions can be used within the ASP(X)/VB(A) script to execute an UMRA project and to read and process the project variables.

Script execution

The UMRA project script is executed by the UMRA server as instructed by the COM object. All variable names and values that are required to execute the UMRA project script, must be specified by Using the COM object. Usually, the values are taken from the application that uses the UMRA COM objects.

(18)

16 1.3 UMRA components

The UMRA solution contains several different software components.

These individual software components will be briefly described in this section.

UMRA Console

The UMRA Console is the main application for the administrator. The UMRA Console is used to build the actual user account or network management solution :

 develop and test UMRA project scripts. The UMRA Console comes with a wide range of script actions to build a project script and many testing facilities to test the script before it goes live in an operational environment;

 specify input data to be used in combination with the project script;

 set the security settings which specify who is allowed to execute the project script and form;  structure UMRA projects;

 setup the UMRA Service (explained in the next section);

Projects can be developed to be run by the UMRA service, or local projects can be developed to be directly run by the console. Projects that require forms, scheduling or are initiated by means of the UMRA COM, can only be executed by the UMRA service, but are developed using the UMRA Console application.

UMRA Service

Except for local UMRA projects that are executed directly by the UMRA console, all UMRA projects are stored on the UMRA

Service.

The UMRA Service performs the following tasks:  Maintains the UMRA projects

 Verifying access privileges of the currently logged-in user to check if the user is allowed to execute the project script;  Executing the project script.

 contains a scheduler for the scheduled execution of project scripts

 Interfaces with the UMRA COM component so that external applications can initiate the execution of project scripts

UMRA Forms client

The UMRA Forms client is a windows application that is used to access and fill in forms maintained by the UMRA service. This client is used by non-admins to connect to the UMRA Service. It presents the user with a list of names of those UMRA projects he is entitled to use. When a project is selected, the form of the project is presented to the user. The user can fill in the form and send it to the service, which executes the project script, using the specified information in the form. If the project requires more information, it can present additional forms. It can also present additional forms to report information to the user.

UMRA COM

UMRA COM is a software component which is used to integrate UMRA functionality with other applications such as IIS

(SharePoint). UMRA COM holds a variety of functions that can be used within a script (e.g. ASP(X)/VB(A) ) to execute an UMRA project and to manage the UMRA project variables.

UMRA command line

This software component is a command line interface that uses the UMRA COM object to execute an UMRA project maintained by the UMRA service.

This makes it possible to start a specific umra project from the Windows command line

1.4 UMRA project management

A user or network account management solution in UMRA can become very complex. To help you to structure your solution, UMRA offers a very flexible project management environment.

(19)

UMRA Help

17

UMRA projects

In its simplest form, an UMRA project contains a project script only. Depending on the kind of solution you require, additional information can be added which should be used by the project script:

 file input data – user information contained in a (CSV) file can be imported into UMRA. During the import, these data

are transformed into a table. The columns can be linked to a variable and used in the project script. This is covered in detail in the section File input data on page 10 of chapter UMRA Projects on page 9.

 network input data – instead of providing user information in a file, you can also make a network selection.

 form - The form is the template which the administrator creates for the non-admin to perform a specific user account

management task. The data specified by the end user can be linked to variables and used in the project script. This is discussed in detail in the section Form input data on page 12 of chapterUMRA Projects on page 9.

 security settings - for all projects which are maintained by the UMRA Service, you need to specify who is allowed

to execute the project form and / or project script.

For UMRA, there can be three different kinds of user accounts:

User account with Description

Full control These user have access to push forms to the UMRA service,

setup, delete, manage all forms, project scripts and security settings. The number of user accounts with this type of access should obviously be very limited.

Form access only These users can see and submit a form. When such a user

connects to the UMRA service using the UMRA Forms client, the form is presented to them. The user can then specify the various fields of the form and let the UMRA service execute the script of the form project. The accounts can be configured for each individual form.

No access These users can connect to the UMRA service but no projects will

be shown.

UMRA workspaces

Projects are contained in a workspace, which is a collection of one or more UMRA projects. By using a workspace it is easier to open all relevant projects at the same time.

UMRA XML project and script files

UMRA can store UMRA projects and scripts in XML format. The XML files are human-readable and can for instance be used to copy (parts) of projects from one UMRA installation to another. The UMRA XML format is available with the following functions:

1. Main menu, File, Import project (xml): The function allows you to import an UMRA XML project files. This project file can contain either a UMRA Service (Forms and Automation) of UMRA Console (Mass) project;

2. Main menu, File, Export project (xml): Exports the current active project to an UMRA XML project file.

3. Project workspace, Script window, context sensitive menu: Import script (xml and .usc): Import the UMRA script from the specified XML file. The script is imported at the current location of the UMRA script. The XML project file can contain either an UMRA XML project or UMRA XML script.

4. Project workspace, Script window, context sensitive menu: Export script actions (xml): Export the current selection of UMRA script actions to an UMRA XML script file. The result file can be used to import the script actions in another UMRA script.

5. UMRA Service, Manage service projects, Import: Imports one ore more UMRA XML project files.

(20)

18

7. UMRA Service, Manage service projects, Backup: Creates a directory with a name containing the date-time and UMRA build number, and stores all UMRA Service projects as UMRA xml project files in the directory

(21)

UMRA Help

19

2. Getting Started

UMRA has been developed as a broad solution for managing Active Directory and other directory services. It covers the following user management areas:

 Mass updating network resources - UMRA offers administrators a fast and reliable solution for implementing bulk

changes in network and associated resources. UMRA should be used for small to large migration projects and is an alternative for manual actions or complex scripting. The user data UMRA needs to work with can be obtained in many different ways (e.g. as a result of a database query or a CSV file containing, for instance, the user's First Name, Last name and Middle Name). Using built-in script actions, you can mass create new user accounts in Active Directory, together with Exchange e-mail accounts, home directories, (random) passwords, dial-in permissions, Windows Terminal Server settings, global group memberships, and profile directories.

 Delegation of user management tasks to non-admins - UMRA offers administrators the option to delegate user

account management tasks to non-administrative users within the organization (e.g. helpdesk employees). Administrators can define a delegation project consisting of of secure forms to handle a specific user management task such as resetting passwords, creating and deleting user accounts, disabling accounts, moving accounts (cross-domain), etc. These forms can be delegated to non-administrative users. Using forms, it is also possible to delegate management of other resources such as Windows computer services and printer queues.

 Linking network resources to other information systems - UMRA offers the possibility of linking network resources to

other information systems, such as a link between an HR system and Active Directory. In a scenario where an employee leaves the company for instance, the corresponding user account in Active Directory can be automatically disabled. This automation option provides unrivalled flexibility and eliminates the need for scripting solutions entirely.

 Integration of network resources with (self service) web portals - companies using a web portal can integrate the

UMRA features with their intranet by simply adding web pages for specific user management tasks. Different options can be made available, depending on the user's role within the organization. When HR employees log into the intranet for example, they can be offered a page to create new users in Active Directory. Similarly, an IT manager can be offered a list of disabled users and authorize the deletion of disabled user accounts.

This document will guide you through the various UMRA software modules covering these user management areas. When you have finished this guide, you will be able to install UMRA and create a user management solution yourself.

(22)

20

2.1. Introduction