INFOMAPS Procedure

INSERT IDENTITY_PROPERTY Statement

Adds a SAS identity property or all available SAS identity properties to the current information map.

Syntax

INSERT IDENTITY_PROPERTY PROPERTY=property-keyword
<ID="identity_property-ID">;

Required Argument

PROPERTY=property-keyword

inserts a specified SAS identity property (or all available SAS identity properties) into the current information map. Once the properties are inserted into the information map, they can be used in filter definitions that are created with the INSERT FILTER or UPDATE FILTER statements.

The property-keyword value can be one of the following:

_ALL_: inserts all of the following SAS identity properties into the current information map.

EXTERNAL_IDENTITY: inserts the SAS.ExternalIdentity property. When a filter that uses this property is executed, the connected client’s identity value (for example, employee ID) is substituted in the filter expression. This property is often useful because its values are likely to match user information in your data.

Notes:An identity can have more than one external identity value. However, only the first value is returned.

Unlike the values for other SAS identity properties, values for this property are not always populated in the metadata. If an identity has no external identity values, then no value is returned for this property.

IDENTITY_GROUP_NAME: inserts the SAS.IdentityGroupName property. When a filter that uses this property is executed, the connected client’s group name is substituted in the filter expression. If a user logs on with an ID that is stored in a login on a group definition, then the name of the group that owns that login is returned. If a user logs on with a user ID that is not stored in the metadata, then the PUBLIC group is returned.

Restriction:This property is not supported if client-side pooling is used.

Note:This property is useful only in the unusual circumstance where a user logs on with the user ID that is defined for a group login. In almost all cases, a user logs on with a user ID that is defined for an individual user definition. Not all applications allow a group to log on.

IDENTITY_GROUPS: inserts the SAS.IdentityGroups property. When a filter that uses this property is executed, a list of the names of the user groups and roles to which the connected client belongs (directly, indirectly, or implicitly) is substituted in the filter expression.

IDENTITY_NAME: inserts the SAS.IdentityName property. When a filter that uses this property is executed, the connected client’s user name or group name is substituted in the filter expression. This property is a generalization of SAS.PersonName and SAS.IdentityGroupName.

PERSON_NAME: inserts the SAS.PersonName property. When a filter that uses this property is executed, the connected client’s name is substituted in the filter expression.

Note:Users who belong only to the PUBLIC group do not have PersonNames. For these users, no value is returned for this property.

USERID: inserts the SAS.Userid property. When a filter that uses this property is executed, the connected client’s authenticated user ID, normalized to the uppercase format USERID or USERID@DOMAIN, is substituted in the filter expression.

Note:If you attempt to insert an SAS identity property that already exists in the information map, then the INSERT IDENTITY_PROPERTY statement is ignored and a warning message is written to the log.

Optional Argument

ID="identity_property-ID": specifies the identifier that is assigned to the specified SAS identity property in the information map. To reference an SAS identity property in a conditional expression in an INSERT FILTER or UPDATE FILTER statement, you must specify its ID.
Note:

Default:If you omit the ID= option, then a default identifier is assigned to the inserted SAS identity property and a warning message is written to the log.

Note:When you specify PROPERTY=_ALL_, the specified ID value is used as the base name for the default identifiers that are assigned to the properties.

Details

It is often necessary to make per-person access distinctions. You can make a separate filter for each user (such as where name="joe"). However, if you have more than a few users, this approach quickly becomes cumbersome. The more efficient alternative is to create a dynamic filter (such as

where
                        name="&name;"

) that can discover and insert the correct, user-specific value into the WHERE expression each time access is requested.

To create a dynamic filter, use an SAS identity property as the value against which values in the target data are compared. This list explains how the substitution works:

Each SAS identity property corresponds to a characteristic (such as name, user ID, or external identity).
Each user's values for these characteristics (such as joe, WinXP\joe, or 607189) are stored in the metadata.
The SAS identity property is aware of the user ID with which a client authenticated and can locate information that is stored in the metadata for that user ID.
Each time it receives a request, the SAS identity property substitutes a user-specific value into the filter expression.

Note: In certain circumstances, a connecting identity might not have a value for the SAS identity property that you are using. This can happen with the ExternalIdentity property (sometimes), the IdentityGroupName property (almost always), or the PersonName property (rarely). When a connecting user doesn't have a value for the property that a query uses, an empty string is returned.

For more information about SAS identity properties and when to use them, see the section on fine-grained controls in the “Authorization Model” chapter in the SAS Intelligence Platform: Security Administration Guide. For information about using SAS identity properties to implement row-level access control to the data in an information map, see SAS Guide to BI Row-Level Permissions.

Example

insert identity_property
       property=person_name
       id="SasPersonName";

insert filter "myFilter"
       condition="<<SECURITY.USER_ID>>=(<<SasPersonName>>";