AddUserFolders

Short Description

Creates a user's home folder and subfolders.

Syntax

rc=DoRequest("<AddUserFolders>...</AddUserFolders>",outMetadata);

Parameters

Method Parameters

Parameter	Type	Direction	Description
<Tree/>	C	in	Metadata property string that creates a Tree object. See the "Details" section for information about the format of the metadata property string.

Details

The SAS Metadata Server supports the concept of a user folder to enable clients to provide a consistent user interface to metadata. The user folder is a work area similar to the My Documents area on a Windows system. Metadata that is created or accessed by a user is stored in a subfolder of the user folder. This subfolder is named “My Folder” by default. The work area also includes a subfolder named “Application Data” that stores system information about the user for the internal use of applications.

The AddUserFolders method can be used to create one or all of these folders for a specified user.

The AddUserFolders method is available in the DoRequest interface only. The method and its parameters are specified in an XML input string within the INMETADATA parameter of the DoRequest method. The method's output is returned in the DoRequest method's OUTMETADATA parameter.

The XML input string consists of an <ADDUSERFOLDERS> element that passes a metadata property string that defines a Tree object in the following form:

<Tree PersonName='name' FolderName='folder-type'/>

A folder is represented by the Tree metadata type in a SAS Metadata Repository.

PERSONNAME='name'

specifies the name of the user for whom the folder is created.

The PERSONNAME value must be the unique name stored in a Person object's Name attribute or be blank. If a name value contains a forward slash (/) or backslash (\), the AddUserFolders method changes it to a dash (-) so that it does not interfere with the folder's pathname specification. When PERSONNAME is blank, the specified folder is created for the connected user. A user folder cannot be created for an IdentityGroup. If the name specified in PERSONNAME does not match the name of the requesting user, the connected user must be an administrative user of the SAS Metadata Server. Otherwise, the server returns an error. For more information about administrative user status on the SAS Metadata Server, see SAS Intelligence Platform: Security Administration Guide.

FOLDERNAME='folder-type'

specifies the type of user folder to create. Valid values are “Home Folder,” “My Folder,” or “Application Data.”

When choosing a FOLDERNAME value for an AddUserFolders request, note that a request to create a folder named “Home Folder” does not also create subfolders. However, a request to create any of the subfolders (“My Folder” or “Application Data”) does create a home folder, if one does not exist.

If you specify a SAS Metadata Model metadata type other than Tree in the XML input string, the SAS Metadata Server returns an error. The name “Folder” is accepted in the XML input string, because Folder is the PublicType value that is assigned to a Tree object.

Do not specify more than one Tree or Folder definition within the <ADDUSERFOLDERS> element. If you want to define more than one user folder in a request, submit multiple <ADDUSERFOLDERS> elements within a <MULTIPLE_REQUESTS> element. For more information about the <MULTIPLE_REQUESTS> element, see DoRequest.

The AddUserFolders method uses the security policy defined for the foundation repository to determine where to create the folders. The foundation repository has a Metadata Location for Users' Folders policy that specifies the root folder in which to store the user folders. The default security policy is to create the user folders in the foundation repository in a /User Folders folder. However, the SAS Metadata Server supports storing folders in another folder of the foundation repository or in another repository, if the other repository and folder exist in the folder tree. The AddUserFolders method does not create a repository or /User Folders folder for you.

A successful AddUserFolders request creates a subfolder in the /User Folders folder that has the name specified in the PERSONNAME parameter. The request potentially creates one or both of the “My Folder” and “Application Data” subfolders. The names “My Folder” and “Application Data” are localized. For example, if all possible folders were created for a user using the US-English locale, they would be displayed in the folder tree as follows:

—Users
- —PersonName
  
  —My Folder
  
  —Application Data

If the French locale were active, then “My Folder” and “Application Data” would be displayed in French. The locale used to create the Tree object's DisplayName attribute is provided to the SAS Metadata Server in the LOCALE server invocation option or in the sasv9.cfg file.

The AddUserFolders method automatically stores the following attribute values for each folder:

PublicType="Folder"
UsageVersion="1000000"
TreeType="BIP Folder"
DisplayName="server-localized-version-of-folder-name”

This attribute is set only for subfolders of the user folder.

The Admin-Only Update ACT grants SAS Metadata Server administrators WriteMetadata and Write permissions to all user home folders, and denies the Public group WriteMetadata and Write permissions to user home folders. This enables only administrators to create and update home folders. The Private User Folder ACT grants SAS Metadata Server administrators full access to all "My Folder" and "Application Data" subfolders in the directory, and denies the Public group access to the subfolders. This ACT contains an access control entry (ACE) for each person indicated in PERSONNAME that grants them ReadMetadata, WriteMemberMetadata, and CheckinMetadata permissions on his or her “My Folder” and “Application Data” folders. These permissions enable the folder owners to view and create metadata in their user folders, but not to delete the folders.

If the administrator changes the Metadata Location for Users' Folders policy after some user folders have been created, then any home folders and subfolders for existing users in /User Folders will remain in this folder. Home folders for new users are created in the new location.

Example

The following is an example of a DoRequest method call that issues an AddUserFolders request. The request creates both a “My Folder” and home folder for user “SAS Web Administrator.”

outMetadata=""
inMetadata=
"<AddUserFolders>
  <Tree PersonName='SAS Web Administrator' FolderName='My Folder'/>
</AddUserFolders>";

rc=DoRequest(inMetadata,outMetadata);

If the request is successful, the XML returned in the OUTMETADATA parameter mirrors the input in the INMETADATA parameter. The output includes the 17-character metadata identifier of the newly created “My Folder” Tree object. A metadata property string and an Id value defining the home folder are not returned in the output. The folder is created if it did not exist.

The request is rejected with an authorization error if the requesting user is not “SAS Web Administrator,” is not an administrative user of the SAS Metadata Server, or if “SAS Web Administrator” is the name of an IdentityGroup.