portal Command

[add|copy|modify|delete|
print|list] portal NAME [CLAUSEs];

• NAME is the name you assign to the portal. Portal names must be unique. For more information, see About Administrative Object Names.
• CLAUSEs provide additional information about the portal.

Syntax

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

• user USER_NAME can be included if you are a business administrator with person/group/role access defining a channel for another user. This user is the item’s “owner.” If the user clause is not included, the portal is a system item.
• ADD_ITEM is an add portal clause that provides additional information about the portal. The add portal clauses are:

  description VALUE

  icon FILENAME

  label VALUE

  href VALUE

  alt VALUE

  channel CHANNEL_ID{,CHANNEL_ID} [{channel CHANNEL_ID{,CHANNEL_ID}}];

  setting NAME [STRING]

  [!|not] hidden

  property NAME [to ADMINTYPE NAME] [value STRING]

  visible USER_NAME{,USER_NAME};

  history STRING

Label Clause

This clause specifies the label to appear in the application in which the portal is assigned.

Href Clause

This clause is used to provide link data to the JSP. The href link is evaluated to bring up another page. Many portals will not have an href value at all. The href string generally includes a fully-qualified JSP filename and parameters, which can contain embedded macros and expressions for mapping to database schema.

The syntax is:

href VALUE;

• VALUE is the link data.

Alt Clause

This clause is used to define text that is displayed until any image associated with the portal is displayed and also as “mouse over text.”

The syntax is:

alt VALUE;

• VALUE is the text that is displayed.

For example, you could use the following for a Program Manager portal:

alt "Program Manager";

Channel Clause

This clause is used to specify existing channels to be added to a single row in the portal you are creating. You can add channels that are owned by you (in your workspace), or system channels. Channels will be displayed in the order in which they are added. Separate items with a comma. To indicate a new row in the portal, use the channel clause again.

You cannot add channels from other user’s workspaces.

The syntax is:

channel CHANNEL_ID{,CHANNEL_ID} [{channel CHANNEL_ID{,CHANNEL_ID}}];

• CHANNEL_ID is the name of the channel you are adding, plus an optional keyword system. Specify 'system' if you are creating a workspace portal and the channel is a system channel. If the portal you are creating is a system portal, the channels added are also assumed to be system.

For example, the following portal has 3 rows of channels:

add portal MyPortal channel ABC system,DEF channel EFG system channel XYZ;

For more information, see Add Channel.

Setting Clause

This clause is used to provide any name/value pairs that the portal needs. They can be used by JSP code, but not by hrefs on the Link tab. For more information, see MQL Concepts: Using Macros and Expressions in Configurable Components.

The syntax is:

setting NAME [STRING];

For example, an image setting with the image name can be specified to display when the portal is used in a toolbar:

setting Image iconSmallMechanicalPart.gif;

History Clause

The history keyword adds a history record marked “custom” to the portal that is being added. The STRING argument is a free-text string that allows you to enter some information describing the nature of the addition. For more information, see Adding History to Administrative Objects.

If you are a Business Administrator with portal access, you can copy system portals. If you are a Business Administrator with person access, you can copy portals in any person’s workspace (likewise for groups and roles). Other users can copy visible workspace portals to their own workspaces.

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

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

• SRC_NAME is the name of the portal 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 portal 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. You only need to specify the fields to be modified.

  Clone/Modify Portal Clause	Specifies
  name NEW_NAME	The current portal name is changed to the new name entered.
  description VALUE	The current description value, if any, is set to the value entered.
  icon FILENAME	The image is changed to the new image in the field specified.
  label VALUE	The label is changed to the new value specified.
  href VALUE	The link data information is changed to the new value specified.
  alt VALUE	The alternate text is changed to the new value specified.
  height VALUE	The height is changed to the new value specified.
  place CHANNEL1 [system] [newrow] before CHANNEL2 [system]	The named CHANNEL1 is moved or added before CHANNEL2. Use newrow to indicate that the channels are not next to each other but in separate rows. If CHANNEL2 is an empty string, CHANNEL1 is placed before all channels in the portal.
  place CHANNEL1 [system] [newrow] after CHANNEL2 [system]	The named CHANNEL1 is moved or added after CHANNEL2. Use newrow to indicate that the channels are not next to each other but in separate rows. If CHANNEL2 is an empty string, CHANNEL1 is placed after all channels in the portal.
  add setting NAME [STRING]	The named setting and STRING are added to the portal.
  remove channel NAME [system]	The named channel is removed from the portal. Specify system if it is a channel that is not owned by the same user as owns the portal. If modifying a system portal, the channel is assumed to be a system channel.
  remove setting NAME [STRING]	The named setting and STRING are removed from the portal.
  visible USER_NAME{,USER_NAME};	The named users have visibility to the portal.
  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.
  history STRING	Adds a history record marked "custom" to the portal that is being copied. The STRING argument is a free-text string that allows you to enter some information describing the nature of the copy operation. For more information, see Adding History to Administrative Objects

Syntax

You must be a business administrator with group or role access to modify a portal owned by a group or role.

Use the modify portal command to add or remove defining clauses or change the value of clause arguments:

modify portal NAME [user USER_NAME] [MOD_ITEM {MOD_ITEM}];

• NAME is the name of the portal 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 any of the items in the table above.

Each modification clause is related to the arguments that define the portal. 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.

When modifying a portal, you can make the changes from a script or while working interactively with MQL.

• If you are working interactively, perform one or two changes at a time to avoid the possibility of one invalid clause invalidating the entire command.
• If you are working from a script, group the changes together in a single modify portal command.

History Clause

The history keyword adds a history record marked “custom” to the portal that is being modified. The STRING argument is a free-text string that allows you to enter some information describing the nature of the modification. For more information, see Adding History to Administrative Objects.

You must be a business administrator with group or role access to delete a channel owned by a group or role.

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

delete portal NAME [user USER_NAME];

• NAME is the name of the portal 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 portals. If the name is found, that portal is deleted. If the name is not found, an error message is displayed. For example, to delete the portal named “Program Manager” enter the following:

delete portal "Program Manager";

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