filter Command

Filters limit the objects or relationships displayed in browsers to those that meet certain conditions previously set by you or your Business Administrator. For example, you could create a filter that would display only objects in a certain state (such as Active), and only the relationships connected toward each object (not to and from). When this filter is turned on, only the objects you needed to perform a specific task would display.

This page discusses:

User Level

Business Administrator

Syntax

The command uses this syntax. 

[add|copy|modify|delete|list|print] filter NAME {CLAUSE};
  • NAME is the name of the filter you are defining.
  • CLAUSEs provide additional information about the filter.

Add Filter

To define a new filter from within MQL, use the Add Filter command.

Syntax

add filter NAME [user USER_NAME] [ADD_ITEM {ADD_ITEM}];
  • USER_NAME can be included with the user keyword if you are a business administrator with person access defining a filter for another user. If not specified, the filter is part of the current user’s workspace.
  • ADD_ITEM specifies the characteristics you are setting.

When assigning a name to the filter, you cannot have the same name for two filters. If you use the name again, an error message will result. However, several different users could use the same name for different filters. (Remember that filters are local to the context of individual users.)

After assigning a filter name, the next step is to specify the conditions (ADD_ITEM) that each object must meet in order to display when the filter is turned on (activated). The following are Add Filter clauses: 

[!|in|notin|not] active
 
appliesto businessobject|relationship
 
from|to|both 
type TYPE_PATTERN 
name PATTERN 
minorrevision REVISION_PATTERN 
vault PATTERN 
owner PATTERN 
where QUERY_EXPR 
[!|not] hidden
 
visible USER_NAME{,USER_NAME};
 
property NAME on ADMIN [to ADMIN] [value STRING]

Appliesto Clause

This clause indicates that the filter applies to business objects or relationships.

Direction Clause

This clause indicates the direction of the relationships to which the filter applies: to, from, or both.

Type Clause

This clause assigns a filter for a particular type of business object or relationship. 

type TYPE_PATTERN

  • TYPE_PATTERN defines the types for which you are assigning a filter.

The Type clause can include more than one type using multiple values to define the pattern. The Type clause can also use wildcard characters. For example, the following definition displays a filter to display all customers and other users: 

add filter “Customers and Other Users” type customer,user;

When listing multiple values as part of a pattern, separate each value with a comma and no spaces, or enclose any multi-word type value within quotation marks (for example, "new customer",user). If you include spaces, the value is read as the next part of the filter definition. For example, the following Type clause would produce an error because MQL reads the type as “new” and the next specification for the filter as “customer”. 

type new customer;

Name Clause

This clause assigns the names of objects to include in the filter. 

name PATTERN
  • PATTERN is the names of objects to include in your filter.

The Name clause can include more than one name using multiple values to define the pattern. The Name clause can also use wildcard characters. For example, the following definition adds a filter to display all business objects with names that start with “Inter”, or include the letters “IBM”, or include the words “International Business Machines”: 

add filter “IBM” 
name Inter*,*IBM*,”International Business Machines”;

When listing multiple values as part of a pattern, separate each value with a comma and no spaces, or enclose any multi-word type value within quotation marks (for example, “International Business Machines”). If you include spaces, the value is read as the next part of the filter definition, as described in the Type clause.

Minorrevision Clause

This clause assigns a filter for a particular revision of business objects. 

minorrevision REVISION_PATTERN
  • REVISION_PATTERN defines the revision for which you are assigning a filter.

The Minorrevision clause can include more than one revision value and wildcards as in the other clauses that use patterns. Typically, you might use a wildcard, but would not include more than one or two revisions. Filtering by the latest revision number or all revisions A and B can remove much of the out-dated business objects from view. This allows you to work with only the most current objects.

The Minorrevision clause can also use wildcard characters. For example, the following definition displays a filter to display all parts of revision 1 or 2: 

add filter “Revised Parts” 
type Parts
minorrevision 1,2;

When listing multiple values as part of a pattern, separate each value with a comma and no spaces, or enclose any multi-word type value within quotation marks (for example, “status new”,”status old”). If you include spaces, the value is read as the next part of the filter definition.

Vault Clause

This clause assigns a filter for business objects that are in a particular or similar vault: 

vault PATTERN
  • PATTERN defines the vaults for which you are assigning a filter.

The Vault clause can use wildcard characters. For example, the following definition displays a filter for all business objects that reside in the “Vehicle Project” vault: 

add filter “Vault Search”
   appliesto businessobject
   vault “Vehicle Project”
   owner *;

Copy Filter

You can modify any filter that you own, and copy any filter to your own workspace that exists in any user definition to which you belong or that is defined as visible to you. As an alternative to copying definitions, you can use the set workspace command to make your workspace look like that of another user. Business Administrators can change their workspace to that of another user to work with filters that they do not own.

After a filter is defined, you can clone the definition with the Copy Filter command. Cloning a filter definition requires Business Administrator privileges, except that you can copy a filter definition to your own context from a group, role or association in which you are defined.

This command lets you duplicate filter definitions with the option to change the value of clause arguments: 

copy filter SRC_NAME DST_NAME [COPY_ITEM {COPY_ITEM}] [MOD_ITEM {MOD_ITEM}];
  • SRC_NAME is the name of the filter definition (source) to be copied.
  • DST_NAME is the name of the new definition (destination).

COPY_ITEM can be:

COPY_ITEM Specifies
fromuser USERNAME USERNAME is the name of a person, group, role or association.
touser USERNAME
overwrite Replaces any filter of the same name belonging to the user specified in the touser clause.

The order of the fromuser , touser and overwrite clauses is irrelevant, but MOD_ITEMS, if included, must come last.

MOD_ITEMS are modifications that you can make to the new definition. For more information, see Modify Filter.

Modify Filter

Use the Modify Filter command to add or remove defining clauses and change the value of clause arguments. 

modify filter NAME [user USER_NAME] [ITEM {ITEM}];
  • NAME is the name of the filter you want to modify. If you are a business administrator with person access, you can include the user clause to indicate another user’s workspace object.
  • ITEM is the type of modification you want to make. With the Modify filter command, you can use these modification clauses to change a filter:
    Modify Filter Clause Specifies
    active The active option is changed to specify that the object is active.
    notactive The active option is changed to specify that the object is not active.
    appliesto businessobject |relationship The appliesto option is changed to reflect what the filter now affects.
    from|to|both The direction of the filter is changed.
    type TYPE_PATTERN The type is changed to the named pattern.
    name PATTERN The name is changed to the named pattern.
    revision REVISION_PATTERN The revision is changed to the named pattern.
    vault PATTERN The vault is changed to the pattern specified.
    owner PATTERN The owner is changed to the pattern specified.
    where QUERY_EXPR The query expression is modified.
    hidden The hidden option is changed to specify that the object is hidden.
    nothidden The hidden option is changed to specify that the object is not hidden.
    add visible USER_NAME{,USER_NAME}; The object is made visible to the other users listed.
    add property NAME [to ADMINTYPE NAME] [value STRING] The named property is modified.
    add property NAME [value STRING] The named property is added.
    remove property NAME [to ADMINTYPE NAME] [value STRING] The named property is removed.

These clauses are essentially the same ones that are used to define an initial filter except that Add property and Remove property clauses are substituted for the Property clause. When making modifications, you simply substitute new values for the old.

Although the Modify filter command allows you to use any combination of criteria, no other modifications can be made except the ones listed. To change the filter name or remove the filter entirely, you must use the Delete filter command and/or create a new filter.

Delete Filter

If a filter is no longer needed, you can delete it using the Delete filter command. 

delete filter NAME [user USER_NAME];
  • NAME is the name of the filter to be deleted. If you are a business administrator with person access, you can include the user clause to indicate another user’s workspace object.

This command searches the local list of existing filters. If the name is found, that filter is deleted. If the name is not found, an error message results. For example, assume you have a filter named “Overdue Invoices” that you no longer need. To delete this filter from your area, you would enter the following MQL command: 

delete filter “Overdue Invoices”;

After this command is processed, the filter is deleted and you receive the MQL prompt for the next command.

When a filter is deleted, there is no effect on the business objects or on queries. Filters are local only to the user’s context and are not visible to other users.