Setting Permissions Using the PermissionValue Object

The following code example adds permissions for a folder through the PermissionValue object.

The following is the complete code sample: the steps explain each line.

Local ApiObject &MyPortal;
Local ApiObject &UserFldr;
Local ApiObject &PermV, &PermVColl;

&MyPortal = %Session.GetPortalRegistry();

If NOT &MyPortal.Open(MYRECORD.PORTAL_NAME) Then
   /* Do error handling */
End-if;
&UserFldr = &MyPortal.RootFolder.Folders.ItemByName("Users");

&CascadedColl = &UserFldr.CascadedPermissions;

&PermV = &CascadedColl.ItemByName("VENDOR1");

If NOT &PermV Then
   &PermVColl = &UserFldr.Permissions;
   &PermVColl.InsertItem("VENDOR1");
   &UserFldr.Save();
End-If;

To set permissions for a folder, using the PermissionValue object:

1. Get a Session object and a PortalRegistry.

   Before you can access a PortalRegistry object, you must get a session object. The session controls access to the registry, provides error tracing, enables you to set the runtime environment, and so on. Because you want to use the existing session, use the %Session system variable (instead of the GetSession function.) In addition, you want to get a PortalRegistry. Using the GetPortalRegistry method returns a reference to an unpopulated PortalRegistry object.

   &MyPortal = %Session.GetPortalRegistry();

2. Open the PortalRegistry.

   After you get a PortalRegistry object, you want to open it, that is, populate it with data. Use the Open method to do this. The Open method returns a Boolean value, and this example uses that value to do error checking to make sure that the PortalRegistry is actually opened. In addition, the name of the PortalRegistry is kept in the record MYRECORD, in the field PORTAL_NAME.

   If NOT &MyPortal.Open(MYRECORD.PORTAL_NAME) Then
      /* Do error handling */
   End-if;

3. Access the User folder.

   One of the strengths of dot notation is being able to string together many methods and properties into a single line of code. The result of this single line of code is to return a reference to the folder named Users.

   &UserFldr = &MyPortal.RootFolder.Folders.ItemByName("Users");

4. Access the entire, cascaded PermissionValue collection.

   There are two types of PermissionValue collections you can access for a folder.

   • One contains only the permission list values that are set at that folder. This collection is returned with the Permissions property.

   • The other contains all the permission list values for folder, that is, it contains any permission list values set in any parent folder and cascaded. This collection is returned with the CascadedPermissions property.

Note:

You cannot add any PermissionValue objects to a collection returned by the CascadedPermissions property. You can add values only to the collection returned by the Permissions property.

This example uses the CascadedPermissions collection to check if the permission exists, because we don’t want to add a permission if it already exists. Then it uses the Permissions collection to add the value.

&CascadedColl = &UserFldr.CascadedPermissions;

1. Check to see if the permission list value exits.

   Before adding the new PermissionValue object, you want to make sure one by that name doesn't already exist.

   &PermV = &CascadedColl.ItemByName("VENDOR1");

2. If the PermissionValue doesn't exist, add it.

   The ItemByName returns a reference to a PermissionValue object if it exists, or NULL if it doesn't. So this example checks for NULL, and adds the PermissionValue if it doesn't exist.

   Notice that this example is not changing the Cascaded property with the PermissionValue object. The default value for a new PermissionValue object is False. As this example does not want to cascade the permissions for this permission list, it retains the default value.

   In addition, if the PermissionValue object is added, the folder is saved. The InsertItem method executes only after the parent object, the folder, is saved.

   If NOT &PermV Then
      &PermVColl = &UserFldr.Permissions;
      &PermVColl.InsertItem("VENDOR1");
      &UserFldr.Save();
   End-If;

   You may want to check for errors after you save the folder.

See Permissions property: Folder class, CascadedPermissions property: Folder class.

See Using PermissionValue, RolePermissionValue, Cascading Permissions and CascadingRolePermissions.