Metadata Access (IOMI Interface)

AddUserFolders

Creates a user's home folder and subfolders.

Category: User interface helper methods

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

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 9.2 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 forwardslash (/) 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 or 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" will not additionally create subfolders. However, a request to create any of the subfolders ("My Folder" or "Application Data") will additionally 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 also 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. Beginning in SAS 9.2, 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 /Users 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 will not create a repository or /Users folder for you.

A successful AddUserFolders request creates a subfolder in the /Users folder that has the name specified in the PERSONNAME= parameter. The request also 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 display 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 display 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 administrators only 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 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 the /Users folder will remain in this folder, and home folders for new users will be 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 is 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.

Related Methods

Top of Page