PortalRegistry Class Methods

In this section, we discuss the PortalRegistry class methods. The methods are discussed in alphabetical order.

Syntax

Close()

Description

The Close method closes the PortalRegistry object, that is, this method sets the object to the state it was in immediately after the GetPortalRegistry was done on the PeopleSoft Session object. Any unsaved changes are discarded. The Close method can be used only on an open PortalRegistry, not a closed one. This means you must have opened the PortalRegistry with the Open method before you can close it.

Parameters

None.

Returns

A Boolean value: True if the PortalRegistry object is successfully closed, False otherwise.

Example

&Rslt = &MyRegistry.Close();

If Not &Rslt Then
   /* registry not closed - do error processing */
End-if;

Syntax

CopyObject(sourcePortalName, sourceRefType, sourceObjName, targetPortalName, targetPrntFldrName, copyChildren)

Description

Use the CopyObject method to copy folders and content references between portal registries.

If the object being copied has related HTML, the HTML is also copied and named according to the current portal naming convention for HTML objects, which is: 

PR_<portalname>_<objectname>

where <portalname> is up to the first 8 characters of the portal name and <objectname> is up to the first 17 characters of the object name.

Considerations Using CopyObject

The source portal name and the target portal name cannot be the same name.

The targetPrntFldrName must be a folder that exists in the portal identified by the target portal name. It cannot be null (or empty). If you need to copy an entire portal, the portal must first be "created" using the Create method, before copying over all the folders and content references.

The copyChildren parameter is ignored for content references. However, it still must be set to "Yes" or "No".

Parameters

Field or Control

Definition
sourcePortalName

Specify the name of the portal from which the object is to be copied.
sourceRefType

Specify the type of object to be copied. Values are:

  • "C" for content references

  • "F" for folders

This parameter is case-sensitive.
sourceObjName

Specify the name of the object to be copied.
targetPortalName

Specify the name of the portal to which the object will be copied.
targetPrntFldrName

Specify the name of the folder that will be the parent folder for the source object.
copyChildren

Specify whether to also copy the children of the source object. This parameter is valid only with folder objects. Values are:

  • "Yes" copy child objects

  • "No" do not copy child objects

This parameter is case-sensitive.

Returns

A Boolean value: True if object copied successfully, False otherwise.

Example

&Success = &Portal.CopyObject("PORTAL", "F", "PEOPLETOOLS_QUALITY", "BOGUS", "PORTAL_ROOT_OBJECT", "Yes");
If (&Success = False) Then
   WinMessage("portal copy failed");
   Exit;
End-If;

Syntax

Create(RegistryName)

Description

The Create method creates a new PortalRegistry in the PortalRegistry object called RegistryName. The specified registry must be a new registry. The Create method returns False if the registry already exists.

The new PortalRegistry is immediately committed to the database. If you change any property of a PortalRegistry after you create the object, use the Save method to commit your changes to the database.

When a registry is created, a folder called Root is automatically created. This is the root folder for the registry.

Note: If you're using Visual Basic, you must check that the PortalRegistry is actually created. If you use a duplicate name, a zero is returned, but no error results.

Parameters

Field or Control

Definition
RegistryName

The name of the registry to create. This parameter takes a string value. If you specify a registry that already exists, this method returns a False value.

Returns

A Boolean value: True if the PortalRegistry object is successfully created, False otherwise.

Example

&PORTAL_NAME = MY_PORTAL_RECORD.PORTALNAME;
&MyPortal = %Session.GetPortalRegistry();

If NOT &MyPortal.Create(&PORTAL_NAME) Then;
   /* portal not created - do error processing */
End-If;

Syntax

CreateContentRefLink(LinkName, LinkLabel, LinkParent, CRefPortalName, CRefObjectName)

Description

Use the CreateContentRefLink method to create a link to any content reference in any portal in a local database.

For example, using this method, you can create a link to a content reference in the EMPLOYEE portal, to a content reference in the CUSTOMER portal, or to a content reference in the current portal.

Parameters

Field or Control

Definition
LinkName

Specify the name of the link as a string. This is the ID of the link. The name is validated as that of the content reference name. It cannot start with a number, and can not have special characters and spaces. This property is not translated.

LinkLabel

Specify the label of the link as a string. This property can be translated. This is the label that appears on the left hand navigation menu If this value is blank, a linked content reference label is displayed instead.
LinkParent

Specify the parent folder of the link, as a string.
CRefPortalName

Specify the portal name of the content reference, to which the link is pointing, as a string.
CRefObjectName

Specify the ID of the content reference to which the link is pointing, as a string.

Returns

A reference to a newly created ContentReference link object.

Example

Local ApiObject &Portal, &CRef, &CReflink;
&Portal = PortalOpen();
&CReflink = &Portal.CreateContentRefLink(<Unique Link Name> , <LinkLable>, "<Link's Parent folder >", "<Cref Portal Name>", <Cref Object Name>);

/*... Use the link object */

&Portal.Close();

Syntax

CreateRemote(PortalName, RemoteNodeName)

Description

Use the CreateRemote method to create a remote portal. Although you can have more than one portal on a node, they must all be uniquely named.

Parameters

Field or Control

Definition
PortalName

Specify the name of the new portal to create on the remote node.

RemoteNodeName

Specify the name of the remote node to create the new portal on.

Returns

A Boolean value: True if the PortalRegistry object is successfully created, False otherwise.

Syntax

Delete(RegistryName)

Description

The Delete method deletes the PortalRegistry from the database, including any data and tables.

Warning! If you delete a PortalRegistry, you delete everything. Your entire PortalRegistry is gone, all the folders, content references, templates, and so on. Do not delete a PortalRegistry object unless you are absolutely certain that you want to.

Note: The portal registry classes execute some methods "interactively", that is, as they happen. The item won't be marked for deletion, then actually deleted later. The item is deleted from the database as soon as the method is executed.

The Delete method can only be used with a closed registry, it cannot be used on an open registry. Before you use the Delete method, you must explicitly close the PortalRegistry object (with the Close method.) The Delete method returns False if you try to delete an open PortalRegistry object.

Parameters

Field or Control

Definition
RegistryName

The name of the registry to delete. This parameter takes a string value. If you specify a registry that doesn't exist, this method returns a False value.

Returns

A Boolean value: True if the PortalRegistry object is successfully deleted, False otherwise.

Example

The following example deletes all PortalRegistry objects that start with HRMS_99.

Local ApiObject &MySession;
Local ApiObject &MyPortal;

&MySession = %Session;

&MyPortal = &MySession.GetPortalRegistry();

&MyPortal.Delete("HRMS_99");

Syntax

DeleteHomepage()

Description

The DeleteHomepage method deletes the current user's homepage. This method is valid only after a user has opened a PortalRegistry object.

Parameters

None.

Returns

A Boolean value: True if the homepage is successfully deleted, False otherwise.

Syntax

FindCRefByName(Name)

Description

The FindCRefByName method returns the content reference object corresponding to Name. The name is a unique identifier for each content reference.

Considerations on Returned Content References

This method returns content reference objects that aren't yet valid as well as ones that are no longer valid. When you create your program, you must check for these invalid values if you don't want to use them. You can check using ValidTo, ValidFrom, or IsVisible.

This method returns content reference objects that you aren't authorized to. When you create your program, you should always check the Authorized property. This is the only property you can view from an object that you're not authorized to view.

Parameters

Field or Control

Definition
Name

A unique name within the registry that identifies the content reference. This parameter takes a string value. This parameter uses the name, not the label, of a content reference.

Returns

What this method returns depends on the condition of the content reference:

  • If the content reference name is valid and the end-user has access to the content reference, a content reference object is returned.

  • If the content reference is valid but the end-user doesn't have access to it a content reference object is returned, however, the only property you can access is the Authorized property.

  • If you specified an invalid name this method returns NULL.

Example

The following example returns a GLOBAL_PAYROLL content reference object:

&CRef = &Portal.FindCRefByName("GLOBAL_PAYROLL");

Syntax

FindCRefByURL(URL)

Description

The FindCRefByURL method returns the content reference object corresponding to URL. The URL specified by URL must be an absolute URL.

Note: The portal registry API needs the current URI of the local node to work. During runtime, it gets this information from the current webserver. For Application Engine programs, there isn't a current webserver, so it has to get this information from the database.

If you have multiple content providers with the same URI, FindCRefByURL looks for the specified content reference with all those content providers.

To access pagelet categories and their associated pagelets, use the PageletCategories collection from the PortalRegistry object, not FindCRefByURL.

Considerations on Returned Content References

This method returns content reference objects that aren't yet valid as well as ones that are no longer valid. When you create your program, check for these properties (ValidTo and ValidFrom) if you don't want to use them.

This method returns content reference objects that the end-user isn't authorized to. When you create your program, always check the Authorized property. This is the only property you can view from an object that the end-user isn't authorized to view.

Parameters

Field or Control

Definition
URL

A URL that represents the content. This parameter takes a string value. This URL must be an absolute URL. This parameter is case-insensitive.

Returns

What this method returns depends on the condition of the content reference:

  • If the end-user has access to the URL, a content reference object is returned.

  • If the content reference is registered, but the end-user doesn't have access to it, a content reference is returned, but the only property you can access is the Authorized property.

  • If a URL isn't registered or is invalid, this method returns NULL.

Example

The following example finds a content reference from a URL: 

&UserCRef = &Portal.FindCRefByURL("http://www.example.com");

Syntax

FindCRefForURL(URL)

Description

The FindCRefForURL method returns the content reference object corresponding to URL. The URL specified by URL must be an absolute URL.

If the exact content reference is not found, this method tries to look for the content reference again, after stripping off the query portion of the URL.

If you don't want the system searched without the query string, use the FindCRefByURL method.

Note: The portal registry API needs the current URI of the local node to work. During runtime, it gets this information from the current webserver. For Application Engine programs, there isn't a current webserver, so it has to get this information from the database.

If you have multiple content providers with the same URI, FindCRefForURL looks for the specified content reference with all those content providers.

To access pagelet categories and their associated pagelets, use the PageletCategories collection from the PortalRegistry object, not FindCRefForURL.

Considerations on Returned Content References

This method returns content reference objects that aren't yet valid as well as ones that are no longer valid. When you create your program, check for these properties (ValidTo and ValidFrom) if you don't want to use them.

This method returns content reference objects that the end-user isn't authorized to. When you create your program, always check the Authorized property. This is the only property you can view from an object that the end-user isn't authorized to view.

Parameters

Field or Control

Definition
URL

A URL that represents the content. This parameter takes a string value. This URL must be an absolute URL. This parameter is case-insensitive.

Returns

What this method returns depends on the condition of the content reference:

  • If the end-user has access to the URL, a content reference object is returned.

  • If the content reference is registered, but the end-user doesn't have access to it, a content reference is returned, but the only property you can access is the Authorized property.

  • If a URL isn't registered or is invalid, this method returns NULL.

Example

The following example finds a content reference from a URL. If the content reference isn't found from the full URL, the query string is stripped and the system searches again: 

&UserCRef = &Portal.FindCRefForURL("http://www.example.com/crefs/psportal/technologies/?url=http%3a%2f%2faugust2004%2fipass.html");

Syntax

FindCRefLinkByName(LinkName)

Description

Use the FindCRefLinkByName method to find the existing link in the current portal. If the link is found a reference to ContentReference link object is returned. A Null value is returned if the link is not found in the database, and the error message is added to message collection

Considerations on Returned Links

This method returns links that aren't yet valid as well as ones that are no longer valid. When you create your program, you must check for these properties (ValidTo and ValidFrom) if you don't want to use them. This method may also return objects that you aren't authorized to. When you create your program, you should always check the Authorized property. This is the only property you can view from an object that you're not authorized to view.

Parameters

Field or Control

Definition
LinkName

Specify the name of the link as a string. This is the ID of the link.

Returns

A reference to an existing ContentReference link object. or a Null value if the link is not found.

Syntax

FindFolderByName(Name)

Description

The FindFolderByName method returns the Folder object corresponding to Name. The name is a unique identifier for each folder.

Considerations on Returned Folders

This method returns Folder objects that aren't yet valid as well as ones that are no longer valid. When you create your program, check for these properties (ValidTo and ValidFrom) if you don't want to use them.

This method returns folder objects that you aren't authorized to. When you create your program, always check the Authorized property. This is the only property you can view from an object that you're not authorized to view.

Parameters

Field or Control

Definition
Name

A unique name within the registry that identifies the folder. This parameter takes a string value. This parameter takes the name of a folder, not the label.

Returns

What this method returns depends on the condition of the folder:

  • If the folder name is valid and the end-user has access to the folder, a folder object is returned.

  • If the folder is valid but the end-user doesn't have access to it a folder object is returned, however, the only property you can access is the Authorized property.

  • If you specified an invalid name this method returns NULL.

Example

The following example returns a folder named ROOT:

&MyFolder = &MyPortal.FindFolderByName("ROOT");

The following example returns the folder object for an already instantiated content reference:

&Folder = &Portal.FindFolderByName(&CRef.ParentName);

Syntax

FindPgltByName(PageletName)

Description

The FindPgltByName method returns the pagelet object corresponding to PageletName. The name is a unique identifier for each pagelet.

Considerations on Returned Pagelets

This method returns pagelet objects that aren't yet valid as well as ones that are no longer valid. When you create your program, check for these properties (ValidTo and ValidFrom) if you don't want to use them.

This method returns pagelet objects that you aren't authorized to. When you use create your program, always check the Authorized property. This is the only property you can view from an object that you're not authorized to view.

Parameters

Field or Control

Definition
PageletName

A unique name within the registry that identifies the Pagelet. This parameter takes a string value. This parameter takes the name of a Pagelet, not the label.

Returns

What this method returns depends on the condition of the Pagelet:

  • If the Pagelet name is valid and the end-user has access to the Pagelet, a Pagelet object is returned.

  • If the Pagelet is valid but the end-user doesn't have access to it a Pagelet object is returned, however, the only property you can access is the Authorized property.

  • If you specified an invalid name this method returns NULL.

Example

The following example returns a pagelet named HomePg_Dictionary:

&MyPglt = &MyPortal.FindPgltByName("HomePg_Dictionary");

Syntax

GetAbsoluteContentURL(NodeName, URL)

Description

The GetAbsoluteContentURL method returns the absolute unwrapped simple URL of the content, in the context of the current portal. For example, if the PortalRegistry object accessed a portal called Employees, and the method were called like this:

&Registry.getAbsoluteContentURL(Node.CRM,  "/c/SERVICES.ORDERS.GBL");

It would return the following string:

http://crmserver/servlets/psc/crmHome/Employees/CRM/c/SERVICES.ORDERS.GBL

In the returned string, the portion of the string from server name through portal_home (crmHome in the example) are the ones associated with the content node (CRM in the example). The portal is the current portal, and the rest of the URL is the URL string passed in.

Parameters

Field or Control

Definition
NodeName

Specify the name of the node that contains the content. You can also use a string, such as %Node, for this value.
URL

Specify the relative URL pointing to the content that you want the absolute URL generated for.

Returns

A string containing the absolute URL.

Syntax

GetDefaultHPTabOID()

Description

Use the GetDefaultHPTabOID method to return the name of the first homepage tab that is found and authorized for the current user ID.

The search order of the tabs depends on Sequence number of the tab name and is sorted alphabetically.

Parameters

None.

Returns

A string

Syntax

GetQualifiedURL(ContentProvider, RelativeURL)

Description

Note: This method is maintained only for backward compatibility. If your existing code uses this method, it actually returns the value from GetAbsoluteContentURL method. New applications should use the GetAbsoluteContentURL method.

Related Links

GetAbsoluteContentURL

Syntax

GrantPermissionForComponent(MenuName, ComponentName, Market, PermListName, NodeName)

Description

Use the GrantPermissionForComponent method to grant the specified permission and cascaded upwards on parent folders to the specified component. In addition, the specified permission is granted to any component references that point to the specified component, and any parent folders.

Components that have query strings are also searched and permissions are applied on them.

If you use the string "LOCAL_NODE" as NodeName, the system uses the node name currently defined as local.

All component entries in the portal registry are affected for all the portals. Not just the current portal.

Parameters

Field or Control

Definition
MenuName

Specify the menu name, as a string, that the component you want to grant permissions for is associated with.
ComponentName

Specify the component name, as a string, that you want to grant permissions for.
Market

Specify the market, as a string, associated with the component that you want to grant permissions for.
PermListName

Specify the name of the permission list, as a string, that you want to use.
NodeName

Specify the node of the component reference, as a string, that points to the component reference that you want to grant permissions for. If you use the string "LOCAL_NODE", the system uses the node name currently defined as local.

Returns

A Boolean value: True if method completed successfully, False otherwise.

Example

The My Profile Component Reference points to the USERMAINT_SELF component. Using the following example, "ALLPANLS" permission is granted to the MY_PROFILE component reference, as well as "MY INFO", the parent folder.

&Portal.GrantPermissionForComponent("MAINTAIN_SECURITY", "USERMAINT_SELF", "GBL", "ALLPANLS", "LOCAL_NODE");

Syntax

GrantPermissionForScript(RecordName, FieldName, EventName, FuncName, PermListName, NodeName)

Description

Use the GrantPermissionForScript method to grant the specified permission to the specified iScript. In addition, the specified permission is granted to any component references that point to the specified iScript, and any parent folders.

If you use the string "LOCAL_NODE" as NodeName, the system uses the node name currently defined as local.

All iScript entries in the portal registry are affected for all the portals. Not just the current portal.

Parameters

Field or Control

Definition
RecordName

Specify the record name, as a string, of the record containing the iScript. All iScripts are contained on records whose names start with "WEBLIB".
FieldName

Specify the name of the field, as a string, containing the iScript.
EventName

Specify the name of the event, as a string, containing the iScript. Generally iScripts are contained in the FieldFormula event.
FuncName

Specify the name of the function, as a string, containing the iScript.
PermListName

Specify the name of the permission list, as a string, that you want to use.
NodeName

Specify the node of the component reference, as a string, that points to the component reference that you want to grant permissions for. If you use the string "LOCAL_NODE", the system uses the node name currently defined as local.

Returns

A Boolean value: True if method completed successfully, False otherwise.

Example

&Portal.GrantPermissionForScript("WEBLIB_ALERT", "ALERTCOUNT", "FieldFormula", "Connect_Alert", "ALLPGS", "Local_Node");

Syntax

Open(RegistryName)

Description

The Open method opens the PortalRegistry specified by the parameters. The registry must already exist. The Open method can be used only with a closed PortalRegistry, it cannot be used on an open registry.

Parameters

Field or Control

Definition
RegistryName

The name of the registry to open. This parameter takes a string value. If you specify a registry that doesn’t exist, this method returns a False value.

Returns

A Boolean value: True if the PortalRegistry object is successfully opened, False otherwise.

Example

In the following example, the name of the portal is stored as the value of a field in a record.

&PORTAL_NAME = EO_PE_REG_AET.PORTAL_NAME;
&Portal = %Session.GetPortalRegistry();

&Portal.Open(&PORTAL_NAME);

Syntax

PermissionListDelete(PermListName)

Description

Use the PermissionListDelete method to delete the specified permission list from the PortalRegistry.

If you try to delete a permission list that is still in use, you receive an error when you try to save the object.

The permission list is deleted from all the portal objects for all the portal.

Parameters

Field or Control

Definition
PermListName

Specify the permission list to delete from the PortalRegistry.

Returns

A Boolean value: True if the permission list is successfully deleted, False otherwise.

Syntax

PermissionListSaveAs(PermListSourceName, PermListTargetName)

Description

Use the PermissionListSaveAs method to copy the specified permission list in the PortalRegistry.

Parameters

Field or Control

Definition
PermListSourceName

Specify the name of the PermissionList to copy.
PermListTargetName

Specify the name that you want to give the new PermissionList.

Returns

A Boolean value: True if the permission list is successfully copied, False otherwise.

Syntax

RevokePermissionForComponent(MenuName, ComponentName, Market, PermListName, NodeName)

Description

Use the RevokePermissionForComponent method to revoke the specified permission to the specified component. In addition, the specified permission is revoked for any component references that point to the specified component.

If you use the string "LOCAL_NODE" as NodeName, the system uses the node name currently defined as local.

All component entries in the portal registry are affected for all the portals. Not just the current portal.

Parameters

Field or Control

Definition
MenuName

Specify the menu name, as a string, that the component that you want to revoke permissions for is associated with.
ComponentName

Specify the component name, as a string, that you want to revoke permissions for.
Market

Specify the market, as a string, associated with the component that you want to revoke permissions for.
PermListName

Specify the name of the permission list, as a string, that you want to use.
NodeName

Specify the node of the component reference, as a string, that points to the component reference that you want to revoke permissions for. If you use the string "LOCAL_NODE", the system uses the node name currently defined as local.

Returns

A Boolean value: True if method completed successfully, False otherwise.

Example

The My Profile Component Reference points to the USERMAINT_SELF component. Using the following example, "ALLPANLS" permission is revoked to the MY_PROFILE component reference.

&Portal.RevokePermissionForComponent("MAINTAIN_SECURITY", "USERMAINT_SELF", "GBL", "ALLPANLS", "LOCAL_NODE");

Syntax

RevokePermissionForScript(RecordName, FieldName, EventName, FuncName, PermListName, NodeName)

Description

Use the RevokePermissionForScript method to revoke the specified permission to the specified iScript. In addition, the specified permission is revoked for any component references that point to the specified iScript.

If you use the string "LOCAL_NODE" as NodeName, the system uses the node name currently defined as local.

All component entries in the portal registry are affected for all the portals. Not just the current portal.

Parameters

Field or Control

Definition
RecordName

Specify the record name, as a string, of the record containing the iScript. All iScripts are contained on records whose names start with "WEBLIB".
FieldName

Specify the name of the field, as a string, containing the iScript.
EventName

Specify the name of the event, as a string, containing the iScript.
FuncName

Specify the name of the function, as a string, containing the iScript. Generally iScripts are contained in the FieldFormula event.
PermListName

Specify the name of the permission list, as a string, that you want to use.
NodeName

Specify the node of the component reference, as a string, that points to the component reference that you want to revoke permissions for. If you use the string "LOCAL_NODE", the system uses the node name currently defined as local.

Returns

A Boolean value: True if method completed successfully, False otherwise.

Example

&Portal.RevokePermissionForScript("WEBLIB_ALERT", "ALERTCOUNT", "FieldFormula", "Connect_Alert", "ALLPGS", "Local_Node");

Syntax

Save()

Description

The Save method saves changes that you made to the PortalRegistry or to a node template. It does not save any changes that you made to a folder, content reference, and so on.

Note: To save changes for a folder or content reference use the save method associated with that object.

Parameters

None.

Returns

A Boolean value: True if the PortalRegistry object is successfully saved, False otherwise.

Example

If Not(&MyPortal.Save()) Then
   /* do error checking */
End-if: