Administration and Management(4.2)

Owned by Jenni Wallin
Last updated: Aug 15, 2024
16 min read

Desktop Background Color

You can start several Desktop applications on a specific computer. To tell the difference between the applications and their respective views you can vary the background color of every Desktop. To change the Desktop application background color, set the Desktop property mz.gui.color.space.active.

The value can be any color of the following: blue, green, yellow, orange, red, darkblue, darkgreen, magenta, or darkred. For further information about Desktop properties, see Starting and Managing Desktop Client (4.2).

Dynamic Update

While a real-time workflow is being executed, you can change the value of the following parameters:

  • The Host and Port parameters of the TCP/IP agent

  • The NAS list of the Radius agent

To be able to dynamically update TCP/IP Host and Port parameters, you need to set them to either Default or Per Workflow in the Workflow Properties dialog box. See the figure The Workflow Table Tab in Workflow Table Tab (4.2).

To update, select Dynamic Update from the Edit menu. On the title bar of the monitor dialog-box, the text Dynamic Update followed by a number appears. It represents the number of times that you have updated the workflow configuration while running it, that is since the last time you started it.

Folders

Folders enable the user to categorize configurations, and simplify their maintenance and operation. Folders could for instance be created based on traffic type, decoding for a specific network element, as well as being based on geographic location etc.

Usage Engine includes a system folder named Default. This folder cannot be renamed nor removed.

Configuration Naming

Configuration names within a folder must be unique.

Some named items in the Usage Engine environment are used when constructing file names. To avoid potential conflicts in the file systems, Usage Engine converts the illegal characters when constructing the file names.

The following characters are considered to be legal. Any other character will result in a validation error.

  • a-z

  • A-Z

  • 0-9

  • - (dash)

  • _ (underscore)

Usage Engine has an internal key for every configuration. This key is used to identify the configuration. Renaming a configuration will not change this key. The key is constructed using the system name and the date when the configuration was created. You can view the generated key by selecting the Show Properties option in the right-click menu in the Configuration Navigator, as well as in the Configuration Browser and Configuration Tracer.

Date and Time Format Codes

In various places in Usage Engine, date formats are entered. The following list shows valid date and time format codes that can be combined with any characters that are not in the ranges of 'a'-'z' and 'A'-'Z'. For instance, characters such as ':', '.', ' ', '#' and '@' will appear in the resulting time even if they are not specified within single quotation marks.

The date syntax conforms to the Java class SimpleDateFormat. This section contains a summary only. For a full description see:

https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/text/SimpleDateFormat.html

Letter

Date or time component

Example

Letter

Date or time component

Example

G

Era designator

AD

y

Year

1996; 96

M

Month in year

July; Jul; 07

w

Week in year

27

W

Week in month

2

D

Day in year

189

d

Day in month

10

F

Day of week in month

2

E

Day in week

Tuesday; Tue

a

am/pm marker

PM

H

Hour in day(0-23)

0

k

Hour in day(1-24)

24

K

Hour in am/pm (0-11)

0

h

Hour in am/pm (1-12)

12

m

Minute in hour

30

s

Second in minute

55

S

Millisecond

978

z

Time zone

PST; GMT-08:00

Z

Time zone

-08:00

Example - Date and time patterns are interpreted in the U.S. local

The following examples show how date and time patterns are interpreted in the U.S. local. The given date and time are 2001-07-04 12:08:56 local time in the U.S. Pacific Time time zone.

Format

Example

Format

Example

"yyyy.MM.dd G 'at' HH:mm:ss z"

2001.07.04 AD at 12:08:56 PDT

"EEE, MMM d, ''yy"

Wed, Jul 4, '01

"h:mm a"

12:08 PM

"hh 'o''clock' a, zzzz"

12 o'clock PM, Pacific Daylight Time

"K:mm a, z"

0:08 PM, PDT

"yyyyy.MMMMM.dd GGG hh:mm aaa"

02001.July.04 AD 12:08 PM

"EEE, d MMM yyyy HH:mm:ss Z"

Wed, 4 Jul 2001 12:08:56 -0700

"yyMMddHHmmssZ"

010704120856-0700

Text Editor

At various places in the Usage Engine environment, editable text areas are available in order to enter APL code. To assist in writing the code, these areas host functions available in a pop-up menu that is displayed when you right-click anywhere in the text area.

The menu has the following options:

Option

Description

Option

Description

Font Size

Sets the font size.

Cut

Moves the selected text to the clipboard.

You can also press the CTRL+X keys to perform this action.

Copy

Copies the selected text to the clipboard.

You can also press the CTRL+C keys to perform this action.

Paste

Pastes the contents of the clipboard into the place where the insertion point has been set.

You can also press the CTRL+V keys to perform this action.

Select All

Selects all the text.

You can also press the CTRL+A keys to perform this action.

Undo

Undoes your last action.

You can also press the CTRL+Z keys to perform this action.

Redo

Redoes the last action that you undid with Undo.

You can also press the CTRL+Y keys to perform this action.

Find/Replace...

Displays a dialog where chosen text may be searched for and, optionally, replaced.

You can also press the CTRL+H keys to perform this action.

Find/Replace dialog

Quick Find

Searches the code for the highlighted text.

You can also press the CTRL+F keys to perform this action.

Find Again

Repeats the search for last entered text in the Find/Replace dialog.

You can also press the CTRL+G keys to perform this action.

Go to Line...

Opens the Go to Line dialog where you can enter which line in the code you want to go to. Click OK and you are redirected to the entered line.

You can also press the CTRL+L keys to perform this action.

Show Definition

If you right-click a function in the code that has been defined somewhere else and select this option, you are redirected to where the function has been defined.

If the function has been defined within the same configuration, you jump to the line where the function is defined. If the function has been defined in another configuration, the configuration opens and you jump directly to the line where the function has been defined.

You can also click a function and press the CTRL+F3 keys to perform this action.

Note!

If you have references to an external function with the same name as a function within the current code, some problems may occur. The Show Definition option will point to the function within the current code, while the external function is the one that is called during workflow execution. 

Show Usages

If you right-click a function where it is defined in the code and select this option, a dialog called Usage Viewer opens and displays a list of the Configurations that are using the function.

You can also select a function and press the CTRL+F4 keys to perform this action.

UDR Assistance...

Opens the UDR Internal Format Browser from which the UDR Fields may be inserted into the code area.

You can also press the CTRL+U keys to perform this action.

 MIM Assistance...

Opens the MIM Browser from which the available MIM Resources may be inserted into the code area.

You can also press the CTRL+M keys to perform this action.

Import...

Imports the contents from an external text file into the editor. Note that the file has to reside on the host where the client is running.

Export...

Exports the current contents into a new file to, for instance, allow editing in another text editor or usage in another Usage Engine system.

Use External Editor

Opens the editor specified by the Desktop property mz.gui.editor.command, e g "notepad.exe".

APL Help...

Opens the APL Reference Guide.

APL Code Completion

Performs code completion on the current line. For more information about Code Completion, see the section below, APL Code Completion.

You can also press the CTRL+SPACE keys to perform this action.

Indent

Adjusts the indentation of the code to make it more readable.

You can also press the CTRL+I keys to perform this action.

Jump to Pair

Moves the cursor to the matching parenthesis or bracket.

You can also press the CTRL+SHIFT+P keys to perform this action.

Toggle Comments

Adds or removes comment characters at the beginning of the current line or selection.

You can also press the CTRL+7 keys to perform this action.

Surround With

Adds a code template that surrounds the current line or selection:

  • for Loop (CTRL+ALT+F)

  • while Loop (CTRL+ALT+W)

  • Debug Expression (CTRL+ALT+D)

  • if Condition (CTRL+ALT+I)

  • Block Comment (CTRL+ALT+B)

APL Code Completion

In order to make APL coding easier, the APL Code Completion feature will help you find and add APL functions and their respective syntax.

To access APL Code Completion, place the cursor where you want to add an APL function, press CTRL+SPACE and select the correct function. To reduce the number of hits, type the initial characters of the APL function. The characters to the left of the cursor will be used as a filter.

APL Code Completion covers:

  • All installed APL functions.

  • Function blocks such as beginBatch and consume.

  • Condition statements such as while and if.

  • APL functions created by APL Code configurations.

  • APL functions created with the Development Toolkit.

APL Code Editor Outline

In order to make it easier to navigate in an APL code configuration, there is an Outline navigation panel to the right of the APL Code Editor.

The APL Code Editor Outline provides a view of all the blocks, variables and methods in an APL code configuration and makes it possible to easily navigate between different types in the APL code. The entries in the navigation panel are automatically updated as you make valid entries in the APL Editor.

You can also filter what you want to display in the Outline navigation panel. You can search for a specific block, variable or method using the free text field, or by selecting one of the quick filter buttons for different types:

Button

Description

Button

Description

b

Click to display or hide the blocks within the APL code configuration displayed in the APL Code Editor.

v

Click to display or hide the variables within the APL code configuration displayed in the APL Code Editor.

m

Click to display or hide the methods within the APL code configuration displayed in the APL Code Editor.

The Outline navigation panel can be hidden or made visible. By default, it is visible and all the elements are displayed. To hide or display the navigation panel, click the vertical Outline button to the right of the APL Code Editor.

Configuration List Editor

The Configuration List Editor appears in many Agent Configuration dialog boxes and usually looks like the example in the figure below, Configuration List Editor. This table enables you to select and list several entries that you want to include in a certain Configuration definition.

Button

Description

Button

Description

Add

Click to open a dialog box where you can add an item to the Configuration list.

Edit

Select a row and click Edit; an Update dialog box opens and enables you to modify the data entry.

Remove

Select a row and click Remove.

Select an entry from the Configuration list and click Up or Down to move it to an upper or lower position

Note!

To change the order of any of the appended rows from ascending to descending, or vice versa, click a column's heading. The new order is not saved for the next time you open this view.

UDR Browser

In places where one or many UDR types or UDR fields will be selected, the UDR Browser is utilized. See the figure below, UDR Internal Format Browser. You access the UDR Internal Format Browser from the Analysis or Aggregation agents, by right-clicking in the APL Code area and selecting UDR Assistance... .

The browser contains all UDR types available in the system:

  1. UDR types created in the Ultra Format Editor. These include events and sessions for the Aggregation sub-system.

  2. UDR types installed with the system.

For further information about UDR types and fields, see Ultra Format (4.2).

 

Item

Description

Item

Description

UDR Types

List of available UDR types ordered in a tree structure.

You can search for a specific UDR type using the filter text box. You can also expand all of the folders to display all the subfolders and types by clicking the Expand button. You can collapse the folders again by clicking the Collapse button. If you click the Refresh button, the view is refreshed and the folders are collapsed.

Formats created in Ultra Format Editor usually have the following structure:

folder name - configuration name - internal type name

Expand All

Click this button to expand all of the UDR Types folders to display all the subfolders and types.

If you click the Refresh button, the view is refreshed and the folders are collapsed.

Collapse All

Click this button to collapse the UDR Types folders so that only the folders are displayed.

UDR Fields

Displays the UDR type fields in a tree structure.

You can search for a specific UDR type field using the filter text box. To refresh the view, click the Refresh button.

To ease identification, the fields are color coded:

  • Optional - Italic black

  • Read-only - Red

  • Default - Blue

  • Nested UDRs - Gray

Show Optional

If enabled, fields declared as optional are displayed in black italic text.

Show Readonly

Select this check box to display read-only fields; the text appears in red.

Datatype

If enabled, only fields that match the selected data type are displayed. 

Selection Modes

The browser operates in five modes depending on where it is utilized.

  1. Single selection of UDR Type. You can choose the UDR Type either by double-clicking the UDR Type, or by selecting it followed by OK or Apply. OK and double-click dismisses the dialog.

  2. Multiple selections of UDR Type. You can choose several UDR Types at once by selecting them followed by OK or Apply. OK or double-click dismisses the dialog.

  3. Single selection of UDR fields. Same as for UDR Type, but fields are selected instead.

  4. Multiple selections of UDR field. Same as for UDR Type, but fields are selected instead.

  5. Field input assistance. You can insert fields in the target text field by double-clicking them, or by selecting them followed by Apply. The OK button is not available.

MIM

Some agents in a workflow need information from the workflow or other agents in order to operate. For instance, an agent that produces a file might need the source file name and the number of processed UDRs to be used in the outgoing file name. In order to satisfy these requirements,  Usage Engine uses a model called Meta Information Model (MIM) .

Agents may use MIM parameters to publish information during run-time that other agents may need to use. The MIM information is used in various parts of Usage Engine, for instance, when selecting which MIM resources to use in a file name.

Usage Engine uses Java Management Extensions (JMX) to monitor MIM tree attributes in running workflows. For more information, see Workflow Monitor (4.2).

MIM resources for each agent have their values assigned at any time, depending on type. For example, the Disk collection agent publishes the MIM resource Source Filename which is set at Begin Batch. The agent puts the name of the collected file in this resource before it starts collecting the file.

There are in total four types of MIMs:

MIM Type

Description

MIM Type

Description

Batch

Batch MIMs are dynamic values, populated during batch processing. An example of such a value is outbound UDRs.

Global

A global MIM value can be accessed at any time during the execution phase of a workflow. For instance, static values such as Agent Name.

Header

Header MIM values are populated when a batch is received for processing (an agent emits Begin Batch). For example Source Filename (published by the Disk collection agent).

Trailer

Trailer MIM values are populated after a batch is processed (an agent emits End Batch). An example of such a value is Target Filename (published by the Disk forwarding agent).

By default, all agents may publish the following MIM resources depending on their Input/Output data types.

MIM Parameter

Description

MIM Parameter

Description

Agent Name

This MIM parameter contains the name of the agent as defined in the workflow editor. All agents publish this resource. The value is set when the workflow starts executing.

Agent Name is defined as a global MIM context type.

<route name> UDRs (or Bytes)

This MIM parameter contains the number of UDRs (or Bytes) routed on the link by the agent. The value is updated continuously during processing. This MIM is not valid for forwarding agents.

<route name> UDRs (or Bytes) is defined as a batch MIM context type.

<route name> Queue Size

This MIM parameter contains the number of objects that are currently in the route's queue.

<route name> Queue Full Count

This MIM parameter contains the number of queue state changes and the value is updated each time a route's queue enters "full" state. 

Inbound UDRs (or Bytes)

This MIM parameter contains the number of incoming UDRs (or Bytes) since last Begin Batch. The value is updated continuously during batch processing. This MIM is not valid for collection agents.

Inbound UDRs (or Bytes) is defined as a batch MIM context type.

Outbound UDRs (or Bytes)

This MIM parameter contains the number of outgoing UDRs (or Bytes) since last Begin Batch. The value is updated continuously during batch processing. This MIM is not valid for forwarding agents.

Outbound UDRs (or Bytes) is defined as a batch MIM context type.

There are also pico specific MIM resources representing information about the picos' JVMs. These are:

MIM Parameter

Description

MIM Parameter

Description

Available CPUs

This MIM parameter states the number of processors that are available for the JVM.

Available CPUs is defined as a global MIM context type.

System Load Average

This MIM parameter states the average system load during the last minute. The system load is the sum of the number of runnable entitites that are queued or running on the available processors, and this value shows the average of this sum for the last minute. This information is useful for indicating the current system load and may be queried frequently.

System Load Average is defined as a global MIM context type.

Heap Memory Used Percentage

This MIM parameter states JVM's heap size, i e the amount of memory that is currently used by the JVM, in percent.

Heap Memory Bytes Usedn is defined as a global MIM context type.

Non Heap Memory Used Percentage

This MIM parameter states the amount of memory outside of the heap (non-heap memory) that is currently used by the JVM, in percentage.

Non Heap Memory Bytes Used is defined as a global MIM context type.

There are workflow specific MIM resources representing information of a running workflow as well. These are:

MIM Parameter

Description

MIM Parameter

Description

Batch Cancelled

This MIM parameter states if the current batch has been cancelled.

Batch Cancelled is defined as a header MIM context type.

Batch Count

This MIM parameter contains a unique sequence number that will be associated with each batch processed by the workflow. This value is increased by 1 up to 263 and is saved between workflow invocations.

Batch Count is defined as a header MIM context type.

Batch Duration

This MIM parameter contains the time it took to process a batch. This value is updated during processing.

Batch Duration is defined as a batch MIM context type.

Batch End Time

This MIM parameter contains the end time for the processing of a batch.

Batch End Time is defined as a trailer MIM context type.

Batch Start Time

This MIM parameter contains the start time for the processing of a batch.

Batch Start Time is defined as a header MIM context type.

Execution Context

This MIM parameter contains the name of the Execution Context hosting the current workflow.

Execution Context is defined as aUntitled global MIM context type.

Processed UDRs Interval Duration

This parameter contains the duration of an interval in minutes for counting the number of processed UDRs in the current real-time workflow. This MIM parameter is only valid for real-time workflows.

Processed UDRs Intverval Duration is defined as a global MIM context type.

Processed UDRs Per Interval

This parameter contains the UDRs processed during the defined interval in the current real-time workflow. This MIM parameter is only valid for real-time workflows.

Processed UDRs Per Intverval  is defined as a global MIM context type.

Start Time

This MIM parameter contains the date and time when the workflow was started. The value is set when the workflow is activated.

Start Time is defined as a global MIM context type.

Threads Configured

This parameter contains the number of workflow threads configured in the current real-time workflow. This MIM parameter is only valid for real-time workflows.

Threads Configured is defined as a global MIM context type.

Threads Idle

This parameter contains the number of workflow idle threads in the current real-time workflow. This MIM parameter is only valid for real-time workflows.

Threads Idle is defined as a global MIM context type.

Throughput

By default, Throughput is the volume-per-time processing rate of a particular workflow or agent.

Transaction ID

Each batch closed by all workflows will receive a unique transaction ID, cancelled batches as well. This MIM parameter contains the unique transaction ID.

Transaction ID is defined as a header MIM context type.

Workflow ID

This MIM parameter contains the unique identification name of every workflow.

Workflow Name

This MIM parameter contains the name of the current workflow. The value is set when the workflow is activated.

Workflow Name is defined as a global MIM context type.

MIM Browser

At places where access to MIM resources is used, the MIM Browser is utilized. You access the MIM Browser from the Analysis or Aggregation agent, by right-clicking in the APL Code area and selecting MIM Assistance....

The browser contains all MIM resources available in the workflow.

The available MIM resources are displayed, ordered in a tree structure. You can choose the MIM resource either by double-clicking the MIM resource, or by selecting it followed by Apply. Cancel dismisses the dialog. You can also search for a specific MIM resource using the filter text box at the top of the MIM Browser.

Locks

Configurations that you edit are locked so that they cannot be modified by other users. When you open a locked configuration, a message box appears with information about the user that has access and can edit it. To edit a locked, or read-only, configuration you can save a copy of it with a different name.

A locked configuration 

Locks are not persistent. If the system is restarted, all locks will be forgotten.

Encryption

A configuration in Usage Engine is persisted using XML and therefore more or less available in a readable form to any user, see Browser (4.2). Some configurations may be sensitive and possibly contain descriptions that are proprietary and must be protected. To protect such configurations, Usage Engine features the ability to encrypt configurations using a passphrase. A configuration is thereby only readable if the passphrase is known by the user. If the passphrase is lost, the configuration should be considered lost as well.

There are configurations that generate information to the system. For example, the Ultra format that renders UDRs. A user can have access to the UDRs without knowing the passphrase for the configuration source, by setting the user group execute permission. A user can also import a format or analysis package which has execute permission configured.

Encrypted configurations retain their encryption and passphrase across export and import. This means that to open a configuration that is imported from another system, you need its passphrase.

The Database profile and some of the agents can use passwords from External References. These can be encrypted, either using the default key, or using a crypto service keystore file. See Using Passwords in External References in External Reference (4.2) for further information.