Variable Definition

Programming Guides › Programming Guide for C › Policy Management API › Policy Management API Data Structures › Sm_PolicyApi_Variable_t › Variable Definition

Variable Definition

You define a variable by specifying where the variable's value can be found. You do so through the pszDefinition field.

The value of this field 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 pszDefinition field for each type:

Post
The pszDefinition field 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 pszDefinition field 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. With this item name, the variable value is the type of action specified in the request (for example, GET or POST).
- Resource. With this item name, the variable value is the target resource (for example, /directory_name/).
- Server. With this item name, the variable value is the full server name specified in the request (for example, server.company.com).
Static
The pszDefinition field contains the actual value that will be compared against the user-supplied data at runtime. For example, a Static variable of return type Sm_PolicyApi_VarReturnTypes_Date might be assigned the string value 2004-01-01. During authorization, this assigned date is compared against a user-supplied date.
UserContext
The pszDefinition field 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 ItemName element can contain one of the following values:
- DirectoryEntryProperty
- DirectoryNameSpace
- DirectoryPath
- DirectoryServer
- IsUserContext
- SessionId
- UserPath
- UserProperty
- UserName
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.

WebService

The pszDefinition field 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 pszDefinition, 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 pszDefinition field should not be formatted with spaces, tabs, and return characters. For example, a RequestContext variable for a Resource attribute would be passed in pszDefinition as follows:

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

Email CA about this topic