When you create a session, a number of session initialization flags are set to their default values. The following table lists the initialization methods in the PolicyMgtAPI object and their default values:

Method	Default	Description
DisableAudit()	0 (Auditing enabled)	Enables or disables: Auditing of user activity, including authentication, authorization, and administration activities. (Administration activities include changes to the policy store.) Monitoring of user sessions.
DisableManagement WatchDog()	0 (Watchdog enabled)	Enables or disables the SiteMinder management watchdog. The watchdog is used internally and should not be disabled.
Disable Validation()	0 (Validation enabled)	Enables or disables validation of policy store objects.
LoadAgentType Dictionary()	0 (Pre-load dictionary disabled)	Enables or disables the pre-loading of the agent type dictionary.
PreLoadCache()	0 (Pre-load cache disabled)	Enables or disables the pre-loading of SiteMinder caches.

Note: These methods have no effect if called after CreateSession().

Example: Initialize session operations

The following example enables all the session initialization operations that are not enabled by default. If the session is successfully initialized, the script displays the initialization flags:

use Netegrity::PolicyMgtAPI;

$username = "adminid";
$password = "adminpwd";

print "\nInitializing and connecting to PolicyMgtAPI...\n";
$policyapi = Netegrity::PolicyMgtAPI‑>New();
$policyapi‑>PreLoadCache(1);
$policyapi‑>LoadAgentTypeDictionary(1);

die "ERROR: Couldn't create session\n" unless ($session != undef);

print "Initialization settings:\n";
print "  Preload cache flag: ".$policyapi‑>PreLoadCache()."\n";
print "  Disable validation flag: " . 
                     $policyapi‑>DisableValidation()."\n";
print "  Load agent type dictionary flag: " . 
                     $policyapi‑>LoadAgentTypeDictionary()."\n";
print "  Disable audit flag: ".$policyapi‑>DisableAudit()."\n";
print "  Disable watchdog flag: " . 
                     $policyapi‑>DisableManagementWatchDog()."\n";

Create and Manage System Objects

When you initialize a connection to the Policy Server, you create a session object (PolicyMgtSession). You use the session object to create, retrieve, and delete the system-level objects that are listed in the System tab of the SiteMinder Administration window.

System objects (also called global objects) have global scope—that is, they are visible across all domains in the policy store. The system objects you can create from session objects include:

Administrators
Agents and agent types
Authentication schemes
Authentication and authorization maps
Domains
ODBC query schemes
Password policies
Registration schemes
User directories

Create Agent Objects

Agent objects are system objects with global scope. The following example uses a session object to create and configure an agent, then prints out all the agent names that are configured in the policy store:

use Netegrity::PolicyMgtAPI;

$policyapi = Netegrity::PolicyMgtAPI‑>New();
$session = $policyapi‑>CreateSession("adminid", "adminpwd");

$ip="127.0.0.1";
$secret="oursecret";

$agentType=$session‑>GetAgentType("Web Agent");
$session‑>CreateAgent("agent1",$agentType,"",$ip,$secret);

@agents=$session‑>GetAllAgents();
foreach $agent(@agents) {
   print $agent‑>Name()."\n";
}

Note: This example creates a v4.x agent. To create a v5.x or v6.x agent, do not specify a shared secret.

View and Modify Object Properties

After you create an object (or after an object is created in the Administrative UI), you can view and modify the individual properties of the created object by calling the object’s get and set methods.

Typically, an object’s get and set method names represent the name of the property being retrieved or modified, and the methods take a single optional argument. If you supply the argument, you set the property for the object. If you omit the argument, you retrieve the property value without altering it. The method returns the new or existing property value.

In the following example, each user directory is checked for its Maximum Results property—that is, the value that specifies the maximum number of search results to return after a directory search. If the retrieved number is not 25, the script sets the property to 25:

use Netegrity::PolicyMgtAPI;

$policyapi = Netegrity::PolicyMgtAPI‑>New();
$session = $policyapi‑>CreateSession("adminid", "adminpwd");

$max="25";

@userdirs=$session‑>GetAllUserDirs();
foreach $userdir(@userdirs) {
   print "\nMax results for directory " . $userdir‑>Name()."\n";
   if ($userdir‑>MaxResults() != $max) {
      print "  Updating from " . $userdir‑>MaxResults()." to " .
                                                      $max . "\n";
      $userdir‑>MaxResults($max);
   }
   else {
      print "  Max results are correct.\n";
   }
}

Objects with Domain Scope

One of the system objects you can create is a domain object (PolicyMgtDomain). Although a domain object itself has global scope, the objects you create and retrieve through a domain object have domain scope—that is, they are visible only within the domain and cannot be shared between domains.

Domain objects are listed in the Domains tab of the SiteMinder Administration window.

Objects with domain scope include:

Policies
Realms
Responses and response attributes
Rules
User Policies

Retrieve One Object to Create Another

Sometimes, before you can manipulate an object, you must retrieve a higher-level object. That is the case with objects having domain scope.

Here is an example of creating a policy with domain scope. Note that before the policy object can be created, you retrieve the domain object where the policy will reside:

use Netegrity::PolicyMgtAPI;

$policyapi = Netegrity::PolicyMgtAPI‑>New();
$session = $policyapi‑>CreateSession("adminid", "adminpwd");
$domain=$session‑>GetDomain("engineering");
$policy=$domain‑>CreatePolicy("Payroll Policy");
if($policy == undef) {
   print "Couldn't create the policy.\n";
}
else {
   print "Successfully created policy " . $policy‑>Name() . ".\n";
}

Manage an Object’s Properties

You view and set properties for an object with domain scope by using the object’s get and set methods, just as you do for objects with global scope.

Sometimes, the value of an object’s property is not a string or numeric value, but another object. For example, with policies, you add rules and users to the policy, and you set responses for the rules in the policy. All of these values are provided as objects.

Example: Add objects to a policy

In the following example, the policy is configured with a user, rule and response:

use Netegrity::PolicyMgtAPI;

$policyapi = Netegrity::PolicyMgtAPI‑>New();
$session = $policyapi‑>CreateSession("adminid", "adminpwd");
$domain=$session‑>GetDomain("engineering");
$policy=$domain‑>GetPolicy("Payroll Policy");

# Add a user to the policy
$userdir=$session‑>GetUserDir("Acme North Directory");

@users=$userdir‑>LookupEntry("uid=ppaycheck");
foreach $user(@users) {
   if ($user‑>GetPath()=="uid=ppaycheck,ou=HR,o=security.com") {
      $userResult=$policy‑>AddUser($user);
      $thisUser=$user;
   }
}
if ($userResult != 0) {
   print "Error adding user to policy.\n";
}

# Add a rule to the policy
$realm=$domain‑>GetRealm("HR");
$rule=$realm‑>GetRule("Payroll Rule");
$ruleResult=$policy‑>AddRule($rule);
if ($ruleResult != 0) {
   print "Error adding rule to policy.\n";
}
else
{
   # Set a response for the rule
   $response=$domain‑>GetResponse("Welcome to Payroll");
   $respResult=$policy‑>SetResponse($rule,$response);
   if ($respResult != 0) {
      print "Error adding response to policy.\n"
   }
}

print "\nAdded these objects to the policy:\n";
print "  User DN: ".$thisUser‑>GetPath()."\n" unless $userResult!=0;
print "  Rule: ".$rule‑>Name()."\n" unless $ruleResult!=0;
print "  Response: ".$response‑>Name()."\n" unless $respResult!=0;

Objects with Domain Scope or Global Scope

Some objects can be created with either domain scope or global scope. Those objects are:

PolicyMgtPolicy
- Domain: PolicyMgtDomain‑>CreatePolicy()
- Global: PolicyMgtSession‑>CreateGlobalPolicy()
PolicyMgtResponse
- Domain: PolicyMgtDomain‑>CreateResponse()
- Global: PolicyMgtSession‑>CreateGlobalResponse()
PolicyMgtRule
- Domain: PolicyMgtRealm‑>CreateRule()
- Global: PolicyMgtSession‑>CreateGlobalRule()
PolicyMgtGroup
- Domain: PolicyMgtDomain‑>CreateResponseGroup()
- Domain: PolicyMgtDomain‑>CreateRuleGroup()
- Global: PolicyMgtSession‑>CreateAgentGroup()

The following table compares policy, response, and rule objects when they have domain scope and global scope:

Object	Domain Scope	Global Scope
Policy	Bound to specific users or groups of users.	Bound to all users.
	Individual users can be included in or excluded from the policy.	Users cannot be individually included or excluded.
	Uses domain-specific rules and rule groups, domain-specific responses and response groups, and global responses.	Uses only global rules and global responses.
	Can use variable expressions.	Cannot use variable expressions.
Response	Used in a domain-specific policies.	Used in global or domain-specific policies.
	Can be a member of a domain-specific response group.	Can be a member of a domain-specific response group. Global response groups are not supported.
	Can use variables-based attributes.	Cannot use variables-based attributes.
Rule	Used in domain-specific policies.	Used in global policies.
	Associated with an agent through a realm.	Associated with a specific agent or agent group. The agent or agent group is specified when the global rule is created.
	The resource filter is bound to a specific realm (realm filter plus rule filter).	The resource filter is absolute (that is, not bound to a realm).
	Fires only for resources defined within a specific domain.	Fires for resources defined within any domain that has global policy processing enabled.
	Can be defined as an access rule or an event rule.	Can be defined as an event rule only (authentication and authorization events).
	Can be a member of a domain-specific rule group.	Can be a member of a domain-specific rule group. Global rule groups are not supported.
All	Created by domain administrators in the context of the specific domain.	Created by system administrators at the system level.

Authorization Variables

An authorization variable is a dynamic object that is resolved to a value during an authorization request. The variables appear within an active expression defined for a policy or a response.

Authorization variables are used as follows:

With policies, variables are used as authorization constraints. When a user requests access to a resource, and the resource contains an active expression that includes one or more variables, the variables are resolved to values that pertain to the user. The values are then evaluated and used in the decision about whether to authorize the user.
For example, suppose a policy that protects a bank’s credit card application form contains an active expression with a Credit Rating variable and a Salary variable. When a user attempts to access the form, the user is authorized only if his credit rating and salary meet or exceed the minimum values for these variables.
With responses, variables are used as return values. For example, a response attribute might be configured to return a transaction’s tracking number obtained from a remote Web Service.

To use authorization variables, you must have the SiteMinder Option Pack installed.

Configure a Variable for a Particular Variable Type

You create and configure a variable by calling CreateVariable() for a PolicyMgtDomain object.

One of this method’s arguments is definition. The value of this argument can be a simple string or a set of XML elements, depending on the variable type. Here are the SiteMinder variable types and a description of the definition argument for each type:

Post
The definition argument contains the name of a field on an HTML form. In a POST action, the variable value is derived from the value assigned to the field.
RequestContext
The definition argument contains the following XML code:
```
<RequestContextVariableDef>
   <ItemName></ItemName>
</RequestContextVariableDef>
```
The variable value depends upon which of the following attribute names appears within the ItemName element:
- Action. The variable value is the type of action specified in the request (for example, GET or POST).
- Resource. The variable value is the target resource (for example, /directory_name/).
- Server. The variable value is the full server name specified in the request (for example, server.company.com).
Static
The definition argument contains the actual value that will be compared against the user-supplied data at runtime. For example, a Static variable of return type VAR_RETTYPE_DATE might be assigned the string value 2004-01-01. During authorization, this assigned date is compared to a user-supplied date.
UserContext
The definition argument contains some or all of the following XML code:
```
<UserContextVariableDef>
   <ItemName></ItemName>
   <PropertyName></PropertyName>
   <DN></DN>
   <BufferSize></BufferSize>
</UserContextVariableDef>
```
The variable value is based on an attribute of a user directory connection (such as session ID) or on the contents of the user directory (such as user name). The name of the attribute upon which the variable value is based appears in the XML element ItemName.

The elements PropertyName, DN, and BufferSize are only used as follows:
- When ItemName contains DirectoryEntryProperty, elements PropertyName, DN, and BufferSize are used.
- When ItemName contains UserProperty, elements PropertyName and BufferSize are used.
For a complete list of the valid ItemName values, see the description of CreateVariable() in the Policy Management API Reference (PolicyMgtAPI.htm).

WebService

The definition argument contains the following basic XML structure:

<WebServiceVariableDefn xmlns:NeteWS=
                       "http://www.netegrity.com/2003/SM6.0";>
   <NeteWS:RemoteURL></NeteWS:RemoteURL>
   <NeteWS:SSL/>
      <NeteWS:RemoteMethod></NeteWS:RemoteMethod>
      <NeteWS:ResultQuery></NeteWS:ResultQuery>
      <NeteWS:AuthCredentials>
         <NeteWS:Username></NeteWS:Username>
         <NeteWS:Password></NeteWS:Password>
         <NeteWS:Hash></NeteWS:Hash>
      </NeteWS:AuthCredentials>
      <NeteWS:Document>
         <SOAP:Envelope xmlns:SOAP=
                 "http://schemas.xmlsoap.org/soap/envelope/";>
            <SOAP:Header></SOAP:Header>
            <SOAP:Body></SOAP:Body>
         </SOAP:Envelope>
      </NeteWS:Document>
</WebServiceVariableDefn>

To retrieve a variable value from a Web Service, the Policy Server sends the Web Service a SOAP request document as specified in the definition argument, and then extracts the variable value from the SOAP response.

The following table describes the XML elements used to configure a WebService variable:

Element	Description
RemoteURL	The URL to the Web Service that will resolve the WebService variable.
SSL	Specifies that the connection between the Policy Server and the Web Service should use SSL.
RemoteMethod	Set this element to POST.
ResultQuery	The return query, in XPath format. The Policy Server uses this information to search for the variable’s value in the SOAP response document.
AuthCredentials	Optionally, specify the user’s Web Service credentials through the following elements: Username Password (use either a SHA-1 password digest or a clear-text password) Optionally, use the Hash element to specify that a hash of the password is to be included in the WS‑Security password.
Document	Optionally, use this element to define a SOAP header and/or SOAP body through the following elements: Envelope. The SOAP namespace is: http://schemas.xmlsoap.org/soap/envelope Header. A user-defined SOAP header. A WS‑Security header is automatically added to it if the user’s Web Service credentials are specified. Body. A user-defined SOAP body. Nested variables of type RequestContext, UserContext, Post, and Static can be used inside the header and body. Their values are resolved and substituted before the request document is sent to the remote Web Service. Specify a nested variable as follows: $variable-name$

Note: The XML element structures shown above are formatted for legibility. The XML string supplied through the definition argument should not be formatted with spaces, tabs, and return characters. For example, a RequestContext variable for a Resource attribute would be passed in definition as follows:

<RequestContextVariableDef><ItemName>Resource</ItemName></RequestContextVariableDef>

The following information is required in a call to CreateVariable():

The user-defined variable name.
The variable type—for example, Static or ResourceContext.
The variable definition.
The data type of the variable value. Valid data type values are:
- VAR_RETTYPE_BOOLEAN
- VAR_RETTYPE_NUMBER
- VAR_RETTYPE_STRING
- VAR_RETTYPE_DATE

If you have both the optional TransactionMinder product and the Option Pack installed, you can use the following types of variables:

SAMLAssertion
Transport
XMLAgent
XMLBody
XMLEnvironment

You cannot create variables of these types with the Command Line Interface. You can only do so using the Administrative UI.

Example: Create a ResourceContext Variable

The following example creates the variable MyVar as a ResourceContext variable. The variable value is the resource that is being protected (for example, /directory_name/):

use Netegrity::PolicyMgtAPI;

$pmgtapi=Netegrity::PolicyMgtAPI‑>New();
$session=$pmgtapi‑>CreateSession("adminid", "adminpwd");

$dom=$session‑>GetDomain("MyDomain");
$varName="MyVar";
$varType=$session‑>GetVariableType("RequestContext");
$varDef="<RequestContextVariableDef><ItemName>Resource</ItemName>

</RequestContextVariableDef>";


$vr=$dom‑>CreateVariable($varName,$varType,$varDef,

VAR_RETTYPE_STRING);


if ($vr==undef) {
	print "Create operation failed.";
	}
else {
	print "Created variable " . $varName;
	}