webreport Command

[add|copy|modify|evaluate|temporary|list|print|
delete|link] webreport NAME {CLAUSE};

• NAME is the name of the webreport you are defining. If you are a business administrator with person access, you can include the User clause to indicate another user’s workspace object. (By default the webreport is added to the current workspace.)
• CLAUSEs provide additional information about the webreport.

Syntax

add webreport NAME [user USER_NAME][ADD_ITEM {ADD_ITEM}];

• NAME is the name of the webreport you are defining. If you are a business administrator with person access, you can include the User clause to indicate another user’s workspace object. (By default the webreport is added to the current workspace.)
• ADD_ITEM is an add webreport clause that provides additional information about the webreport. The add webreport clauses are:

  description STRING_VALUE

  appliesto | businessobject | | relationship | | both |

  searchcriteria STRING

  notes STRING

  reporttype STRING

  [!|not] checkaccess

  groupby EXPR_ITEM

  data EXPR_ITEM

  summary | NAME [APPLIESTO] SUM_ITEM {SUM_ITEM} | | all [APPLIESTO] |

  visible USER_NAME{,USER_NAME}

  [!|not]hidden

  property NAME [to ADMIN] [value STRING]

Appliesto Clause

Include this clause to indicate if the webreport collects statistics on business objects, relationships, or both. The default is business object. For example:

add webreport UsedParts appliesto both;

The ability to report on relationships as well as or instead of business objects is applicable only when SEARCHCRITERIA is an expand. (When SEARCHCRITERIA is not an expand, no relationships are returned, so there are none to evaluate against.) In an expand, the information desired could be some summary of data from the relationships found and not the end objects. Or it could be you need more than one statistic and that one is properly obtained from the objects and the other from the relationships.

In addition to an overall appliesto flag for the webreport, a webreport’s groupbys, datas, and summaries can use this flag. Their flags are only relevant (and looked up) if the appliesto flag for the entire webreport has the value “both”.

Searchcriteria Clause

SEARCHCRITERIA is defined recursively as one of:

set NAME

query NAME

temp set OBJECTID [{,OBJECTID}]

temp query businessobject TYPE NAME REVISION [TEMP_QUERY_ITEM {TEMP_QUERY_ITEM }]

expand [EXPAND_ITEM {EXPAND_ITEM}]

[( {( }]SEARCHCRITERIA [ ){ )}]

• TEMP_QUERY_ITEM is one of:

  owner NAME

  vault NAME

  [!|not]expandtype

  where WHERE_CLAUSE

  limit NUMBER

  size NUMBER

  over SEARCHCRITERIA

  querytrigger

  For more information, see Temporary Query.

• OBJECTID is the Type Name and Revision of the business object.
• EXPAND_ITEM is one of:

  from

  to

  type PATTERN {,PATTERN}

  relationship PATTERN {,PATTERN}

  fixed points ID [,Id]

  withroots

  filter PATTERN

  activefilters

  reversefilters

  view NAME

  limit NUMBER

  size NUMBER

  recurse [to | N |]

  recurse to |all|

  [into|onto] set NAME

  SELECT_BO

  where WHERE_CLAUSE

  SELECT_REL

  DUMP

  The values of EXPAND_ITEM have the same meaning in this context as they have for the Expand Business Object with these exceptions:

  • In the case of “select,” it indicates whether a subsequent Where clause applies to business objects or to relationships. In expand bus select has an additional meaning that is not applicable here.
  • Leaf can be used with recurse in a SEARCHCRITERIA expand to specify that only “leaf” nodes of the expand should be returned. What counts as a leaf node differs depending on whether “recurse to all” or “recurse to n” is issued. In the “all” case, a leaf node is one that has no further connected objects that satisfy the criteria. With a recursion level N indicated, the leaf nodes consist of the same objects as recurse to all, PLUS all objects on level N.

    Leaf is not allowed in the expand bus command, but is allowed here.

An “expand” searchcriteria does not make sure that returned objects are unique. That is, any objects that are connected more than once to the object(s) being expanded (or recursed to) will be listed more than once. This affects webreports, eval expression, and other commands using searchcriteria. For example, the following might return a list containing duplicate entries:

MQL<18>eval expres "count TRUE" on ( expand bus t2 t2-1 0 );

To avoid the duplication, you could change the searchcriteria to the following:

temp query * * * over expand bus t2 t2-1 0

SEARCHCRITERIAs can be linked with binary operators, which follow simple, intuitive rules:

• and: an object is in both collections
• or: an object is in one or the other collection
• less: an object is in the result if it is in the left-hand collection but not the right-hand one.

If there is more than one binary operator in a SEARCHCRITERIA, parentheses must be used to disambiguate the clause. (There is no implied order of operations.) You must include a space before and after each parenthesis. In addition, the number of left and right parentheses must match each other. For example:

( set A + set B ) - set C

would probably evaluate differently than:

set A + ( set B - set C )

Notes Clause

This clause is used to store a string of any length. It is designed for use by applications to store any information they need to maintain with the webreport. (Of course, properties could be used, but they are limited to no more than 255 characters.) For example, the Business Metrics application stores data in the notes field that is required to update the JSP page used to create a webreport with values used to evaluate the webreport.

Reporttype Clause

This clause can be used to store a string up to 255 characters.

Notcheckaccess Clause

This clause indicates if show and read access should be checked when the webreport is evaluated; that is, when the data expressions are evaluated. There are two reasons you might want to turn off these accesses:

• Checking access can be a big performance penalty.
• Turning off the access checking allows the counting and summarizing of data on objects that cannot otherwise be seen or read; that is, objects to which you don’t have show or read access are included in the statistics returned.

The default is that read and show access are checked (for show, that’s assuming show access is on).

This option does not control what happens when the business objects or connections found by a webreport result are printed, which can be done with options in “evaluate webreport” and “temp webreport”, as well as through a Select clause in “print webreport”. In that case, show and read access will apply as they normally do regardless of this setting.

Groupby Clause

This clause is used to define a hierarchy of the data in the results of a webreport. A groupby has one expression, which is either a string or a pointer to an expression object. A webreport can have any number of groupbys.

The expression used with groupby should be an expression that applies to a single business object or connectio . All of the groupby expressions will be evaluated against each object found by the search criteria. The values of these evaluated expressions will be used to organize the objects into a number of subsets. There will be one subset for each unique combination of groupby values after evaluating them all across all the objects.

For example, suppose the attribute Priority can take on values 0,1,2,3 and the attribute Material can take on values Metal, Wood, Rubber, Plastic, Other. Then, if the webreport includes these groupby expressions:

groupby value 'attribute[Priority]' 
groupby value 'attribute[Material]' 
data value 'average attribute[Cost of Rework]'

The expression could result in as many as 20 distinct subsets, corresponding to the 20 unique combinations of (Priority, Material), and it would report the average Cost of Rework for the objects in each of those ~20 subsets. The term 'cell' is used to refer to these subsets in the webreport selectables described below.

The Maxgroupings N clause limits the number of subsets created for distinct values of this groupby expression to be no greater than N. It will keep the subsets which have the largest number of associated objects, and will create an additional 'other' subset of the remaining objects.

The objects returned by the search criteria are grouped by the values of the first groupby expression, then sub-grouped by values of the second groupby expression, and so on to separate the objects into their appropriate cells. Each groupby can have a label associated with it, and the labels need not be unique. The groupby syntax is one of:

groupby [APPLIESTO] object EXPR_NAME [label STRING] [maxgroupings N];

groupby [APPLIESTO] value STRING [label STRING] [maxgroupings N];

• Where APPLIESTO is a valid Appliesto Clause. The appliesto setting of the groupby is only looked at if the Appliesto clause on the entire webreport is “both.”

For example:

add webreport UsedParts groupby value current label Status groupby object 
WhereUsedExpression label “Used In”;

Data Clause

This clause has the same syntax as the Groupby clause:

data [APPLIESTO] object EXPR_NAME [label STRING];

data [APPLIESTO] value STRING [label STRING];

• APPLIESTO is a valid Appliesto Clause. The appliesto setting of the data is only looked at if the Appliesto clause on the entire webreport is “both.”
• Each data can have a label associated with it, and the labels need not be unique.

However, the expressions used with data clauses are those appropriate for evaluation on a collection of business objects or connections (called “collection expressions”), such as averages, sums, standard deviations, and so on. For more information, see expression CommandEach data clause has one expression, which is either a string or a pointer to an expression object. A webreport can be defined with any number of data clauses.

Each data expression is evaluated against each of the subsets determined by the search criteria together with the groupbys. To evaluate the data expressions against combinations of these subsets, such as the entire collection or with some groupby ignored, summaries should be created. For more information, see Summary Clause.

For example:

data value dateperiod ym (maximum (current.actual));

Summary Clause

A webreport can include a list of uniquely named summaries. A summary specifies a subset of the datas and groupbys of the webreport, which allows you to collapse groupings and report on only a subset of the datas.

Use the Summary clause of the add webreport command to specify the summaries. The syntax is:

summary | NAME [APPLIESTO] SUM_ITEM {SUM_ITEM} |  
        | all  [APPLIESTO]                     |

• APPLIESTO is a valid Appliesto Clause. The appliesto setting of the summary is only looked at if the Appliesto clause on the entire webreport is “both.”
• Where SUM_ITEM is one of:

  groupby INDEX{,INDEX}

  data | INDEX{,INDEX}| | all |

• INDEX specifies one of the webreport’s groupbys or datas indicated by order added to the summary. The first groupby (and data) added has an index of 1, with the last one added having an index of the total number of groupbys (or datas).
• If “summary all” is specified, a summary is created for every possible subset of groupbys and each summary will have all data expressions. You cannot use “summary all” when the number of groupbys is more than 8.
• You can indicate “data all” when you list a subset of groupbys.

For example, using the example above with groupbys on Priority and Material, you could specify a Summary report with ignores the Material groupby to report the average Cost of Rework by sorting by Priority alone:

 summary groupby 1 data 1

The 1’s refer to the first groupby and first data expressions defined for this webreport.

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

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

copy webreport SRC_NAME DST_NAME [COPY_ITEM {COPY_ITEM}] [MOD_ITEM {MOD_ITEM}];

• SRC_NAME is the name of the webreport 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 webreport 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 Webreport.

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

modify webreport NAME [user USERNAME][MOD_ITEM {MOD_ITEM}];

• NAME is the name of the webreport 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.
• MOD_ITEM is the type of the modification you want to make. You only need specify the fields to be modified.

  Modify Webreport Clause	Specifies
  name NEW_NAME	The current webreport name is changed to the new name entered.
  description VALUE	The current description value, if any, is set to the value entered.
  APPLIESTO	The webreport applies to the new setting - business objects, relationships or both.
  searchcriteria STRING	The search criteria is changed to STRING.
  notes STRING	The notes are changed to STRING.
  reporttype STRING	The report type is changed to STRING.
  [!|not]checkaccess	The checkaccess setting is changed as indicated.
  summary NAME MOD_SUM_ITEM {MOD_SUM_ITEM} where MOD_SUM_ITEM is: | APPLIESTO | | add | groupby | INDEX | | | data | | | remove | groupby | INDEX | | | data | |	The named summary is modified as specified.
  add summary | NAME [APPLIESTO] SUM_ITEM {SUM_ITEM} | | all [APPLIESTO] |	The new summary is added as specified.
  remove summary NAME	The existing summary is removed.
  copy result to archive	The existing evaluation result is saved in an archive.
  copy archive INDEX to result	The specified archive is copied to the current evaluation result, thereby overwriting any existing one.
  result ARCHIVE_ITEM {ARCHIVE_ITEM} where ARCHIVE_ITEM is: | label NAME | | description VALUE | | remove objects | | [un]lock | | [!|not]hidden |	The current evaluation result is modified as indicated.
  archive INDEX ARCHIVE_ITEM {ARCHIVE_ITEM}	The specified archive is modified as indicated.
  remove result	Deletes the existing results.
  remove archive INDEX	Deletes the specified archive results.
  remove archive all	Deletes all archive results.
  remove archive label PATTERN	Deletes all archive results that fit the label PATTERN.
  append | groupby EXPR_ITEM | | data EXPR_ITEM |	New groupby or data is added to end of list (index is total number of groupbys or datas). EXPR_ITEM is a valid definition of the groupby or data.
  add groupby INDEX EXPR_ITEM	New groupby is added with index as specified. EXPR_ITEM is a valid definition of the groupby.
  remove groupby INDEX{,INDEX}	Groupbys listed by index are removed.
  add data INDEX EXPR_ITEM	New data is added with index as specified. EXPR_ITEM is a valid definition of the data.
  remove data INDEX{,INDEX}	Datas listed by index are removed.
  add visible USER_NAME{,USER_NAME}	Named users are added to visible list so they can use the webreport.
  remove visible USER_NAME{,USER_NAME}	Named users are removed from visible list so they can no longer use the webreport.
  [!|not]hidden	The webreport hidden setting is set as specified.
  property NAME [to ADMINTYPE NAME] [value STRING]	The named property is modified.
  add property NAME [to ADMINTYPE NAME] [value STRING]	The named property is added.
  remove property NAME [to ADMINTYPE NAME] [value STRING]	The named property is removed.

Each modification clause is related to the arguments that define the webreport. To change the value of one of the defining clauses or add a new one, use the Modify clause that corresponds to the desired change.

Syntax

evaluate webreport NAME [user USER_NAME][EVAL_ITEM {EVAL_ITEM}]
 [OUTPUT_ITEM {OUTPUT_ITEM}];

• NAME is the name of the webreport you are evaluating.
• You can include the user USER_NAME clause to clarify to which workspace the webreport belongs. (By default USER_NAME is assumed to be the current context user.)
• You can evaluate the webreport as defined, or you can specify EVAL_ITEMs to override settings in the defined webreport. The EVAL_ITEMs are:

  count

  no count

  data INDEX{,INDEX}

  summary NAME{,NAME}

  no data

  no summary

  objects [select SELECT_ITEM{,SELECT_ITEM}]

• OUTPUT_ITEMs can be included to specify how to handle the results. The clauses include:

  [unlock] save [SAVE_ITEM {SAVE_ITEM}]

  xml

  output FILENAME

  separator STRING

  groupbyseparator STRING

  • SAVE_ITEM is:

    | label NAME | | description VALUE | | archive | | objects | | lock |

No Count Clause

By default, a count of the objects that meet the search criteria is included when the webreport is evaluated. Include no count to remove it from the webreport’s results.

[No] Data Clause

Include the Data clause in the evaluate webreport command to include only the results of the webreports datas specified with INDEX. Include no data to remove all datas from the webreport’s results.

[No] Summary Clause

Include the Summary clause in the evaluate webreport command to include only the webreport summary specified with NAME. Include no summary to remove all summaries from the webreport’s results.

Objects Clause

Include the Objects clause in the evaluate webreport command to return the list of business object ids that meet the search criteria, in addition to the webreport results. Include Select clauses in brackets to return this information about the objects found.

Save Clause

Include the Save clause to save the results in the database. You can include any of the archive subclauses, including label, description, archive, and objects. If save is issued without archive, the results are saved as “the result.”

If you use archive, the computed results are stored as an archive, rather than as the result. The difference between the result and an archive is in how you read or manipulate them.

You can also lock or unlock the results. When the result is locked it cannot be overwritten without unlocking it.

XML Clause

Include the xml clause so that the output is formatted as xml.

Separator Clause

Include the Separator clause to specify how fields are separated in the results. The separator is used to separate a list of groupby values from the count and data values in a given line of output.

Groupbyseparator Clause

Include the Groubyseparator clause to specify how groupby output is separated in the webreport results. The groupby separator is used to separate groupby values.

temp webreport [TEMP_ITEM {TEMP_ITEM}];

The TEMP_ITEMs are:

searchcriteria STRING

[!|not]checkaccess

groupby EXPR_ITEM

data EXPR_ITEM

ADD_SUMMARY

count

objects [select SELECT_ITEM{,SELECT_ITEM}]

separator STRING

groupbyseparator STRING

xml

output FILENAME

If a webreport is no longer required, you can delete it using the delete webreport command

delete webreport NAME [user USERNAME];

• NAME is the name of the webreport 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 list of defined webreports. If the name is found, that webreport is deleted. If the name is not found, an error message is displayed. For example, to delete the webreport named “ProjectStatus” enter the following:

delete webreport "ProjectStatus";

After this command is processed, the webreport is deleted and you receive an MQL prompt for another command.