Skip Headers
Oracle® Access Manager Developer Guide
10g (10.1.4.3)

Part Number E12491-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

2 IdentityXML Functions and Parameters

IdentityXML functions allow you to programmatically perform operations in the Identity System applications. For example, using IdentityXML, you can perform functions such as the following:

This chapter discusses the following topics:

Note:

You can use WSDL instead of working directly with IdentityXML. The Identity System provides two WSDL files for each IdentityXML function. For more information, see "Benefits of WSDL".

2.1 About IdentityXML

IdentityXML enables you to write programs to perform various actions in the Identity System applications:

User Manager: The User Manager enables users and administrators to add, modify, and delete information about user identities. The User Manager enables end users to view other users and to modify their own identity information. The users that a person can view and the identity information that someone can modify depends on the privileges granted by a Master Administrator.

Group Manager: If you are an administrator, the Group Manager enables you to create or delete groups. This application enables users to view groups and to subscribe or unsubscribe from groups. A user's ability to create and delete groups and to subscribe to various groups depends on the privileges granted by an Master Administrator.

Organization Manager: If you are an administrator, the Organization Manager enables you to create and delete organizations and other objects (such as floor plans and assets) that do not belong in the User Manager or Group Manager. A user's ability to view objects, add them, and modify them depends on the privileges granted by a Master Administrator.

You can create programs with IdentityXML that perform actions such as adding a user to the User Manager or changing the attribute values of an entry in the Organization Manager.

You can also create programs that use the workflow capability of the Identity System. An Identity workflow enables you to link actions into an automated chain of events that are presented in the Identity System as a series of steps. When you create a workflow definition, you specify who is to perform each action, possibly calling out to external applications at one or more points in the process.

2.1.1 IdentityXML Overview

A process overview of planning an IdentityXML deployment is described elsewhere in this guide. See "IdentityXML and Identity Web Services" for details. Line-by-line descriptions of IdentityXML request and response format are also provided in that chapter. See "Formatting an IdentityXML Request" and "Formatting an IdentityXML Response" for details.

A number of IdentityXML samples are provided with your Oracle Access Manager installation. While these samples are not supported, they can provide you with an idea of how specific functions are specified. For a look at the samples, go to:

IdentityServer_install_dir\identity\oblix\unsupported\integsvcs

2.1.2 About IdentityXML Functions and Parameters

An IdentityXML function is a piece of code that serves the same purpose as an operation that can be performed manually in the GUI. A parameter is a component in the definition of a function. As described in the sections on IdentityXML functions, starting with "Common Functions", each IdentityXML function contains one or more parameters. For example, the IdentityXML function named workflowTicketSearch takes parameters such as targetapplication and tickettype. In this document, required parameters must be used in the IdentityXML statement. You can omit optional parameter names and values, in which case a default may apply. If no default value appears in the description, there is no default for the parameter.Entering an optional parameter's name but not its value causes an error.

2.1.2.1 Function Types

The following are basic types of IdentityXML functions:

  • Common functions: these are functions that are applicable to every Identity System application.

    See "Common Functions" for details.

  • User Manager functions: These functions perform actions in the User Manager application.

    See "User Manager Functions" for details.

  • Group Manager functions: These functions perform actions in the Group Manager application.

    See "Group Manager Functions" for details.

  • Org. Manager functions: These functions perform actions in the Org. Manager application.

    See "Organization Manager Functions" for details.

Each function performs one of two basic activities:

  • Testing to see if a particular person has the right to perform a specific operation

  • Actually performing the operation (for instance, finding a user)

2.1.2.2 Finding the Right Parameter Values for a Function

The values for many parameters are the DN values as they appear in the directory, rather than the display values. To find the DN values, you can use a tool that enables you to browse the directory and display DN entries. An example of such a tool is ldp.exe provided with Windows systems.

The values for many parameters that operate on attributes are the LDAP schema names of the attributes, rather than the display names. The following procedure provides the User Manager as an example of finding the schema name for an attribute.

To find schema names for an attribute

  1. Navigate to the Identity System Console.

  2. Click User Manager Configuration.

  3. Click Tabs.

  4. Click the link for the tab.

  5. Click Modify Attributes.

    An applet appears. The Attribute field in the top left corner shows a list of schema names for the attribute. The top right corner shows the Display Names field. This field shows the name of the attribute as it appears in the GUI.

2.2 Search Parameters

One basic component of many IdentityXML functions is the search operation. The following are search parameters that you can configure in IdentityXML functions that conduct searches.

Search parameters are expressed using a Condition tag to delimit a tuple. The following is an example:

<oblix:tab_id>Employees</oblix:tab_id> 
               <oblix:SearchParams> 
                  
                  <oblix:noOfFields>2</oblix:noOfFields>
                  <oblix:Condition>
                        <oblix:SearchAttr>cn</oblix:SearchAttr> 
                        <oblix:SearchOperation>OSM</oblix:SearchOperation> 
                        <oblix:SearchString>john</oblix:SearchString> 
                  </oblix:Condition>
                  <oblix:Condition>
                        <oblix:SearchAttr>cn</oblix:SearchAttr> 
                        <oblix:SearchOperation>OSM</oblix:SearchOperation> 
                        <oblix:SearchString>mary</oblix:SearchString> 
                  </oblix:Condition>
               </oblix:SearchParams>

The search parameters are as follows:

Parameter searchAttr
Description: An attribute whose string values are to be searched. Attributes are associated, by application, with one or more tabs. The attribute must have been marked as searchable for the tab name provided by the tab_id parameter. If it is not, an error is returned.

An administrator must have set the searchable flag for the attribute.

Rules: Required. Multivalued, 1 to n. For an explanation of n, see the noOfFields parameter.

Parameter searchOperation
Description: The way string data is to be selected. Legal entries all begin with the letter O, and the next two letters are an abbreviation of the search type.

Possible values are:

OSM: Substring match. Search results include entries whose value contains the data entered for this parameter.

OGE: Greater than or equal to. Search results include entries whose string value is greater than or equal to the data entered for this parameter.

OLE: Less than or equal to. Search results include entries whose string value is greater than or equal to the data entered for this parameter.

OBW: Begins with. Search results include entries whose string value begins with the data entered for this parameter.

OEW: Ends with. Search results include entries whose string value ends with the data entered for this parameter.

OSL: Sounds like. Attempts a phonic match on the entered data.

OEM: Exact match. Search results include entries whose string value is the same as the data entered for this parameter.

OOS: Oracle-specific substring match. Differs from OSM. Multiple search strings can be entered, delimited by spaces. Results include entries that match both of the two strings.

Any other value than the ones specified in this list returns an error (Invalid parameters).

Rules: Required. Single value.
Default: None. If an invalid value or no value is provided, an error is returned.

Parameter searchString
Description: Use this parameter to search for items that match a text string.
Rules: Required. Single value.
Default: If no value is specified, then the default is to do a blank search on the class attribute. This means, return everything that has any value (but not a NULL value) for the selected searchAttr attribute.

Parameter noOfFields
Description: When used in a search, this represents the number of attributes whose values are to be searched. Depending on the value of this parameter, you must provide the same number of conditions of SearchAttribute, SearchOperation and SearchString parameters. For example, if the noOfFields is 2, you would need to supply two conditions in the SearchParams element, and specify a set of search parameters within each condition.

The result of the search is an AND that satisfies all of the parameter sets.

The entered or default value for noOfFields must be greater than or equal to the number of sets. If it is greater, no error is reported, and the behavior is as if you had entered the correct value for n.

Rules: Optional. Single value, an integer value >= 1.
Default: 1

2.3 Attribute Parameters

Many IdentityXML functions can add, modify, and remove attributes. For example, a function can add new attributes and replace old attribute values in a user profile. The following sections describe parameters that find, add, and replace attribute values, the syntax for these parameters, and how to specify multiple values for an attribute.

IdentityXML requests for gathering the attribute list pertaining to modifying a profile (modifyUser, modifyGroup, and modifyObject), no longer depend on a panel in the Identity System. For these functions, the attribute parameter must be configured in the Identity System. However, the attribute parameter need not be included in a panel configured for a user, group, or object profile. The GUI-based request for gathering the attribute list pertaining to modifying a profile continues to require the attributes listed on a panel.

Note:

With IdentityXML, an attribute listed in the negativeListForEntityAttributes list in the globalparams.xml file can only be read and cached. For details, see the topic on tuning the internal DBAgent cache in the Oracle Access Manager Deployment Guide.

2.3.1 Syntax for Most Attribute Parameters

Attribute parameters are expressed as shown in the following examples.

<oblix:AttributeParams>
             <oblix:GenericAttribute>
             <!--Generic string type attribute-->
                     <oblix:AttrName>genphonenumber</oblix:AttrName>
                     <oblix:AttrOperation>REPLACE</oblix:AttrOperation>
                     <oblix:AttrOldValue>408</oblix:AttrOldValue>
                     <oblix:AttrNewValue>650</oblix:AttrNewValue>
             </oblix:GenericAttribute>
         </oblix:AttributeParams>

There are templates for specifying attribute values for the following display types: generic, password, Date, DateISO8601, and postal address. The following examples are provided.

Note:

The PasswordAttribute example illustrates a user changing her own password. In this case, the old password value is required. If a Master Administrator changes another user's password, the old password value is not required. If a Master Administrator modifies a user's password-type attribute "response" using the REPLACE operation, the old ÒresponseÓ value must be included.
<oblix:noOfFields>5</oblix:noOfFields>
         <oblix:AttributeParams>
              <oblix:GenericAttribute>
              <!--Generic string type attribute-->
                     <oblix:noOfFields>1</oblix:noOfFields>
                     <oblix:AttrName>cn</oblix:AttrName>
                     <oblix:AttrOperation>REPLACE</oblix:AttrOperation>
                     <oblix:AttrOldValue>jim</oblix:AttrOldValue>
                     <oblix:AttrNewValue>james</oblix:AttrNewValue>
              </oblix:GenericAttribute>

              <oblix:PasswordAttribute>
              <!--Password type attribute-->
                     <oblix:AttrName>userPassword</oblix:AttrName>
                     <oblix:AttrOperation>REPLACE</oblix:AttrOperation>
                     <oblix:AttrOldValue>mypassword</oblix:AttrOldValue>
                     <oblix:AttrNewValue>mynewpassword</oblix:AttrNewValue>
                    <oblix:AttrConfirmValue>mynewpassword</oblix:AttrConfirmValue>
               </oblix:PasswordAttribute>
 
               <oblix:DateAttribute>
               <!--Generic datetype attribute-->
                     <oblix:AttrName>date</oblix:AttrName>
                     <oblix:AttrOperation>REPLACE</oblix:AttrOperation>
                     <oblix:AttrOldValue>
                        <oblix:day>21</oblix:day>
                        <oblix:month>7</oblix:month>
                        <oblix:year>2003</oblix:year>
                        <oblix:hours>22</oblix:hours>
                        <oblix:minutes>33</oblix:minutes>
                        <oblix:seconds>11</oblix:seconds>
                     </oblix:AttrOldValue>
                     <oblix:AttrNewValue>
                        <oblix:day>2</oblix:day>
                        <oblix:month>10</oblix:month>
                        <oblix:years>2004</oblix:year>
                        <oblix:hours>15</oblix:hours>
                        <oblix:minutes>10</oblix:minutes>
                        <oblix:seconds>3</oblix:seconds>
                     </oblix:AttrNewValue>
                </oblix:DateAttribute>
 
                <oblix:DateAttributeISO8601>
                <!--ISO8601 date type attribute-->
                     <oblix:AttrName>date</oblix:AttrName>
                     <oblix:AttrOperation>REPLACE</oblix:AttrOperation>
                     <oblix:AttrOldValue>
                        <oblix:bahead_utc>2100</oblix:bahead_utc>
                        <oblix:tz_hours>22</oblix:tz_hours>
                        <oblix:tz_minutes>33</oblix:tz_minutes>
                     </oblix:AttrOldValue>
                     <oblix:AttrNewValue>
                        <oblix:bahead_utc>400</oblix:bahead_utc>
                        <oblix:tz_hours>10</oblix:tz_hours>
                        <oblix:tz_minutes>8</oblix:tz_minutes>
                     </oblix:AttrNewValue>
                </oblix:DateAttributeISO8601>
 
                <oblix:PostalAddressAttribute>
                <!--Postal address type attribute-->
                     <oblix:AttrName>addr</oblix:AttrName>
                     <oblix:AttrOperation>REPLACE</oblix:AttrOperation>
                     <oblix:AttrOldValue>
                        <oblix:field>123 Main St.</oblix:field>
                        <oblix:field>San Jose</oblix:field>
                     </oblix:AttrOldValue>
                     <oblix:AttrNewValue>
                     <oblix:noOfFields>2</oblix:noOfFields>
                        <oblix:field>100 Forge Dr.</oblix:field>
                        <oblix:field>Cupertino</oblix:field>
                     </oblix:AttrNewValue>
                </oblix:PostalAddressAttribute>
               </oblix:AttributeParams>

The noOfFields parameter is specified outside of the <oblix:AttributeParams> tag. The noOfFields parameter refers to the total number of attributes being specified. Each attribute must be enclosed in the appropriate tag element delimiters (for PostalAddress, GenericAttribute, and so on). An example:

<oblix:noOfFields>3</oblix:noOfFields> 
          <oblix:AttributeParams>
               <oblix:GenericAttribute>
                        <oblix:AttrName>cn</oblix:AttrName>
                        <oblix:AttrOperation>REPLACE</oblix:AttrOperation>
                        <oblix:AttrOldValue>jim</oblix:AttrOldValue>
                        <oblix:AttrNewValue>james</oblix:AttrNewValue>
               </oblix:GenericAttribute> 
               <oblix:GenericAttribute> 
                        <oblix:AttrName>title</oblix:AttrName>
                        <oblix:AttrOperation>REPLACE</oblix:AttrOperation>
                        <oblix:AttrOldValue>development</oblix:AttrOldValue>
                        <oblix:AttrNewValue>sales</oblix:AttrNewValue>
               </oblix:GenericAttribute> 
               <oblix:PostalAddressAttribute>
                        <oblix:AttrName>addr</oblix:AttrName>
                        <oblix:AttrOperation>REPLACE</oblix:AttrOperation>
                        <oblix:AttrOldValue>
                        <oblix:field>123 Main St.</oblix:field>
                        <oblix:field>San Jose</oblix:field>
                        </oblix:AttrOldValue>
                        <oblix:AttrNewValue>
                        <oblix:field>100 Forge Dr.</oblix:field>
                        <oblix:field>Cupertino</oblix:field>
                        </oblix:AttrNewValue>
               </oblix:PostalAddressAttribute> 
         </oblix:AttributeParams>
Parameter attrName
Description: The names of one or more attributes to be viewed or changed. Use the schema names from the directory, not the display names. The attribute must be configured in the Identity System and should be included in a panel configured for a user, group, or object profile.

A given attrName combination can appear only once. If it appears more than once, every operation except the first on that attribute name is ignored. Invalid attribute names or attribute names that are not associated with a panel for the associated function are ignored.

Optional for functions such as view or myGroupsProfile.

Rules: Required or Optional. Single value string, 1 to n.
Default: If no names are provided, only the attributes that the user is allowed to view are considered, depending upon the function.

Parameter attrOldValue
Description: This parameter is used when changing an attribute value. Use it to specify the old value for the attribute named by attrName.
Rules: Required if the attrOperation is a replace, otherwise ignored. Single value string. Multiple instances of attrOldValue can be replaced by the value supplied in attrNewValue.

Parameter attrOperation
Description: The type of operation to perform on the attribute. Legal values are:

ADD: Add the attribute name and value to the existing attributes. You receive an error if the combination exists already. Valid for LDAP attributes only.

DELETE: Delete the attribute and value from the existing attributes. You receive an error if the combination does not exist.

REPLACE: Delete the old attribute name and value combination and replace it with the new attribute name and value combination. If you use REPLACE, you must also use the attrOldValue parameter. Valid for LDAP attributes only.

REPLACE_ALL: Delete the old attribute and name combinations and replace them with new attribute name and value combinations. Use this if you do not care what the old values were, and just want to replace all of them. In this case, attrOldValue is not needed or used. Any other value returns an error message such as "Invalid value for attribute". Can be specified for LDAP attributes and template attributes.

Operations on attributes of display type ÒlocationÓ, for example obparent locationdn, are not supported through IdentityXML.

Rules: Required. Single value string.

Parameter attrNewValue
Description: The value that you want to add, delete, or replace for the attribute specified with attrName. Some attributes can have more than one value. To provide these, use attrNewValue again.

Dates contain at least three fields which must be specified, the day, month and year. Content must match the syntax defined for DATETYPE in oblixbaseparams.xml.

DateAttributeISO8601 takes at least one additional field, bahead_utc, to allow for a time zone offset. If the content of this suffix is Z, there is no offset and no additional suffixes. If the content is + or - then the offset must be supplied in hours and minutes, using the tz_hours and tz-minutes, respectively.

Passwords contain three fields which must be specified: the new value, confirmation value, and old value.

For an add or modify operation: you must specify the new password as well as the confirmation. Also:

  • If you modify your own password, you must provide the old password value. You can use the REPLACE operation and must include the old password value.

  • A Master Administrator can modify another user's password using the REPlACE operation, without providing the old password.

The attrOperation in this case can be any of the values ADD, REPLACE, or REPLACE_ALL.

  • If a Master Administrator modifies a user's password-type attribute "response" using the REPLACE operation, the old ÒresponseÓ value must be included.

  • If you need to delete the password-type attribute, specify the attrOperation as DELETE. You do not need to provide the old value or new value parameters.

Postal addresses allow for six fields.

Legal values for attributes generally match what is shown in the GUI that corresponds to the function to be executed. Some exceptions exist, however, and are described at "Exceptions to Attribute Values" on page 2-14.

Rules: Required. Single value

Parameter NoOfFields (when used with workflow and modify
Description: When used with workflow and modify attributes, this is the number of attributes to be modified.
Rules: Required. Single value, integer.

2.3.2 Syntax for Lost Password Management Attribute Parameters

As described in the section on lost password management in the Oracle Access Manager Identity and Common Administration Guide, you can configure multiple challenge phrases and responses. You can add, modify, and delete challenge phrases and responses when performing a modify profile operation, or when performing Create, Self-Registration, and Change Attribute workflow operations.

The challenge phrase and response attribute values are stored as a single value in the directory.

The following sections describe the IdentityXML syntax for challenge phrases and responses in detail.

2.3.2.1 Add Operation

The following are required when adding challenge phrases and responses:

  • The number of ChallengeValue and ResponseValue elements must not exceed the minimum number of challenges to be configured in the user entry.

    For example, if the administrator configured the minimum number of challenges as 3, and 2 challenges exist in the user entry, the Add operation can only add 1 more challenge.

  • Do not include attrOldValue elements when adding a challenge phrase or response.

  • In each challenge response, provide an AttrConfirmValue element for every AttrNewValue element.

    The values of these two elements must be an exact match, including leading and trailing spaces and case.

The following is an example of IdentityXML for adding a challenge phrase:

<oblix:ChallengeAttribute>
      <oblix:AttrName>genChallengePhrase</oblix:AttrName>   
      <oblix:AttrOperation>ADD</oblix:AttrOperation>
            <oblix:ChallengeValue>
                        <oblix:AttrNewValue>phrase1</oblix:AttrNewValue>
            </oblix:ChallengeValue>
            <oblix:ChallengeValue>
                        <oblix:AttrNewValue>phrase2</oblix:AttrNewValue>
            </oblix:ChallengeValue>
            <oblix:ChallengeValue>
                        <oblix:AttrNewValue>phrase3</oblix:AttrNewValue>
            </oblix:ChallengeValue>
</oblix:ChallengeAttribute>

The following is an example of IdentityXML for adding a challenge response:

<oblix:ResponseAttribute>
      <oblix:AttrName>genChallengePhraseResponse</oblix:AttrName>
      <oblix:AttrOperation>ADD</oblix:AttrOperation>
             <oblix:ResponseValue>
                        <oblix:AttrNewValue>response1</oblix:AttrNewValue>
                        <oblix:AttrConfirmValue>response1</oblix:AttrConfirmValue>
             </oblix:ResponseValue>
             <oblix:ResponseValue>
                        <oblix:AttrNewValue>response2</oblix:AttrNewValue>
                        <oblix:AttrConfirmValue>response2</oblix:AttrConfirmValue>
             </oblix:ResponseValue>
             <oblix:ResponseValue>
                        <oblix:AttrNewValue>response3</oblix:AttrNewValue>
                        <oblix:AttrConfirmValue>response3</oblix:AttrConfirmValue>
             </oblix:ResponseValue>
</oblix:ResponseAttribute>

2.3.2.2 Delete Operation

The following are requirements for deleting challenge phrases and responses:

  • Ensure that no lost password management policy is in effect for this user.

  • Only one ChallengeValue element is permitted for the challenge phrase.

  • Do not include attrOldValue elements when deleting a challenge phrase.

  • No ResponseValue element is permitted when deleting a challenge response.

    As a result, you also do not include attrOldValue, AttrNewValue, or AttrConfirmValue elements.

The following is an example of deleting the challenge phrase and response:

<oblix:ChallengeAttribute>
      <oblix:AttrName>genChallengePhrase</oblix:AttrName>
      <oblix:AttrOperation>DELETE</oblix:AttrOperation>
             <oblix:ChallengeValue>
                        <oblix:AttrNewValue>phrase1</oblix:AttrNewValue>
             </oblix:ChallengeValue>
</oblix:ChallengeAttribute>
<oblix:ResponseAttribute>
      <oblix:AttrName>genChallengePhraseResponse</oblix:AttrName>
      <oblix:AttrOperation>DELETE</oblix:AttrOperation>
</oblix:ResponseAttribute>

2.3.2.3 Replace Operations

Replace operations can only be used if the values to be replaced exist in the user entry in the directory. A Replace is permitted for intermediate values.

The following are required when you replace challenge phrases and responses:

  • The number of ChallengeValue and ResponseValue elements cannot exceed the minimum number of challenges if a lost password management policy exists.

    If no lost password management policy is in effect for the user, a Replace operation for only one challenge and one response is permitted.

  • Challenge phrases must have an attrOldValue element for every attrNewValue element.

  • Challenge responses must have an AttrOldValue element and an AttrConfirmValue element for every AttrNewValue element.

    The values of the AttrNewValue element and the AttrConfirmValue element must be an exact match, including leading and trailing spaces and case.

  • The value of the AttrOldValue element must match the value for the user entry in the directory.

The following is an example of replacing the challenge phrase and response:

<oblix:ChallengeAttribute>
      <oblix:AttrName>genChallengePhrase</oblix:AttrName>
      <oblix:AttrOperation>REPLACE</oblix:AttrOperation>
             <oblix:ChallengeValue>
                        <oblix:AttrOldValue>phrase2</oblix:AttrOldValue>
                        <oblix:AttrNewValue>phrase2_new</oblix:AttrNewValue>
             </oblix:ChallengeValue>
             <oblix:ChallengeValue>
                        <oblix:AttrOldValue>phrase3</oblix:AttrOldValue>
                        <oblix:AttrNewValue>phrase3_new</oblix:AttrNewValue>
             </oblix:ChallengeValue>
</oblix:ChallengeAttribute>

<oblix:ResponseAttribute>
      <oblix:AttrName>genChallengePhraseResponse</oblix:AttrName>
      <oblix:AttrOperation>REPLACE</oblix:AttrOperation>
            <oblix:ResponseValue>
                        <oblix:AttrOldValue>response2</oblix:AttrOldValue>
                        <oblix:AttrNewValue>response2_new</oblix:AttrNewValue>
                        <oblix:AttrConfirmValue>response2_new</oblix:AttrConfirmValue>
            </oblix:ResponseValue>
            <oblix:ResponseValue>
                        <oblix:AttrOldValue>response3</oblix:AttrOldValue>
                        <oblix:AttrNewValue>response3_new</oblix:AttrNewValue>
                        <oblix:AttrConfirmValue>response3_new</oblix:AttrConfirmValue>
            </oblix:ResponseValue>
 </oblix:ResponseAttribute>

If a lost password policy is in effect and Allow Duplicate Responses is enabled, there are times when an index attribute is required in a ResponseValue element. When two responses have the same value, and you want to change only one of them, you must specify the index in the ResponseValue element. When two responses have same value and no index is specified in the request, both occurrences are modified with the new value.

For example, if challenge phrases A and B have the same response C, the Replace operation could be configured with an index to differentiate the two challenge phrase and response pairs (A-C and B-C).

The following is an example of a modifyUser function that updates two different challenge phrases that have identical response phrases:

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:oblix="http://www.oblix.com" xmlns:soapenv="http://schemas-xmlsoap.org/soap/envelope/">

<soapenv:Body>
<oblix:authentication>
      <oblix:login>admin</oblix:login>
            <oblix:password>oblix</oblix:password>
      </oblix:authentication>

<oblix:request application="userservcenter" function="modifyUser" version="NPWSDL1.0">
    <oblix:params>
    <oblix:uid>cn=user1,ou=Policy2,o=company,c=us</oblix:uid>
    <oblix:noOfFields>2</oblix:noOfFields>
    <oblix:AttributeParams>
     <oblix:ChallengeAttribute>
            <oblix:AttrName>genChallengePhrase</oblix:AttrName>
                <oblix:AttrOperation>REPLACE</oblix:AttrOperation>
                <oblix:ChallengeValue>
                <oblix:AttrOldValue>phrase1</oblix:AttrOldValue>
                <oblix:AttrNewValue>phrase1_new</oblix:AttrNewValue>
                </oblix:ChallengeValue>
                <oblix:ChallengeValue>
                <oblix:AttrOldValue>A</oblix:AttrOldValue>
                <oblix:AttrNewValue>A_new</oblix:AttrNewValue>
                </oblix:ChallengeValue>
                <oblix:ChallengeValue>
               <oblix:AttrOldValue>B</oblix:AttrOldValue>
               <oblix:AttrNewValue>B_new</oblix:AttrNewValue>
                </oblix:ChallengeValue>
   </oblix:ChallengeAttribute>

   <oblix:ResponseAttribute>
                <oblix:AttrName>genChallengePhraseResponse</oblix:AttrName>
                <oblix:AttrOperation>REPLACE</oblix:AttrOperation>
                <oblix:ResponseValue>
                <oblix:AttrOldValue>response1</oblix:AttrOldValue>
                <oblix:AttrNewValue>response1_new</oblix:AttrNewValue>
                <oblix:AttrConfirmValue>response1_new</oblix:AttrConfirmValue>
                 </oblix:ResponseValue>
            <oblix:ResponseValue index="1">
                <oblix:AttrOldValue>C</oblix:AttrOldValue>
                <oblix:AttrNewValue>C_new1</oblix:AttrNewValue>
                <oblix:AttrConfirmValue>C_new1</oblix:AttrConfirmValue>
                </oblix:ResponseValue>
                <oblix:ResponseValue index="2">
                <oblix:AttrOldValue>C</oblix:AttrOldValue>
                <oblix:AttrNewValue>C_new2</oblix:AttrNewValue>
                <oblix:AttrConfirmValue>C_new2</oblix:AttrConfirmValue>
                </oblix:ResponseValue>
   </oblix:ResponseAttribute>

   </oblix:AttributeParams>
   </oblix:params>
  </oblix:request>
 </soapenv:Body>
</soapenv:Envelope>

2.3.2.4 Replace_All Operations

The Replace_All operation replaces all challenges or responses.

The following are required when you replace all challenge phrases and responses:

  • The number of ChallengeValue and ResponseValue elements must be exactly same as the minimum number of challenges to be configured if a lost password policy exists for the user.

    If no lost password management policy is in effect for the user, you can only replace one value.

  • For challenge phrases, do not include AttrOldValue elements in the ChallengeValue element.

  • For challenge phrases, an AttrNewValue element is required.

  • For challenge responses, if a user is replacing their own response, the AttrOldValue element must match the value of the user entry in the directory.

    If any other user is performing the Replace_All operation, the AttrOldValue elements are not required in the request.

  • Replace_All can be used even if there is no challenge phrase or response in the user entry in the directory.

  • Challenge responses must have an AttrConfirm element for every AttrNewValue element.

    The values of the AttrNewValue element and the AttrConfirmValue element must be an exact match, including leading and trailing spaces and case.

The following is an example of a Replace_All operation:

<oblix:ChallengeAttribute>
      <oblix:AttrName>genChallengePhrase</oblix:AttrName>
      <oblix:AttrOperation>REPLACE_ALL</oblix:AttrOperation>
            <oblix:ChallengeValue>
                        <oblix:AttrNewValue>phrase1_new</oblix:AttrNewValue>
            </oblix:ChallengeValue>
            <oblix:ChallengeValue>
                        <oblix:AttrNewValue>phrase2_new</oblix:AttrNewValue>
            </oblix:ChallengeValue>
            <oblix:ChallengeValue>
                        <oblix:AttrNewValue>phrase3_new</oblix:AttrNewValue>
            </oblix:ChallengeValue>
</oblix:ChallengeAttribute>

<oblix:ResponseAttribute>
      <oblix:AttrName>genChallengePhraseResponse</oblix:AttrName>
      <oblix:AttrOperation>REPLACE_ALL</oblix:AttrOperation>
            <oblix:ResponseValue>
                        <oblix:AttrNewValue>response1_new</oblix:AttrNewValue>
                        <oblix:AttrConfirmValue>response1_new</oblix:AttrConfirmValue>
            </oblix:ResponseValue>
            <oblix:ResponseValue>
                        <oblix:AttrNewValue>response2_new</oblix:AttrNewValue>
                        <oblix:AttrConfirmValue>response2_new</oblix:AttrConfirmValue>
            </oblix:ResponseValue>
            <oblix:ResponseValue>
                        <oblix:AttrNewValue>response3_new</oblix:AttrNewValue>
                        <oblix:AttrConfirmValue>response3_new</oblix:AttrConfirmValue>
           </oblix:ResponseValue>
</oblix:ResponseAttribute>

2.4 Exceptions to Attribute Values

In general, legal values for attributes used in the functions match those that are used in the GUI. However, exceptions exist. Table 2-1 lists attributes with values that differ from those shown in the GUI for the function.

Table 2-1 Attribute Value Exceptions

Attribute Name Description Values

obgroupsubscribenotification

If this attribute is set, the affected UID is notified when the UID is subscribed or unsubscribed from a group.

NotifyUponSubscription: If the user is to be notified when subscribed to a group (matches subscribe for the GUI).

NotifyUponUnsubscription: If the user is to be notified when unsubscribed from a group (matches unsubscribe for the GUI).

obgroup subscriptiontype

This attribute is set to define the limits under which users can be subscribed to the group.

SubscriptionPolicyOpen: Matches Open for the GUI.

SubscriptionPolicyOpenFilter: Matches Open with Filter for the GUI.

SubscriptionPolicyControlledWorkflow: Matches Controlled through Workflow for the GUI.

SubscriptionPolicyClosed: Matches Closed for the GUI.


2.5 Common Functions

The following are functions used throughout the Identity System applications. Note that all functions follow a similar syntax:

<oblix:request application="userservcenter|groupservcenter|objservcenter" function="function name" version="version">

For example:

<oblix:request application="userservcenter" function="search" version="NPWSDL1.0">

Note:

The version tag is required if you are using IdentityXML with Oracle Access Manager 6.5 and higher versions.

For documentation of the pre-6.5 IdentityXML version tag, see the following:

http://www.oracle.com/technology/

2.5.1 Search for entries based on some criteria

Function name search
Request example: <oblix:request application="userservcenter" function="search" version="NPWSDL1.0">
Description: Search for an entry or entries. The entries must be in a searchbase accessible to the user.
Works with: Group, Organization, and User Manager.
Results: The output is defined by the schema file oblix\WebServices\XMLSchema\component_search.xsd
Output schema: oblix\WebServices\XMLSchema\searchResults.xsd
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\common_search.wsdl
Parameters  
SearchAttr Required. See "Search Parameters" for details.
SearchOperation Required. See "Search Parameters" for details.
SearchString Required. See "Search Parameters" for details.
attrname Optional. If no value is given, the default table view attributes are used. See "Attribute Parameters" for details.
noOfFields Optional. See "Attribute Parameters" for details.
noOfRecords The maximum number of entries to return in the search results. Overridden by the showAllResults parameter.

Rules: Optional. Single value, an integer value >=1.

Default: A value obtained from the defaultDisplayResultVal parameter in the oblixbaseparams.xml catalog. Otherwise, this value is obtained from the custom cookie.

showAllResults Specifies that all results of the search be returned. If the value is true, it overrides the value of the noOfRecords parameter.

Rules: Optional. True or false.

Default: false, meaning return results up to the limit imposed by the noOfRecords parameter.

sortBy What attribute to use to sort the results.

Rules: Optional. Single value.

Default: if no value is specified, the class attribute for the structural object class of the tab specified by tab_id is used.

sortOrder The sort order, ascending or descending.

Rules: Optional. Single value, ascending or descending

Default: ascending

startFrom Use this parameter for a long list of search results, to skip over a selected number of items and start the list with a specified item. For example, if 100 entries were found by the search, entering a value of 80 for this parameter gives a response showing only items 80 through 100.

Rules: Optional. Single value, integer.

Default: 1, to start displaying from the beginning of the search results list.

tab_id The name of the tab that describes the information category you want to search within. For User Manager and Group Manager only one tab is allowed. For Organization Manager, multiple tabs are allowed.

If omitted, the Identity System uses a default value for tab_id of the leftmost tab. Oracle recommends that you always provide a value for tab_id. Organization Manager enables you to change the order in which tabs are displayed. If you rely on the default tab_id, your portal functions would be affected.

The tab_id is a number. To get the number, go to the configuration menu for the application. Choose configure tab. Position the cursor on the tab whose tab_id you want, and right click, then click the tab name whose tab_id you want. Select Open in new window. In the URL displayed at the top of the page, you find the value for tab_id.

Rules: Optional. Single value

Default: For User Manager and Group Manager, which have only a single tab, that tab is assumed.

For Organization Manager, which has multiple tabs, the leftmost tab is assumed.


Example 2-1 illustrates a search function.

Example 2-1 Example of a Search in the User Manager for the Name "John"

<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas-xmlsoap.org/soap/envelope/"> <SOAP-ENV:Body>
<oblix:authentication xmlns:oblix="http://www.oblix.com" type="basic">                           <oblix:login>J.Smith</oblix:login>
<oblix:password>J.Smith</oblix:password> 
</oblix:authentication> 
<oblix:request application="userservcenter" function ="search" version="NPWSDL1.0">
<oblix:params>
<oblix:SearchParams>
<oblix:Condition>
<oblix:SearchAttr>cn</oblix:SearchAttr>
<oblix:SearchOperation>OSM</oblix:SearchOperation>
<oblix:SearchString>john</oblix:SearchString>
</oblix:Condition>
</oblix:SearchParams>
</oblix:params>
</oblix:request>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

2.5.1.1 Search for all pending, completed, or all tickets

Function name workflowTicketSearch
Request example: <oblix:request application="userservcenter" function="workflowTicketSearch" version="NPWSDL1.0">
Description: Search for pending, or completed, or all workflow requests.
Works with: Group Manager, Organization Manager, User Manager
Results: The output is defined by the schema file oblix\WebServices\XMLSchema\component_search.xsd.
Output schema: oblix\WebServices\XMLSchema\searchResults.xsd
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ common_workflowTicketSearch.wsdl
Parameters  
requestType The request queue type to search

incomingRequests: Requests you need to process.

outgoingRequests: Requests you have originated.

Rules: Required. Single value.

targetApplication The application to search for tickets. To search all applications, use the value allApplications. To search a specific application, enter the application name:

groupservcenter: For Group Manager.

objservcenter: For Organization Manager.

userservcenter: For User Manager.

Rules: Required. Single value.

ticketType The status type for the requests to be searched. There are three possible entries:

WfAllTickets: Search for all requests, regardless of status.

WfCompletedTickets: Search for requests that have been completely processed.

WfPendingTickets: Search for requests that are pending, waiting to be processed.

Rules: Required. Single value.

days Look for requests issued in the past n days. The Identity System considers a day to be the 24-hour period from when the ticket was created, not a calendar day.

Rules: Optional. Single value, an integer >=1.

Default: 0, meaning look as far back as the oldest request.

noOfRecords A maximum number of entries to be returned in the search results.This is overridden by the showAllResults parameter.

Rules: Optional. Single value, an integer value >=1.

Default: A value obtained from the defaultDisplayResultVal parameter in the oblixbaseparams.xml catalog. Otherwise this value is obtained from the custom cookie.

sortBy What attribute to use to sort the results.

Rules: Optional. Single value.

Default: if no value is specified, the class attribute of the structural object class of the tab specified by tab_id is used. For workflow tickets, the class sorting attribute can have only one of the following values:

obticketid: For Ticket Number

obapp: For Application Name

obactionname: For Action

obwfstatus: For Status

obwftypename: For Request Type

obtargetdn: For Requested For

obcurrentdn: For Requested by

obactordn: For Action Taker

obdateprocessed: For Date Processed

oblockedby: For Locked By

obsubflow: For Subflow Number

If the attribute is invalid, an error is returned, such as "Invalid value for parameter sortBy." If no attribute is specified, the default is the first attribute (most likely obticketid) in the administrator-configured workflow ticket search table. You can see this table by looking at the Identity System Console, Common Configuration, Workflow Panels, Ticket Search Table.

sortOrder The sort order, ascending or descending. An invalid order gives an error message.

Rules: Optional. Single value, ascending or descending.

Default: ascending

startFrom Use this parameter for a long list of search results, to skip a number of items and start the list with a specified item. For example, if 100 entries were found by the search, entering a value of 80 for this parameter gives a response showing only items 80 through 100.

Rules: Optional. Single value, integer.

Default: 1, to start from the beginning of the search results list.


workflowTicketSearch Notes

If the mode is dataonly, the possible values for obwfstatus are integers, as follows:

Unknown = -1

Success = 0

Failed = 1

PendingUser = 2

PendingSubflow = 3

PendingPreAction = 4

PendingPostAction = 5

PendingUserInPre = 6

PendingUserInPost = 7

LastStepDone = 8

Asynch = 9

PendingExecution = 10

Cancelled = 11

PendingPreNotify = 12

PendingPreSubflow = 13

PendingPostNotify = 14

TriggerSubflows = 15

ForceCommit = 16

Retry = 17

PendingRetry = 18

For the output [integer/string], the "store-as" is an integer. The string is the value displayed in the user interface.

Example 2-2 illustrates a search function for incoming tickets.

Example 2-2 Example of Searching for Your Incoming Tickets in the User Manager

<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas-xmlsoap.org/soap/envelope/">

<SOAP-ENV:Body>
<oblix:authentication xmlns:oblix="http://www.oblix.com" type="basic">
<oblix:login>J.Smith</oblix:login>
<oblix:password>J.Smith</oblix:password>
</oblix:authentication>
<oblix:request application="userservcenter" function="workflowTicketSearch" version="NPWSDL1.0">

<oblix:params>
<oblix:tab_id>Employees</oblix:tab_id>
<oblix:requestType>incomingRequests</oblix:requestType>
<oblix:ticketType>allTickets</oblix:ticketType>
</oblix:params>
</oblix:request>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

2.5.1.2 Get information on a particular workflow ticket

Function name workflowTicketInfo
Request example: <oblix:request application="userservcenter" function="workflowTicketInfo" version="NPWSDL1.0">
Description: Get information about a specific request.
Works with: Group Manager, Organization Manager, User Manager.
Results: The output is defined by the schema file oblix\WebServices\XMLSchema\wfTicketInfo.xsd
Output schema: If the operation is successful, it returns the If the operation is successful, it returns the profile of the group, according to the following XML Schema: oblix\WebServices\XMLSchema\workflowTicketInfo.xsd
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ common_workflowTicketInfo.wsdl
Parameters  
workflowInstanceDn The DN of the workflow for which information is required. The DN for the workflow is shown in the workflow definition view. See the Oracle Access Manager Identity and Common Administration Guide.

Rules: Required. Single DN value.

workflowStepInstanceId A step in the workflow specified by workflowInstanceDn for which information is required.

Rules: Required. Single integer value.


2.5.1.3 Resume asynchronous workflows

Function name asynchResumeWorkflowProcess
Request example: <oblix:request application="asynch" function="asynchResumeWorkflowProcess" version="NPWSDL1.0">
Description: This function enables the continuation of a workflow in which an Identity Event API call returned a status of STATUS_PPP_WF_ASYNC. The asyncResumeWorkflowProcess function takes a workflow instance DN and a step ID as input.

asynch_retcode =0 to resume the workfkow

asynch_retcode =1 to abort the workflow default value =0

See Chapter 3, "Identity Event Plug-in API" for details.

One or more of the parameters described as optional in the "Parameters" section of this table must be provided, depending on the requirements of the particular workflow.

Works with: Asynchronous workflows.
Output schema: Currently there is a bug which always produces the output in html format like this:

<html>The action completed successfully. Please refer to the workflow page. </html>

WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ common_asynchResumeWorkflowProcess.wsdl
Parameters  
workflowInstanceDn The DN of the workflow for which information is required. The DN for the workflow is shown in the workflow definition view. See the Oracle Access Manager Identity and Common Administration Guide.

Rules: Required. Single DN value.

workflowStepInstanceId A step in the workflow specified by workflowInstanceDn for which information is required.

Rules: Required. Single integer value.

attrName Optional. See "Attribute Parameters" for details.
attrOldValue Optional. See "Attribute Parameters" for details.
attrOperation Optional. See "Attribute Parameters" for details.
attrNewValue Optional. See "Attribute Parameters" for details.
NoOfFields Optional. See "Attribute Parameters" for details.

Example 2-3 and Example 2-4 illustrate resuming an asynchronous workflow

Example 2-3 Resuming an Asychronous Workflow (1 of 2)

<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas-xmlsoap.org/soap/envelope/">

<SOAP-ENV:Body>
<oblix:authentication xmlns:oblix="http://www.oblix.com" type="basic"> <oblix:login>authenticationAttribute</oblix:login> <oblix:password>authenticationPassword</oblix:password>
</oblix:authentication> 

<oblix:request function="asynchResumeWorkflowProcess" version="NPWSDL1.0"> 
<oblix:params> 
<oblix:param name="workflowInstanceDn">obwfinstanceid=wfinstanceid,
obcontainerId=workflowInstances,o=Oblix,ou=Apps, o=mycompany</oblix:param> <oblix:param name="workflowStepInstanceId">1</oblix:param>
<!-- See Return codes at the bottom of this file --> 
<oblix:param name="asynch_retcode">0</oblix:param>

<!-- Add the attributes required by the workflow in the order the --> 
<!-- workflow expects them. Include even the optional and hidden fields. --> 
<!-- Start with n=1 --> 
<oblix:param name="attrName_n">attr. name</oblix:param> 
<oblix:param name="attrNewValue_n">attr. value</oblix:param>
<!-- ... all other workflow expected attributes --> 
<!-- The operation depends on what you want to do with the attributes. --> 
<!-- In this case I know the attribute does not currently exist in the user --> 
<!-- entry so I want to add them. However, you might want to replace the --> 
<!-- values of the attributes, and so on. --> 
<oblix:param name="attrOperation">ADD</oblix:param> 
</oblix:params> 
</oblix:request> 

</SOAP-ENV:Body> 
</SOAP-ENV:Envelope>
<!-- The values for the return code, async_retcode, is as follows: -->
<!-- 0 - Success -->
<!-- 1 - Action Failed -->
<!-- -11 - Pre-Action Failed -->
<!-- -12 - Post-Action Failed --> 
<!-- -13 - External-Action Failed -->

Example 2-4 Resuming an Asychronous Workflow (2 of 2)

<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas-xmlsoap.org/soap/envelope/">

<SOAP-ENV:Body>
<oblix:authentication xmlns:oblix="http://www.oblix.com" type="basic"> <oblix:login>authenticationAttribute</oblix:login> <oblix:password>authenticationPassword</oblix:password>
</oblix:authentication> 

<oblix:request function="asynchResumeWorkflowProcess" version="NPWSDL1.0"> 
<oblix:params> 
<oblix:workflowInstanceDn>obwfinstanceid=wfinstanceid,obcontainerId=workflowInstances,o=Oblix,ou=Apps, o=mycompany</oblix:workflowInstanceDn> 
<oblix:workflowStepInstanceId>1</oblix:workflowStepInstanceId>
<!-- See Return codes at the bottom of this file --> 
<oblix:asynch_retcode>0</oblix:asynch_retcode>
<!-- Add the attributes required by the workflow in the order the --> 
<!-- workflow expects them. Include even the optional and hidden fields. --> 
   <oblix:attributeParams>
        <oblix:genericAttribute>
         <oblix:attrName> name of attr </oblix:attrName>
         <oblix:attrNewValue> value of attr </oblix:attrNewValue>
         <oblix:attrOperation> operation like ADD or DELETE or REPLACE or REPLACE_ALL</oblix:attrOperation>
       </oblix:genericAttribute>
       <!-- any more attributes -->
 
<!-- ... all other workflow expected attributes --> 
   </oblix:attributeParams>
 
</oblix:params> 
</oblix:request> 
</SOAP-ENV:Body> 
</SOAP-ENV:Envelope>
<!-- The values for the return code, async_retcode, is as follows: -->
<!-- 0 - Success -->
<!-- 1 - Action Failed -->
<!-- -11 - Pre-Action Failed -->
<!-- -12 - Post-Action Failed --> 
<!-- -13 - External-Action Failed -->

2.5.1.4 Subscribe self to group

Function name subscribe
Request example: <oblix:request application="groupservcenter" function="subscribe" version="NPWSDL1.0">
Description: Add (subscribe) yourself to a group. The response returns the profile for the group.
Works with: Group Manager.
Results: The output is the profile of the group, defined by the schema file oblix\WebServices\XMLSchema\gsc_profile.xsd.
Output schema: If operation is successful, it returns the profile of the group, according to the following XML Schema.

oblix\WebServices\XMLSchema\gsc_profile.xsd

If operation fails, you get an error message like:

<SOAP-ENV:Envelope>
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet href="0" type="text/xsl"?> 
<Oblix> 
<ObError> 
<ObRequestInfo> 161660048 </ObRequestInfo> <ObTextMessage> You do not have access rights. </ObTextMessage> 
</ObError> 
</Oblix> 
</SOAP-ENV:Envelop>
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ gm_subscribe.wsdl
Parameters  
uid In this case, uid means the DN of the group being subscribed to.

Rules: Required. Single value, a DN.


Note:

Subscription policies are not required for adding users to groups. For example, if you have pre-existing groups and want to add users to these groups, you can set the relevant access control policies on the uniquemember attribute and use the Selector to add members. However, if you want users to subscribe themselves to groups, you implement this using a subscription functionality.

2.5.1.5 Unsubscribe self from group

Function name unsubscribe
Request example: <oblix:request application="groupservcenter" function="unsubscribe" version="NPWSDL1.0">
Description: Remove (unsubscribe) yourself from a group.
Works with: Group Manager.
Results: The response returns the profile of the group, defined by the schema file: oblix\WebServices\XMLSchema\gsc_profile.xsd.
Output schema: If operation is successful, it returns the profile of the group, according to the following XML Schema: oblix\WebServices\XMLSchema\gsc_profile.xsd

If operation fails, you get an error message like:

<SOAP-ENV:Envelope>
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet href="0" type="text/xsl"?> <Oblix>
<ObError>
<ObRequestInfo> 161660048 </ObRequestInfo> <ObTextMessage> You do not have access rights. </ObTextMessage>
</ObError>
</Oblix>
</SOAP-ENV:Envelop>
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ gm_unsubscribe.wsdl
Parameters  
uid The DN of the group being unsubscribed from.

Rules: Required. Single value, a DN.


2.5.1.6 Subscribe user to group

Function name subscribeUserToGroup
Request example: <oblix:request application="groupservcenter" function="subscribeUserToGroup" version="NPWSDL1.0">
Description: Subscribe a user other than yourself to a group. The other user does not need to be logged in.
Works with: Group Manager.
Results: The output is the profile of the group, defined by the schema file oblix\WebServices\XMLSchema\gsc_profile.xsd
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ gm_subscribeUserToGroup.wsdl
Parameters  
uid The DN of the group entry.
proxysourceuid The DN for a non-logged-in user (proxy user) who is being subscribed.

Rules: Required. Single value, a DN.


Example 2-5 illustrates subscribing a user to a group.

Example 2-5 Subscribing Robert Fulton to a Group

<?xml version="1.0"?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas-xmlsoap.org/soap/envelope/"> <SOAP-ENV:Body> <oblix:authentication xmlns:oblix="http://www.oblix.com" type="basic"> <oblix:login>J.Smith</oblix:login> <oblix:password>J.Smith</oblix:password> </oblix:authentication> 
<oblix:request application="groupservcenter" function="subscribeUserToGroup" version="NPWSDL1.0">
<oblix:params>
<oblix:proxysourceuid>
cn=Robert Fulton, ou=Corporate, o=Company, c=US
</oblix:proxysourceuid>
<oblix:uid>
cn=Marketing Team, ou=Marketing, o=Company, c=US
</oblix:uid>
</oblix:params> 
</oblix:request> 
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Note:

Subscription policies are not required for adding users to groups. For example, if you have pre-existing groups and want to add users to these groups, you can set the relevant access control policies on the uniquemember attribute and use the Selector to add members. However, if you want users to subscribe themselves to groups, you implement this using a subscription functionality.

2.5.1.7 Unsubscribe user from group

Function name unsubscribeUserFromGroup
Request example: <oblix:request application="groupservcenter" function="unsubscribeUserFromGroup" version="NPWSDL1.0">
Description: Unsubscribe a user other than yourself from a group. The other user does not need to be logged in.
Works with: Group Manager.
Results: The response returns the profile of the group, defined by the schema file: oblix\WebServices\XMLSchema\gsc_profile.xsd.
Output schema: If operation is successful, it returns the profile of the group, according to the following XML Schema.

oblix\WebServices\XMLSchema\gsc_profile.xsd

If operation fails, you get an error message like:

<SOAP-ENV:Envelope> 
<?xml version="1.0" encoding="UTF-8"?> 
<?xml-stylesheet href="0" type="text/xsl"?> 
<Oblix>
<ObError>
<ObRequestInfo> 161660048 </ObRequestInfo>
<ObTextMessage> You do not have access rights. </ObTextMessage>
</ObError>
</Oblix>
</SOAP-ENV:Envelop>
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ gm_unsubscribeUserFromGroup.wsdl
Parameters  
uid The DN of the group being unsubscribed from.

Rules: Required. Single value, a DN.

proxysourceuid The DN for a non-logged-in user (proxy user) who is being unsubscribed.

Rules: Required. Single value, a DN.


Example 2-6 illustrates unsubscribing from a group.

Example 2-6 Unsubscribing Robert Fulton From a Group

<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas-xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
   <oblix:authentication xmlns:oblix="http://www.oblix.comÓ type="basic">
      <oblix:login>J.Smith</oblix:login>
      <oblix:password>J.Smith</oblix:password>
   </oblix:authentication>
<oblix:request application="groupservcenter"
      function="unsubscribeUserFromGroup" version="NPWSDL1.0">
   <oblix:params>
      <oblix:proxysourceuid=cn=Robert Fulton, ou=Corporate, o=Company, 
         c=US</oblix:proxysourceuid>
      <oblix:uid>cn=Marketing Team, ou=Marketing, o=Company,c=US</oblix:uid>
   </oblix:params>
   </oblix:request>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas-xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>

2.6 User Manager Functions

If you are an administrator, the User Manager enables you to add, modify, and delete user identities. The User Manager typically enables end users to view other users and to modify their own identity information. The users that a person can view and the identity information that someone can modify depends on the privileges granted by a Master Administrator.

The following IdentityXML functions allow you to programmatically access the User Manager application. Note that all functions follow a similar syntax:

<oblix:request application="userservcenter" function="name" version="version">

For example:

<oblix:request application="userservcenter" function="canIViewUserProfile" version="NPWSDL1.0">

Note:

The version tag is required if you are using IdentityXML with Oracle Access Manager 6.5 and higher versions.

For documentation of the pre-6.5 IdentityXML version tag, see the following:

http://www.oracle.com/technology/

2.6.1 Functions to Test for Attribute Permissions

The following functions provide a yes or no response as to whether you or another user has read, write, delegate, and notify permissions set for a particular attribute.

2.6.1.1 Can I view a user's profile

Function name canIViewUserProfile
Request example: <oblix:request application="userservcenter" function="canIViewUserProfile" version="NPWSDL1.0">
Description: Verifies that you can view a user's profile.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ um_CanIViewUserProfile.wsdl
Parameters  
uid The DN of the user whose profile you want to view.

Rules: Required. Single value, a DN.


2.6.1.2 Can I view an attribute in a user's profile

Function name canIViewUserProfileAttr
Request example: <oblix:request application="userservcenter" function="canIViewUserProfileAttr" version="NPWSDL1.0">
Description: Verifies that you can view a particular attribute in a user's profile.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ um_CanIViewUserProfileAttr.wsdl
Parameters  
uid The DN of the user whose attribute you want to view.

Rules: Required. Single value, a DN.

targetAttribute The schema name (not the display name) for the desired attribute.

Rules: Required. Single value, a string


2.6.1.3 Can I modify an attribute in a user's profile

Function name canIModifyUserProfileAttr
Request example: <oblix:request application="userservcenter" function="canIModifyUserProfileAttr" version="NPWSDL1.0">
Description: Verifies that you can change a particular attribute in a user's profile.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ um_canIModifyUserProfileAttr.wsdl
Parameters  
uid The DN of the user whose attribute you want to change.

Rules: Required. Single value, a DN.

targetAttribute The schema name (not the display name) for the desired attribute.

Rules: Required. Single value, a string.


2.6.1.4 Can I modify an attribute in a user's profile using a workflow

Function name canIRequestUserAttrModification
Request example: <oblix:request application="userservcenter" function="canIRequestUserAttrModification" version="NPWSDL1.0">
Description: Verifies that you can change a particular attribute in a user's profile, using a workflow.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ um_CanIRequestUserAttrModification.wsdl
Parameters  
uid The DN of the user whose attribute you want to change.

Rules: Required. Single value, a DN.

targetAttribute The schema name (not the display name) for the desired attribute.

Rules: Required. Single value, a string.


2.6.1.5 Can I create a new user

Function name canICreateUser
Request example: <oblix:request application="userservcenter" function="canICreateUser" version="NPWSDL1.0">
Description: Verifies that you can create a new user.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ um_CanICreateUser.wsdl
Parameters  
ObDomainName A subtree within which a test is being requested.

Rules: Optional. Single value, a DN.

Default: if no value is provided, the Identity System checks to see if you have the tested rights in any domain.


2.6.1.6 Can I delete an existing user

Function name canIDeleteUser
Request example: <oblix:request application="userservcenter" function="canIDeleteUser" version="NPWSDL1.0">
Description: Verifies that you can delete an existing user.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ um_CanIDeleteUser.wsdl
Parameters  
uid The DN of an entry you want to modify.

Rules: Required. Single value, a DN.


2.6.1.7 Can this user view another user's profile

Function name canIUserViewUserProfile
Request example: <oblix:request application="userservcenter" function="canUserViewUserProfile" version="NPWSDL1.0">
Description: Verifies that a non-logged in user can view another user's profile.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ um_CanUserViewUserProfile.wsdl
Parameters
uid The DN of the user whose profile is to be viewed.

Rules: Required. Single value, a DN.

proxysourceuid The DN of a non-logged-in user (proxy user) whose access rights are being tested.

Rules: Required. Single value, a DN.


2.6.1.8 Can this user view an attribute in another user's profile

Function name canUserViewUserProfileAttr
Request example: <oblix:request application="userservcenter" function="canUserViewUserProfileAttr" version="NPWSDL1.0">
Description: Verifies that a non-logged in user can view a particular attribute in another user's profile.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ um_CanUserViewUserProfileAttr.wsdl
Parameters  
uid The DN for the user whose profile is to be viewed.

Rules: Required. Single value, a DN.

proxysourceuid The DN for a non-logged-in user (proxy user) whose access rights are being tested.

Rules: Required. Single value, a DN.

targetAttribute The schema name (not the display name) for the desired attribute.

Rules: Required. Single value, a string.


2.6.1.9 Can this user modify an attribute in another user's profile using a workflow

Function name canUserRequestUserAttrModification
Request example: <oblix:request application="userservcenter" function="canUserRequestUserAttrModification" version="NPWSDL1.0">
Description: Verifies that a user can request a change of an attribute.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ um_CanUserRequestUserAttrModification.wsdl
Parameters  
uid The DN of an entry you want to modify.

Rules: Required. Single value, a DN.

proxysourceuid The DN for a non-logged-in user (proxy user) whose access rights are being tested.

Rules: Required. Single value, a DN.

targetattribute The schema name (not the display name) for the desired attribute.

Rules: Required. Single value, a string.


2.6.1.10 Can this user create a new user

Function name canUserCreateUser
Request example: <oblix:request application="userservcenter" function="canUserCreateUser" version="NPWSDL1.0">
Description: Verifies that a non-logged in user can create a new user.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ um_CanUserCreateUser.wsdl
Parameters  
proxysourceuid The DN for a non-logged-in user (proxy user) whose access rights are being tested.

Rules: Required. Single value, a DN.

ObDomainName A subtree within which a test is being requested.

Rules: Optional. Single value, a DN.

Default: if no value is provided, the Identity System checks to see if you have the tested rights in any domain.


2.6.1.11 Can this user delete an existing user

Function name canUserDeleteUser
Request example: <oblix:request application="userservcenter" function="canUserDeleteUser" version="NPWSDL1.0">
Description: Verifies that a non-logged in user can delete an existing user.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ um_CanUserDeleteUser.wsdl
Parameters  
proxysourceuid The DN for a non-logged-in user (proxy user) whose access rights are being tested.

Though it is outside the intent of functions using this parameter, DNs other than those of users can be used.

Rules: Required. Single value, a DN.

uid The DN of an entry you want to modify.

Rules: Required. Single value, a DN.


2.6.1.12 Can this user modify another user's attribute

Function name canUserModifyUserProfileAttr
Request example: <oblix:request application="userservcenter" function="canUserModifyUserProfileAttr" version="NPWSDL1.0">
Description: Verifies that a non-logged in user can change a particular attribute in another user's profile.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ um_CanUserModifyUserProfileAttr.wsdl
Parameters  
uid The DN of the user whose attribute you want to modify.

Rules: Required. Single value, a DN.

proxysourceuid The DN for a non-logged-in user (proxy user) whose access rights are being tested.

Rules: Required. Single value, a DN.

targetAttribute The schema name (not the display name) for the desired attribute.

Rules: Required. Single value, a string.


2.6.1.13 Can this user request a change to another user's profile using a workflow

Function name canUserRequestUserAttrModification
Request example: <oblix:request application="userservcenter" function="canUserRequestUserAttrModification" version="NPWSDL1.0">
Description: Verifies that a non-logged in user can request a change to a particular attribute in another user's profile, using a workflow.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ um_CanUserRequestUserAttrModification.wsdl
Parameters  
uid The DN of the user whose attribute you want to change.

Rules: Required. Single value, a DN.

proxysourceuid The DN for a non-logged-in user (proxy user) whose access rights are being tested.

Though it is outside the intent of functions using this parameter, DNs other than those of users can be used.

Rules: Required. Single value, a DN.

targetAttribute The schema name (not the display name) for the desired attribute.

Rules: Required. Single value, a string.


2.6.2 Functions to Perform User Manager Actions

These functions enable you or another user to perform a particular Identity System action, such as creating a user. These are get and set functions.

2.6.2.1 View User Attributes

Function name view
Request example: <oblix:request application="userservcenter" function="view" version="NPWSDL1.0">
Description Use this function to view attributes.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ um_view.wsdl
Parameters  
uid The DN of the user, in the case of the User Manager. If no uid is specified, the profile of the logged-in user is shown.

Rules: Optional for the User Manager only. Single value, a DN.

Notes: This parameter also applies to the DN of the group or organization whose attributes are to be viewed, depending upon if this function is being used in the Group Manager or Organization Manager.

attrName Optional. See "Attribute Parameters" for details.

If no attrNames are specified, then all of the attributes of the entry that the logged-in user has access to view are returned. Those attributes must be configured in the Identity System and added to a panel in the User, Group, or Organization Manager.


Note:

This function shows deactivated users if the requester is a Master Administrator, or if the administrator has the delegated administration rights of Grant and Workflow Monitoring.

Example 2-7 illustrates the view function.

Example 2-7 View Example

<SOAP-ENV:Envelope xmlns:oblix=http://www.oblix.com" xmlns:SOAP-ENV="http://schemas-xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
   <oblix:authentication xmlns:oblix="http://www.oblix.com" type="basic"?
      <oblix:login>admin</oblix:login>
      <oblix:password>oblix></oblix:password>
   </oblix:authentication>
   <oblix:request application="userservcenter" function="view" version="NPWSDL1.0">
      <oblix:params>
         <oblix:uid>
            cn=test1,o=Company,c=US
         </oblix:uid>
         <oblix:attrName>
            genuserid
         </oblix:attrname>
         <oblix:attrName>
            mail
         </oblix:attrName>
      </oblix:params>
   </oblix:request>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

2.6.2.2 Modify User Attributes

IdentityXML requests for gathering the attribute list pertaining to modifying a profile (modifyUser, modifyGroup, and modifyObject), no longer depend on a panel in the Identity System. For these functions, the attribute parameter must be configured in the Identity System. However, the attribute parameter need not be included in a panel configured for a user, group, or object profile. The GUI-based request for gathering the attribute list pertaining to modifying a profile continues to require the attributes listed on a panel.

Note:

With IdentityXML, an attribute listed in the negativeListForEntityAttributes list in the globalparams.xml file can only be read and cached. For details, see the topic on tuning the internal DBAgent cache in the Oracle Access Manager Deployment Guide.
Function name modifyUser
Request example: <oblix:request application="userservcenter" function="modifyUser" version="NPWSDL1.0">
Description: Change the attribute values for a specified user.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ um_modifyUser.wsdl
Parameters  
uid The DN of the user whose attributes are to be changed.

Rules: Required. Single value, a DN.

attrName Optional. See "Attribute Parameters" for details.

Use without the _n, to return data for only the named attributes. While optional for this function, Oracle recommends to always provide this parameter. The trade-off is that if you omit it, you get back data for all the names that appear in the panel. Use this parameter to limit output to just the data you want to see. You use this parameter in addition to the attrName_n parameter.

attrOperation_n Required. See "Attribute Parameters" for details.
attrOperation Required. See "Attribute Parameters" for details.
attrNewValue Required. See "Attribute Parameters" for details.
NoOfFields Required. See "Attribute Parameters" for details.
attrOldValue Optional/Required. Required only if the attrOperation is a REPLACE. See "Attribute Parameters" for details.

Example 2-8 illustrates a modify operation.

Example 2-8 Modify User Operation That Adds Challenge Phrases and Responses

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:oblix="http://www.oblix.com" xmlns:soapenv="http://schemas-xmlsoap.org/soap/envelope/">

<soapenv:Body>
  <oblix:authentication>
   <oblix:login>admin</oblix:login>
   <oblix:password>oblix</oblix:password>
  </oblix:authentication>

  <oblix:request application="userservcenter" function="modifyUser" version="NPWSDL1.0">
   <oblix:params>
    <oblix:uid>cn=user1,ou=Policy2,o=company,c=us</oblix:uid>
    <oblix:noOfFields>2</oblix:noOfFields>
           <oblix:AttributeParams>
           <oblix:ChallengeAttribute>
           <oblix:AttrName>genChallengePhrase</oblix:AttrName>
           <oblix:AttrOperation>ADD</oblix:AttrOperation>
                 <oblix:ChallengeValue>
                       <oblix:AttrNewValue>phrase1</oblix:AttrNewValue>
                 </oblix:ChallengeValue>
                 <oblix:ChallengeValue>
                       <oblix:AttrNewValue>phrase2</oblix:AttrNewValue>
                 </oblix:ChallengeValue>
                 <oblix:ChallengeValue>
                       <oblix:AttrNewValue>phrase3</oblix:AttrNewValue>
                 </oblix:ChallengeValue>
          </oblix:ChallengeAttribute>

          <oblix:ResponseAttribute>
          <oblix:AttrName>genChallengePhraseResponse</oblix:AttrName>
          <oblix:AttrOperation>ADD</oblix:AttrOperation>
                <oblix:ResponseValue>
                      <oblix:AttrNewValue>response1</oblix:AttrNewValue>
                      <oblix:AttrConfirmValue>response1</oblix:AttrConfirmValue>
                </oblix:ResponseValue>
                <oblix:ResponseValue>
                      <oblix:AttrNewValue>response2</oblix:AttrNewValue>
                      <oblix:AttrConfirmValue>response2</oblix:AttrConfirmValue>
                </oblix:ResponseValue>
                <oblix:ResponseValue>
                      <oblix:AttrNewValue>response3</oblix:AttrNewValue>
                      <oblix:AttrConfirmValue>response3</oblix:AttrConfirmValue>
                </oblix:ResponseValue>
         </oblix:ResponseAttribute>

    </oblix:AttributeParams>
   </oblix:params>
  </oblix:request>
 </soapenv:Body>
</soapenv:Envelope>

Example 2-9 illustrates a modify user operation that deletes challenges phrases and responses.

Example 2-9 Modify User Operation That Deletes Challenge Phrases and Responses

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:oblix="http://www.oblix.com" xmlns:soapenv="http://schemas-xmlsoap.org/soap/envelope/">

<soapenv:Body>
<oblix:authentication>
  <oblix:login>admin</oblix:login>
  <oblix:password>oblix</oblix:password>
</oblix:authentication>

<oblix:request application="userservcenter" function="modifyUser" version="NPWSDL1.0">
    <oblix:params>
    <oblix:uid>cn=user1,ou=Policy2,o=company,c=us</oblix:uid>
    <oblix:noOfFields>2</oblix:noOfFields>
    <oblix:AttributeParams>

          <oblix:ChallengeAttribute>
          <oblix:AttrName>genChallengePhrase</oblix:AttrName>
          <oblix:AttrOperation>DELETE</oblix:AttrOperation>
                <oblix:ChallengeValue>
                      <oblix:AttrNewValue>phrase1</oblix:AttrNewValue>
                </oblix:ChallengeValue>
          </oblix:ChallengeAttribute>

          <oblix:ResponseAttribute>
                <oblix:AttrName>genChallengePhraseResponse</oblix:AttrName>
                      <oblix:AttrOperation>DELETE</oblix:AttrOperation>
          </oblix:ResponseAttribute>

    </oblix:AttributeParams>
   </oblix:params>
  </oblix:request>
 </soapenv:Body>
</soapenv:Envelope>

Example 2-10 illustrates replacing challenge phrases and responses.

Example 2-10 Modify User Operation That Replaces Challenges and Responses

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:oblix="http://www.oblix.com" xmlns:soapenv="http://schemas-xmlsoap.org/soap/envelope/">

<soapenv:Body>
<oblix:authentication>
   <oblix:login>admin</oblix:login>
   <oblix:password>oblix</oblix:password>
</oblix:authentication>
<oblix:request application="userservcenter" function="modifyUser" version="NPWSDL1.0">

   <oblix:params>
    <oblix:uid>cn=user1,ou=Policy2,o=company,c=us</oblix:uid>
    <oblix:noOfFields>2</oblix:noOfFields>
    <oblix:AttributeParams>

     <oblix:ChallengeAttribute>
     <oblix:AttrName>genChallengePhrase</oblix:AttrName>
     <oblix:AttrOperation>REPLACE</oblix:AttrOperation>
           <oblix:ChallengeValue>
                 <oblix:AttrOldValue>phrase2</oblix:AttrOldValue>
                 <oblix:AttrNewValue>phrase2_new</oblix:AttrNewValue>
           </oblix:ChallengeValue>
           <oblix:ChallengeValue>
                 <oblix:AttrOldValue>phrase3</oblix:AttrOldValue>
                 <oblix:AttrNewValue>phrase3_new</oblix:AttrNewValue>
           </oblix:ChallengeValue>
     </oblix:ChallengeAttribute>

     <oblix:ResponseAttribute>
     <oblix:AttrName>genChallengePhraseResponse</oblix:AttrName>
     <oblix:AttrOperation>REPLACE</oblix:AttrOperation>
           <oblix:ResponseValue>
                 <oblix:AttrOldValue>response2</oblix:AttrOldValue>
                 <oblix:AttrNewValue>response2_new</oblix:AttrNewValue>
                 <oblix:AttrConfirmValue>response2_new</oblix:AttrConfirmValue>
           </oblix:ResponseValue>
           <oblix:ResponseValue>
                 <oblix:AttrOldValue>response3</oblix:AttrOldValue>
                 <oblix:AttrNewValue>response3_new</oblix:AttrNewValue>
                 <oblix:AttrConfirmValue>response3_new</oblix:AttrConfirmValue>
           </oblix:ResponseValue>
     </oblix:ResponseAttribute>

    </oblix:AttributeParams>
   </oblix:params>
  </oblix:request>
 </soapenv:Body>
</soapenv:Envelope>

Example 2-11 illustrates replacing all challenges and responses.

Example 2-11 Modify User Operation With a Replace_All for Challenges and Responses

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:oblix="http://www.oblix.com" xmlns:soapenv="http://schemas-xmlsoap.org/soap/envelope/">

<soapenv:Body>
<oblix:authentication>
   <oblix:login>admin</oblix:login>
   <oblix:password>oblix</oblix:password>
</oblix:authentication>
<oblix:request application="userservcenter" function="modifyUser" version="NPWSDL1.0">
   <oblix:params>
    <oblix:uid>cn=user1,ou=Policy2,o=company,c=us</oblix:uid>
    <oblix:noOfFields>2</oblix:noOfFields>
    <oblix:AttributeParams>

     <oblix:ChallengeAttribute>
     <oblix:AttrName>genChallengePhrase</oblix:AttrName>
      <oblix:AttrOperation>REPLACE_ALL</oblix:AttrOperation>
            <oblix:ChallengeValue>
                  <oblix:AttrNewValue>phrase1_new</oblix:AttrNewValue>
            </oblix:ChallengeValue>
            <oblix:ChallengeValue>
                  <oblix:AttrNewValue>phrase2_new</oblix:AttrNewValue>
            </oblix:ChallengeValue>
            <oblix:ChallengeValue>
                  <oblix:AttrNewValue>phrase3_new</oblix:AttrNewValue>
            </oblix:ChallengeValue>
      </oblix:ChallengeAttribute>

      <oblix:ResponseAttribute>
      <oblix:AttrName>genChallengePhraseResponse</oblix:AttrName>
      <oblix:AttrOperation>REPLACE_ALL</oblix:AttrOperation>
            <oblix:ResponseValue>
                  <oblix:AttrNewValue>response1_new</oblix:AttrNewValue>
                  <oblix:AttrConfirmValue>response1_new</oblix:AttrConfirmValue>
            </oblix:ResponseValue>
            <oblix:ResponseValue>
                  <oblix:AttrNewValue>response2_new</oblix:AttrNewValue>
                  <oblix:AttrConfirmValue>response2_new</oblix:AttrConfirmValue>
            </oblix:ResponseValue>
            <oblix:ResponseValue>
                  <oblix:AttrNewValue>response3_new</oblix:AttrNewValue>
                  <oblix:AttrConfirmValue>response3_new</oblix:AttrConfirmValue>
            </oblix:ResponseValue>
      </oblix:ResponseAttribute>

    </oblix:AttributeParams>
   </oblix:params>
  </oblix:request>
 </soapenv:Body>
</soapenv:Envelope>

2.6.2.3 Request User Attribute Change Through a Workflow

Function name workflowSaveChangeAttributeRequest
Request example: <oblix:request application="userservcenter" function="workflowSaveChangeAttributeRequest" version="NPWSDL1.0">
Description: Use this function to request a group, organization, or user attribute change using a workflow. The parameters starting with OBAuxClasses apply only to groups.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ um_workflowSaveChangeAttributeRequest.wsdl
Parameters  
uid The DN of the user, group or organization whose attribute is to be changed.

Rules: Required. Single value, a DN.

attrName Required. Required here means attributes that are specific to each workflow. If an attribute supplied here is not required by the workflow, it is ignored, and no error is generated. See "Attribute Parameters" for details.
attrOperation Required. See "Attribute Parameters" for details.
attrNewValue Required. See "Attribute Parameters" for details.
changeRequestAttr Use this parameter to name the attribute whose value you want to change. This is the LDAP schema name of the attribute, not the display name.

Rules: Required. Single-valued, a string.

changeRequestType Specifies whether this request is a provisioning or deprovisioning request.

Rules: Required. Single value. It can be one of two values: remove (for deprovisioning) newval (for provisioning).

NoOfFields Required. See "Attribute Parameters" for details.
ObWorkflowName The name of the workflow that you want to use to create or change the value(s) for an attribute.

Find the full DN for ObWorkflowName under the view menu for workflow definition under the particular application.

Rules: Required. Single value, a DN.

attrOldValue Optional/Required. Required only if the attrOperation is a REPLACE. See "Attribute Parameters" for details.
ObAuxClassesOldValues The old values of the auxiliary class names that you want to replace. This is used only to change the name information for auxiliary classes associated with groups. Use this parameter once for each auxiliary class name to be removed.

If you attempt to specify a value for which you do not have access, you get an error message "Invalid value for attributeObAuxClasses."

You find the values for these using the Identity System Console, Group Manager Configuration, Group Types, Configure Group Type Panels. Select the group, and find the Associated ObjectClass name displayed.

Rules: Required only if the attribute is for an auxiliary class and the ObAuxClassesOperation is a REPLACE, otherwise ignored. Multivalued.

ObAuxClassesOperation The type of operation to perform on the attribute. This is used only to change the name information for auxiliary classes.

Legal values are:

ADD: Add the auxiliary class name to the existing attributes.

DELETE: Delete the auxiliary class name from the existing attributes.

REPLACE: Delete the old auxiliary class name and replace it with the new auxiliary class name.

If you specify any other value or no value, you get an error message "Invalid value for attribute ObAuxClasses."

Rules: Required only if the attribute is for an auxiliary class. Single value.

ObAuxClassesValues The name of the auxiliary class that you want to add, delete, or replace. This is used only to change the name information for auxiliary classes.

Use this parameter once for each auxiliary class name to be added or removed.If you attempt to specify a value for which you do not have access, you get an error message "Invalid value for attributeObAuxClasses".

To find the values for these, use the Identity System Console, Group Manager Configuration, Group Types, Configure Group Type Panels. Select the group, and find the Associated ObjectClass name.

Rules: Required if the attribute is for an auxiliary class. Multivalued. Valid values are the string names of the configured auxiliary classes available. (Auxiliary classes are configured through the System Console, Configure Object Class function, see the Oracle Access Manager Identity and Common Administration Guide.)

ObWfComment Use this parameter to provide a comment for a step in a workflow.

Rules: Optional. Single value, string.


Example 2-12 illustrates adding a challenge and response using a workflow.

Example 2-12 Change Attribute Workflow that Adds a Challenge Phrase and Response

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:oblix="http://www.oblix.com" xmlns:soapenv="http://schemas-xmlsoap.org/soap/envelope/">

<soapenv:Body>
<oblix:authentication>
   <oblix:login>admin</oblix:login>
   <oblix:password>oblix</oblix:password>
</oblix:authentication>

<oblix:request application="userservcenter" function="workflowSaveChangeAttributeRequest" version="NPWSDL1.0">
<oblix:params>
<oblix:uid>cn=user1,ou=Policy2,o=company,c=us</oblix:uid> <oblix:ObWorkflowName>obworkflowid=94400828cd0b4cb494e04a8eab0a142f,obcontainerId=workflowDefinitions,o=Oblix,o=company,c=us</oblix:ObWorkflowName>
    <oblix:changeRequestAttr>genChallengePhrase</oblix:changeRequestAttr>
    <oblix:changeRequestType>newval</oblix:changeRequestType>
    <oblix:noOfFields>2</oblix:noOfFields>
    <oblix:AttributeParams>

     <oblix:ChallengeAttribute>
     <oblix:AttrName>genChallengePhrase</oblix:AttrName>
     <oblix:AttrOperation>ADD</oblix:AttrOperation>
           <oblix:ChallengeValue>
                 <oblix:AttrNewValue>phrase1</oblix:AttrNewValue>
           </oblix:ChallengeValue>
           <oblix:ChallengeValue>
                 <oblix:AttrNewValue>phrase2</oblix:AttrNewValue>
           </oblix:ChallengeValue>
           <oblix:ChallengeValue>
                 <oblix:AttrNewValue>phrase3</oblix:AttrNewValue>
           </oblix:ChallengeValue>
     </oblix:ChallengeAttribute>

     <oblix:ResponseAttribute>
     <oblix:AttrName>genChallengePhraseResponse</oblix:AttrName>
     <oblix:AttrOperation>ADD</oblix:AttrOperation>
           <oblix:ResponseValue>
                 <oblix:AttrNewValue>response1</oblix:AttrNewValue>
                 <oblix:AttrConfirmValue>response1</oblix:AttrConfirmValue>
           </oblix:ResponseValue>
           <oblix:ResponseValue>
                 <oblix:AttrNewValue>response2</oblix:AttrNewValue>
                 <oblix:AttrConfirmValue>response2</oblix:AttrConfirmValue>
           </oblix:ResponseValue>
           <oblix:ResponseValue>
                 <oblix:AttrNewValue>response3</oblix:AttrNewValue>
                 <oblix:AttrConfirmValue>response3</oblix:AttrConfirmValue>
           </oblix:ResponseValue>
     </oblix:ResponseAttribute>

    </oblix:AttributeParams>
   </oblix:params>
  </oblix:request>
 </soapenv:Body>
</soapenv:Envelope>

Example 2-13 illustrates replacing a challenge phrase and response using a workflow.

Example 2-13 Workflow that Replaces Challenge Phrases and Responses

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:oblix="http://www.oblix.com" xmlns:soapenv="http://schemas-xmlsoap.org/soap/envelope/">

<soapenv:Body>
<oblix:authentication>
   <oblix:login>admin</oblix:login>
   <oblix:password>oblix</oblix:password>
</oblix:authentication>
<oblix:request application="userservcenter" function="workflowSaveChangeAttributeRequest" version="NPWSDL1.0">
<oblix:params>
<oblix:uid>cn=user1,ou=Policy2,o=company,c=us</oblix:uid>
   <oblix:ObWorkflowName>obworkflowid=94400828cd0b4cb494e04a8eab0a142f,obcontainerId=workflowDefinitions,o=Oblix,o=company,c=us</oblix:ObWorkflowName>
<oblix:changeRequestAttr>genChallengePhrase</oblix:changeRequestAttr>
<oblix:changeRequestType>newval</oblix:changeRequestType>
<oblix:noOfFields>2</oblix:noOfFields>

    <oblix:AttributeParams>
    <oblix:ChallengeAttribute>
    <oblix:AttrName>genChallengePhrase</oblix:AttrName>
    <oblix:AttrOperation>REPLACE</oblix:AttrOperation>
          <oblix:ChallengeValue>
                <oblix:AttrOldValue>phrase2</oblix:AttrOldValue>
                        <oblix:AttrNewValue>phrase2_new</oblix:AttrNewValue>
          </oblix:ChallengeValue>
          <oblix:ChallengeValue>
                        <oblix:AttrOldValue>phrase3</oblix:AttrOldValue>
                        <oblix:AttrNewValue>phrase3_new</oblix:AttrNewValue>
            </oblix:ChallengeValue>
     </oblix:ChallengeAttribute>

     <oblix:ResponseAttribute>
     <oblix:AttrName>genChallengePhraseResponse</oblix:AttrName>
     <oblix:AttrOperation>REPLACE</oblix:AttrOperation>
           <oblix:ResponseValue>
                         <oblix:AttrOldValue>response2</oblix:AttrOldValue>
                         <oblix:AttrNewValue>response2_new</oblix:AttrNewValue>
                         <oblix:AttrConfirmValue>response2_new</oblix:AttrConfirmValue>
           </oblix:ResponseValue>
           <oblix:ResponseValue>
                         <oblix:AttrOldValue>response3</oblix:AttrOldValue>
                         <oblix:AttrNewValue>response3_new</oblix:AttrNewValue>
                         <oblix:AttrConfirmValue>response3_new</oblix:AttrConfirmValue>
           </oblix:ResponseValue>
      </oblix:ResponseAttribute>

    </oblix:AttributeParams>
   </oblix:params>
  </oblix:request>
 </soapenv:Body>
</soapenv:Envelope>

Example 2-14 illustrates replacing all challenge phrases and responses using a workflow.

Example 2-14 Workflow That Replaces All Challenge Phrases and Responses

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:oblix="http://www.oblix.com" xmlns:soapenv="http://schemas-xmlsoap.org/soap/envelope/">

<soapenv:Body>
<oblix:authentication>
   <oblix:login>admin</oblix:login>
   <oblix:password>oblix</oblix:password>
</oblix:authentication>
<oblix:request application="userservcenter" function="workflowSaveChangeAttributeRequest" version="NPWSDL1.0">
<oblix:params>
<oblix:uid>cn=user1,ou=Policy2,o=company,c=us</oblix:uid> <oblix:ObWorkflowName>obworkflowid=94400828cd0b4cb494e04a8eab0a142f,obcontainerId=workflowDefinitions,o=Oblix,o=company,c=us</oblix:ObWorkflowName>

    <oblix:changeRequestAttr>genChallengePhrase</oblix:changeRequestAttr>
    <oblix:changeRequestType>newval</oblix:changeRequestType>
    <oblix:noOfFields>2</oblix:noOfFields>
    <oblix:AttributeParams>

          <oblix:ChallengeAttribute>
          <oblix:AttrName>genChallengePhrase</oblix:AttrName>
          <oblix:AttrOperation>REPLACE_ALL</oblix:AttrOperation>
                <oblix:ChallengeValue>
                      <oblix:AttrNewValue>phrase1_new</oblix:AttrNewValue>
                </oblix:ChallengeValue>
                <oblix:ChallengeValue>
                      <oblix:AttrNewValue>phrase2_new</oblix:AttrNewValue>
                </oblix:ChallengeValue>
                <oblix:ChallengeValue>
                      <oblix:AttrNewValue>phrase3_new</oblix:AttrNewValue>
              </oblix:ChallengeValue>
       </oblix:ChallengeAttribute>

       <oblix:ResponseAttribute>
       <oblix:AttrName>genChallengePhraseResponse</oblix:AttrName>
       <oblix:AttrOperation>REPLACE_ALL</oblix:AttrOperation>
             <oblix:ResponseValue>
                  <oblix:AttrNewValue>response1_new</oblix:AttrNewValue>
                  <oblix:AttrConfirmValue>response1_new</oblix:AttrConfirmValue>
             </oblix:ResponseValue>
             <oblix:ResponseValue>
                   <oblix:AttrNewValue>response2_new</oblix:AttrNewValue>
                   <oblix:AttrConfirmValue>response2_new</oblix:AttrConfirmValue>
             </oblix:ResponseValue>
             <oblix:ResponseValue>
                   <oblix:AttrNewValue>response3_new</oblix:AttrNewValue>
                   <oblix:AttrConfirmValue>response3_new</oblix:AttrConfirmValue>
             </oblix:ResponseValue>
      </oblix:ResponseAttribute>

    </oblix:AttributeParams>
   </oblix:params>
  </oblix:request>
 </soapenv:Body>
</soapenv:Envelope>

2.6.2.4 Create User Using a Workflow

Function name workflowSaveCreateProfile
Request example: <oblix:request application="userservcenter" function="workflowSaveCreateProfile" version="NPWSDL1.0">
Description: Use this function to create a new user, group, or organization using a workflow.The parameters starting with OBAuxClasses apply only to groups.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ um_workflowSaveCreateProfile.wsdl
Parameters  
ObDomainName The name of the domain where you want to create a new entry.

Rules: Required. Single value, a DN. The domain name must be defined under the workflow referred to by the ObWorkflowName parameter.

ObWorkflowName The name of the workflow that you want to use to create or change the value(s) for an attribute.

Find the full DN for ObWorkflowName under the view menu for workflow definition under the particular application.

Rules: Required. Single value, a DN.

NoOfFields Required. See "Attribute Parameters" for details.
attrName Required. Required here means attributes that are specific to each workflow. If an attribute supplied here is not required by the workflow, it is ignored, and no error is generated. See "Attribute Parameters" for details.
attrOperation Required. See "Attribute Parameters" for details.
attrNewValue Required. See "Attribute Parameters" for details.
attrOldValue Optional/Required. Required only if the attrOperation is a REPLACE.
ObAuxClassesOldValues The old values of the auxiliary class names that you want to replace. This is used only to change the name information for auxiliary classes associated with groups. Use this parameter once for each auxiliary class name to be removed.

If you attempt to specify a value for which you do not have access, you get an error message "Invalid value for attributeObAuxClasses."

You find the values for these using the Identity System Console, Group Manager Configuration, Group Types, Configure Group Type Panels. Select the group, and find the Associated ObjectClass name displayed.

Rules: Required only if the attribute is for an auxiliary class and the ObAuxClassesOperation is a REPLACE, otherwise ignored. Multivalued.

ObAuxClassesOperation The type of operation to perform on the attribute. This is used only to change the name information for auxiliary classes.

Legal values are:

ADD: Add the auxiliary class name to the existing attributes.

DELETE: Delete the auxiliary class name from the existing attributes.

REPLACE: Delete the old auxiliary class name and replace it with the new auxiliary class name.

If you specify any other value or no value, you get an error message "Invalid value for attribute ObAuxClasses."

Rules: Required if the attribute is for an auxiliary class. Single value.

ObAuxClassesValues The name of the auxiliary class to add, delete, or replace. This is used only to change the name information for auxiliary classes.

Use this parameter once for each auxiliary class name to be added or removed.If you attempt to specify a value for which you do not have access, you get an error message "Invalid value for attributeObAuxClasses."

To find the values, use the Identity System Console, Group Manager Configuration, Group Types, Configure Group Type Panels. Select the group, and find the Associated ObjectClass name.

Rules: Required if the attribute is for an auxiliary class. Multivalued. Valid values are the string names of the configured auxiliary classes available. Auxiliary classes are configured through the Administration Console's configure object classes function. See the Oracle Access Manager Identity and Common Administration Guide for details.

ObWfComment Provides a comment for a step in a workflow.

Rules: Optional. Single value, string.


Example 2-15 illustrates adding challenges and responses using a workflow.

Example 2-15 Create User Workflow That Adds Challenge Phrases and Responses

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:oblix="http://www.oblix.com" xmlns:soapenv="http://schemas-xmlsoap.org/soap/envelope/">
<soapenv:Body>
<oblix:authentication>
   <oblix:login>admin</oblix:login>
   <oblix:password>oblix</oblix:password>
</oblix:authentication>
<oblix:request application="userservcenter" function="workflowSaveCreateProfile" version="NPWSDL1.0">
   <oblix:params>
    <oblix:ObWorkflowName>obworkflowid=5c9ad30117f44a3e960dad321a84b139,obcontainerId=workflowDefinitions,o=Oblix,o=company,c=us</oblix:ObWorkflowName>
    <oblix:ObDomainName>ou=Policy2,o=company,c=us</oblix:ObDomainName>
    <oblix:noOfFields>6</oblix:noOfFields>

    <oblix:AttributeParams>
          <oblix:GenericAttribute>
          <oblix:AttrName>cn</oblix:AttrName>
          <oblix:AttrOperation>ADD</oblix:AttrOperation>
                <oblix:AttrNewValue>user101</oblix:AttrNewValue>
          </oblix:GenericAttribute>
          <oblix:GenericAttribute>
          <oblix:AttrName>sn</oblix:AttrName>
          <oblix:AttrOperation>ADD</oblix:AttrOperation>
                <oblix:AttrNewValue>user101L</oblix:AttrNewValue>
          </oblix:GenericAttribute>
          <oblix:GenericAttribute>
          <oblix:AttrName>uid</oblix:AttrName>
          <oblix:AttrOperation>ADD</oblix:AttrOperation>
                <oblix:AttrNewValue>user101</oblix:AttrNewValue>
          </oblix:GenericAttribute>

          <oblix:PasswordAttribute>
          <oblix:AttrName>userPassword</oblix:AttrName>
          <oblix:AttrOperation>ADD</oblix:AttrOperation>
                <oblix:AttrNewValue>oblix</oblix:AttrNewValue>
                <oblix:AttrConfirmValue>oblix</oblix:AttrConfirmValue>
          </oblix:PasswordAttribute>

          <oblix:ChallengeAttribute>
          <oblix:AttrName>genChallengePhrase</oblix:AttrName>
          <oblix:AttrOperation>ADD</oblix:AttrOperation>
                <oblix:ChallengeValue>
                      <oblix:AttrNewValue>phrase1</oblix:AttrNewValue>
                </oblix:ChallengeValue>
                <oblix:ChallengeValue>
                      <oblix:AttrNewValue>phrase2</oblix:AttrNewValue>
                </oblix:ChallengeValue>
                <oblix:ChallengeValue>
                      <oblix:AttrNewValue>phrase3</oblix:AttrNewValue>
                </oblix:ChallengeValue>
          </oblix:ChallengeAttribute>

          <oblix:ResponseAttribute>
          <oblix:AttrName>genChallengePhraseResponse</oblix:AttrName>
          <oblix:AttrOperation>ADD</oblix:AttrOperation>
                <oblix:ResponseValue>
                      <oblix:AttrNewValue>response1</oblix:AttrNewValue>
                      <oblix:AttrConfirmValue>response1</oblix:AttrConfirmValue>
                 </oblix:ResponseValue>
                 <oblix:ResponseValue>
                       <oblix:AttrNewValue>response2</oblix:AttrNewValue>
                       <oblix:AttrConfirmValue>response2</oblix:AttrConfirmValue>
                 </oblix:ResponseValue>
                 <oblix:ResponseValue>
                       <oblix:AttrNewValue>response3</oblix:AttrNewValue>
                       <oblix:AttrConfirmValue>response3</oblix:AttrConfirmValue>
                 </oblix:ResponseValue>
          </oblix:ResponseAttribute>

    </oblix:AttributeParams>
   </oblix:params>
  </oblix:request>
 </soapenv:Body>
</soapenv:Envelope>

2.6.2.5 Self-Registration Using a Workflow

Function name workflowSelfRegistrationSave
Request example: <oblix:request application="userservcenter" function="workflowSelfRegistrationSave" version="NPWSDL1.0">
Description: Adds yourself to an organization or as a user.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ um_workflowSelfRegistrationSave.wsdl
Parameters  
ObDomainName The name of the domain in which you want to create a new entry. The domain name must be defined under the workflow referred to by the ObWorkflowName parameter.

Rules: Required. Single value, a DN.

ObWorkflowName The name of the workflow that you want to use to create or change the value(s) for an attribute.

Find the full DN for ObWorkflowName under the view menu for workflow definition under the particular application.

Rules: Required. Single value, a DN.

attrName Required. Required here means attributes that are specific to each workflow. If an attribute supplied here is not required by the workflow, it is ignored, and no error is generated. See "Attribute Parameters" for details.
attrOperation Required. See "Attribute Parameters" for details.
attrNewValue Required. See "Attribute Parameters" for details.
NoOfFields Required. See "Attribute Parameters" for details.
attrOldValue Optional/Required. Required only if the attrOperation is a REPLACE.
ObWfComment Provides a comment for a step in a workflow.

Rules: Optional. Single value, string.


Example 2-16 illustrates adding challenges and responses using a self-registration workflow.

Example 2-16 Self-Registration Workflow That Adds Challenge Phrases and Responses

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:oblix="http://www.oblix.com" xmlns:soapenv="http://schemas-xmlsoap.org/soap/envelope/">

<soapenv:Body>
<oblix:authentication>
   <oblix:login>admin</oblix:login>
   <oblix:password>oblix</oblix:password>
</oblix:authentication>
<oblix:request application="userservcenter" function="workflowSelfRegistrationSave" version="NPWSDL1.0">
   <oblix:params>
    <oblix:ObWorkflowName>obworkflowid=3a94939d048f42f0b039c3d978c10a2f,obcontainerId=workflowDefinitions,o=Oblix,o=company,c=us</oblix:ObWorkflowName>
<oblix:ObDomainName>ou=Policy2,o=company,c=us</oblix:ObDomainName>
<oblix:noOfFields>6</oblix:noOfFields>
<oblix:AttributeParams>

      <oblix:GenericAttribute>
      <oblix:AttrName>cn</oblix:AttrName>
      <oblix:AttrOperation>ADD</oblix:AttrOperation>
            <oblix:AttrNewValue>user102</oblix:AttrNewValue>
      </oblix:GenericAttribute>
      <oblix:GenericAttribute>
      <oblix:AttrName>sn</oblix:AttrName>
      <oblix:AttrOperation>ADD</oblix:AttrOperation>
            <oblix:AttrNewValue>user102L</oblix:AttrNewValue>
      </oblix:GenericAttribute>
      <oblix:GenericAttribute>
      <oblix:AttrName>uid</oblix:AttrName>
      <oblix:AttrOperation>ADD</oblix:AttrOperation>
            <oblix:AttrNewValue>user102</oblix:AttrNewValue>
     </oblix:GenericAttribute>

     <oblix:PasswordAttribute>
     <oblix:AttrName>userPassword</oblix:AttrName>
     <oblix:AttrOperation>ADD</oblix:AttrOperation>
           <oblix:AttrNewValue>oblix</oblix:AttrNewValue>
           <oblix:AttrConfirmValue>oblix</oblix:AttrConfirmValue>
     </oblix:PasswordAttribute>

     <oblix:ChallengeAttribute>
     <oblix:AttrName>genChallengePhrase</oblix:AttrName>
     <oblix:AttrOperation>ADD</oblix:AttrOperation>
           <oblix:ChallengeValue>
                 <oblix:AttrNewValue>phrase1</oblix:AttrNewValue>
           </oblix:ChallengeValue>
           <oblix:ChallengeValue>
           <oblix:AttrNewValue>phrase2</oblix:AttrNewValue>
           </oblix:ChallengeValue>
           <oblix:ChallengeValue>
                 <oblix:AttrNewValue>phrase3</oblix:AttrNewValue>
           </oblix:ChallengeValue>
     </oblix:ChallengeAttribute>

     <oblix:ResponseAttribute>
     <oblix:AttrName>genChallengePhraseResponse</oblix:AttrName>
     <oblix:AttrOperation>ADD</oblix:AttrOperation>
            <oblix:ResponseValue>
                  <oblix:AttrNewValue>response1</oblix:AttrNewValue>
                  <oblix:AttrConfirmValue>response1</oblix:AttrConfirmValue>
            </oblix:ResponseValue>
            <oblix:ResponseValue>
                  <oblix:AttrNewValue>response2</oblix:AttrNewValue>
                  <oblix:AttrConfirmValue>response2</oblix:AttrConfirmValue>
            </oblix:ResponseValue>
            <oblix:ResponseValue>
                  <oblix:AttrNewValue>response3</oblix:AttrNewValue>
                  <oblix:AttrConfirmValue>response3</oblix:AttrConfirmValue>
            </oblix:ResponseValue>
     </oblix:ResponseAttribute>

    </oblix:AttributeParams>
   </oblix:params>
  </oblix:request>
 </soapenv:Body>
</soapenv:Envelope>

2.6.2.6 Deactivate User Using a Workflow

Function name workflowDeactivateUserSave
Request example: <oblix:request application="userservcenter" function="workflowDeactivateUserSave" version="NPWSDL1.0">
Description: Deactivates a user using a workflow. Information for deactivated users is kept in the directory but not shown in search results.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ um_workflowDeactivateUserSave.wsdl
Parameters Note: If attributes in the workflow steps are configured as optional, only the following parameters are required: uid and ObWorkflowName. In this case, ObDomainName is not required.
uid The DN of the user to be deactivated.

Rules: Required. Single value, a DN.

ObDomainName The name of the domain in which you want to create a new entry. The domain name must be defined under the workflow referred to by the ObWorkflowName parameter.

Rules: Required. Single value, a DN.

ObWorkflowName The name of the workflow that you want to use to create or change the value(s) for an attribute.

Find the full DN for ObWorkflowName under the view menu for workflow definition under the particular application.

Rules: Required. Single value, a DN.

attrName Required. Here, required means attributes that are specific to each workflow. If an attribute supplied here is not required by the workflow, it is ignored, and no error is generated. See "Attribute Parameters" for details.
attrOperation Required. See "Attribute Parameters" for details.
attrNewValue Required. See "Attribute Parameters" for details.
NoOfFields Required. See "Attribute Parameters" for details.
attrOldValue Optional/Required. Required only if the attrOperation is a REPLACE.
ObWfComment Provides a comment for a step in a workflow.

Rules: Optional. Single value, string.


2.6.2.7 View Deactivated User

To be able to view a deactivated user, you need to be either the Master Administrator or have delegated administration rights for grant and workflow monitoring of the domain where the target user exists. That is, you should be able to monitor workflow requests in the target user domain. Then you can view a deactivated user in that domain using the view function. See "View User Attributes" for details.

2.6.2.8 Search Deactivated Users

Function name searchDeactivatedUsers
Request example: <oblix:request application="userservcenter" function="searchDeactivatedUsers" version="NPWSDL1.0">
Description: Search for deactivated users, based on certain criteria. Only one search condition is accepted. You can search for deactivated users based on one condition only.

To be able to search for deactivated users, you need to be either the Master Administrator or have delegated administration rights to GRANT+WORKFLOW MONITORING to the domain where the target users exist. That is, you should be able to monitor workflow requests in the target users' domain. Then you can search for deactivated users in that domain using the searchDeactivatedUsers function. One difference is that the result attributes are those specified in the search results table so you cannot specify the result attributes through attrName as you can do in a normal search.

Note: If you are a participant in a reactive workflow, you can also search for a deactivated user.

WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ um_searchDeactivatedUsers.wsdl
Parameters  
SearchAttr Required. See "Search Parameters" for details.
SearchOperation Required. See "Search Parameters" for details.
SearchString Required. See "Search Parameters" for details.
attrname Optional. If no value is given, the default table view attributes are used See "Attribute Parameters" for details.
noOfFields Optional. See "Attribute Parameters" for details.
noOfRecords Optional. A maximum number of entries to be returned in the search results.This, and its default value, is overridden by the showAllResults parameter.

Rules: Optional. Single value, an integer value >=1.

Default: A value obtained from the defaultDisplayResultVal parameter in the oblixbaseparams.xml catalog. Otherwise this value is obtained from the custom cookie.

showAllResults Returns all results of the search to the user. If the parameter value is true, it overrides the value of the noOfRecords parameter.

Rules: Optional. Single value, Boolean, valued true or false.

Default: False, meaning return results up to the limit imposed by the noOfRecords parameter.

sortBy What attribute to use to sort the results.

Rules: Optional. Single value.

Default: if no value is specified, the class attribute of the structural objectclass of the tab specified by tab_id is used.

sortOrder The sort order, ascending or descending. There are two possible values: ascending, descending.

Rules: Optional. Single value.

Default: ascending

startFrom Use this parameter for a long list of search results, to skip over a selected number of items and start the list with a specified item. For example, if 100 entries were found by the search, entering a value of 80 for this parameter gives a response showing only items 80 through 100.

Rules: Optional. Single value, integer.

Default: 1, meaning to start displaying from the beginning of the search results list.


2.6.2.9 Reactivate User Using a Workflow

Function name workflowReactivateUserSave
Request example: <oblix:request application="userservcenter" function="workflowReactivateUserSave" version="NPWSDL1.0">
Description: Reactivates a user using a workflow. Information for reactivated users is kept in the directory but not shown in search results.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ um_workflowReactivateUserSave.wsdl
Parameters  
uid The DN of the user to be reactivated.

Rules: Required. Single value, a DN.

ObDomainName The name of the domain in which you want to create a new entry. The domain name must be defined under the workflow referred to by the ObWorkflowName parameter.

Rules: Required. Single value, a DN.

ObWorkflowName The name of the workflow that you want to use to create or change the value(s) for an attribute.

Find the full DN for ObWorkflowName under the view menu for workflow definition under the particular application.

Rules: Required. Single value, a DN.

attrName Required. Here, required means attributes that are specific to each workflow. If an attribute supplied here is not required by the workflow, it is ignored, and no error is generated. See "Attribute Parameters" for details.
attrOperation Required. See "Attribute Parameters" for details.
attrNewValue Required. See "Attribute Parameters" for details.
NoOfFields Required. See "Attribute Parameters" for details.
attrOldValue Optional/Required. Required only if the attrOperation is a REPLACE.
ObWfComment Provides a comment for a step in a workflow.

Rules: Optional. Single value, string.


2.7 Group Manager Functions

If you are an administrator, the Group Manager enables you to create or delete groups, and enables users to subscribe or unsubscribe from groups. The Group Manager typically enables end users to view groups and to subscribe to membership in a group. The groups that a person can view and subscription rights are granted by a Master Administrator.

The following functions allow you to programmatically access the Group Manager application. Note that all functions follow a similar syntax:

<oblix:request application="groupservcenter" function="name" version="version">

For example:

<oblix:request application="groupservcenter" function="canIViewGroupProfile" version="NPWSDL1.0">

Note:

The version tag is required if you are using IdentityXML with Oracle Access Manager 6.5 and higher versions.

For documentation of the pre-6.5 IdentityXML version tag, see the following:

http://www.oracle.com/technology/

2.7.1 Functions to Test for Attribute Permissions

The following functions provide a yes or no response as to whether you or another user have read, write, delegate, and notify permissions set for a particular attribute.

2.7.1.1 Can I view a group's profile

Function name canIViewGroupProfile
Request example: <oblix:request application="groupservcenter" function="canIViewGroupProfile" version="NPWSDL1.0">
Description: Verifies that you can view a group's profile.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ gm_canIViewGroupProfile.wsdl
Parameters  
uid The DN of the group whose profile you want to view.

Rules: Required. Single value, a DN.


Example 2-17 illustrates testing the view group profile function.

Example 2-17 Example of Testing the Ability to View a Group Profile

<?xml version="1.0"?> 
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas-xmlsoap.org/soap/envelope/"> 

<SOAP-ENV:Body> 
<oblix:request application="groupservcenter" 
function="canIViewGroupProfile" version="NPWSDL1.0"> 

<oblix:params> 
<oblix:uid>cn=Marketing Team, ou=Marketing, o=Company, c=US
</oblix:uid> 
</oblix:params> 
</oblix:request> 

</SOAP-ENV:Body> 
</SOAP-ENV:Envelope>

2.7.1.2 Can I view an attribute in a group's profile

Function name canIViewGroupProfileAttr
Request example: <oblix:request application="groupservcenter" function="canIViewGroupProfileAttr" version="NPWSDL1.0">
Description: Verifies that you can view a particular attribute in a group's profile.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ gm_canIViewGroupProfileAttr.wsdl
Parameters  
uid The DN of the group whose attribute you want to view.

Rules: Required. Single value, a DN.

targetAttribute The schema name (not the display name) for the desired attribute.

Rules: Required. Single value, a string.


2.7.1.3 Can I modify an attribute in a group's profile

Function name canIModifyGroupProfileAttr
Request example: <oblix:request application="groupservcenter" function="canIModifyGroupProfileAttr" version="NPWSDL1.0">
Description: Verifies that you can change a particular attribute in a group's profile.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ gm_canIModifyGroupProfileAttr.wsdl
Parameters  
uid The DN of the group whose attribute you want to change.

Rules: Required. Single value, a DN.

targetAttribute The schema name (not the display name) for the desired attribute.

Rules: Required. Single value, a string.


2.7.1.4 Can I request modification through a workflow of an attribute in a group profile

Function name canIRequestGroupAttrModification
Request example: <oblix:request application="groupservcenter" function="canIRequestGroupAttrModification" version="NPWSDL1.0">
Description: Verifies that you can change a particular attribute in a group's profile, using a workflow.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ gm_canIRequestGroupAttrModification.wsdl
Parameters  
uid The DN of the group whose attribute you want to change.

Rules: Required. Single value, a DN.

targetAttribute The schema name (not the display name) for the desired attribute.

Rules: Required. Single value, a string.


2.7.1.5 Can I create a new group

Function name canICreateGroup
Request example: <oblix:request application="groupservcenter" function="canICreateGroup" version="NPWSDL1.0">
Description: Verifies that you can create a new group.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ gm_canICreateGroup.wsdl
Parameters  
ObDomainName A subtree within which a test is being requested.

Rules: Optional. Single value, a DN.

Default: If no value is provided, the Identity System checks to see if you have the tested rights in any domain.

Objectclass The auxiliary object class(es), if any, within which the group is to be created. This applies only to Group Manager, where the auxiliary object classes correspond to the group types.

You find the values for these using Identity System Console, Group Manager Configuration, Group Types, Configure Group Type Panels. Select the group, and find the Associated ObjectClass name displayed.

Rules: Optional. Multivalued.


2.7.1.6 Can I delete an existing group

Function name canIDeleteGroup
Request example: <oblix:request application="groupservcenter" function="canIDeleteGroup" version="NPWSDL1.0">
Description: Verifies that you can delete an existing group.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ gm_canIDeleteGroup.wsdl
Parameters  
uid The DN of an entry you want to modify.

Rules: Required. Single value, a DN.


2.7.1.7 Can I subscribe to a group

Function name canISubscribeToGroup
Request example: <oblix:request application="groupservcenter" function="canISubscribetoGroup" version="NPWSDL1.0">
Description: Verifies that you can subscribe to a specific group.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ gm_canISubscribeToGroup.wsdl
Parameters  
uid The DN of the group to which you want to subscribe.

Rules: Required. Single value, a DN.


2.7.1.8 Can I unsubscribe from a group

Function name canIUnsubscribeFromGroup
Request example: <oblix:request application="groupservcenter" function="canIUnSubscribeFromGroup" version="NPWSDL1.0">
Description: Verifies that you can unsubscribe from a specific group.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ gm_canIUnSubscribeFromGroup.wsdl
Parameters  
uid The DN of the group from which you want to unsubscribe.

Rules: Required. Single value, a DN.


2.7.1.9 Am I a member of a group

Function name amIAMember
Request example: <oblix:request application="groupservcenter" function="amIAMember" version="NPWSDL1.0">
Description: Use this function to determine if the logged in user is a member of any group. It checks for static membership by default. If you also want to test the nested or dynamic membership, you need to use the optional flags as described in the "Parameters" section of this table. Use the function memberOfAGroup to determine third-person group membership.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ gm_amIAMember.wsdl
Parameters  
uid The DN of the entry you want to query.

Rules: Required. Single value, a DN.

checkNested Set this parameter to true to check nested groups for membership.

Rules: Optional. Single-valued, a flag.

Default: false.

Note: Using the TurnOffNestedGroupEvaluation parameter in the Identity Server groupdbparams.xml file does not override checkNested in the amIAMember IdentityXML call. For details, see the chapter on performance in the Oracle Access Manager Deployment Guide.

checkDynamic Set this parameter to true to check dynamic groups for membership.

Rules: Optional. Single-valued, a flag.

Default: false.

Note: Using the TurnOffDynamicGroupEvaluation parameter in the Identity Server groupdbparams.xml file does not override checkDynamic in the amIAMember IdentityXML call. For details, see the chapter on performance in the Oracle Access Manager Deployment Guide.


2.7.1.10 Can a user view a group's profile

Function name canUserViewGroupProfile
Request example: <oblix:request application="groupservcenter" function="canUserViewGroupProfile" version="NPWSDL1.0">
Description: Verifies that a non-logged in user can view a group's profile.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ gm_canUserViewGroupProfile.wsdl
Parameters  
uid The DN of the group whose profile you want to view.

Rules: Required. Single value, a DN.

proxysourceuid The DN for a non-logged-in user (proxy user) whose access rights are being tested.

Though it is outside the intent of functions using this parameter, DNs other than those of users can be used.

Rules: Required. Single value, a DN.


2.7.1.11 Can a user view an attribute in a group's profile

Function name canUserViewGroupProfileAttr
Request example: <oblix:request application="groupservcenter" function="canUserViewGroupProfileAttr" version="NPWSDL1.0">
Description: Verifies that a non-logged in user can view a particular attribute in a group's profile.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ gm_canUserViewGroupProfileAttr.wsdl
Parameters  
uid The DN of the group whose attribute you want to view.

Rules: Required. Single value, a DN.

proxysourceuid The DN for a non-logged-in user (proxy user) whose access rights are being tested.

Though it is outside the intent of functions using this parameter, DNs other than those of users can be used.

Rules: Required. Single value, a DN.

targetAttribute The schema name (not the display name) for the desired attribute.

Rules: Required. Single value, a string.


2.7.1.12 Can a user modify an attribute in a group profile using a workflow

Function name canUserRequestGroupAttrModification
Request example: <oblix:request application="groupservcenter" function="canUserRequestGroupAttrModification" version="NPWSDL1.0">
Description: Verifies that a non-logged in user can request a change to a particular attribute in a group's profile, using a workflow.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ gm_canUserRequestGroupAttrModification.wsdl
Parameters  
uid The DN of the group whose attribute you want to modify.

Rules: Required. Single value, a DN.

proxysourceuid The DN for a user (proxy user) whose access rights are being tested.

Rules: Required. Single value, a DN.

targetAttribute The schema name (not the display name) for the desired attribute.

Rules: Required. Single value, a string.


2.7.1.13 Can a user create a new group

Function name canUserCreateGroup
Request example: <oblix:request application="groupservcenter" function="canUserCreateGroup" version="NPWSDL1.0">
Description: Verifies that a non-logged in user can create a new group.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ gm_canUserCreateGroup.wsdl
Parameters  
proxysourceuid The DN for a user (proxy user) whose rights are being tested.

Rules: Required. Single value, a DN.

ObDomainName A subtree within which a test is being requested.

Rules: Optional. Single value, a DN.

Default: if no value is provided, the Identity System checks to see if you have the tested rights in any domain.


2.7.1.14 Can a user delete an existing group

Function name canUserDeleteGroup
Request example: <oblix:request application="groupservcenter" function="canUserDeleteGroup" version="NPWSDL1.0">
Description: Verifies that a non-logged in user can delete an existing group.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ gm_canUserDeleteGroup.wsdl
Parameters  
proxysourceuid The DN for a non-logged-in user (proxy user) whose access rights are being tested.

Rules: Required. Single value, a DN.

uid The DN of the entry.

Rules: Optional. Single value, a DN.


2.7.1.15 Is this person a member of a group

Function name memberOfAGroup
Request example: <oblix:request application="groupservcenter" function="memberOfAGroup" version="NPWSDL1.0">
Description: Third-person IdentityXML request to check a person's membership to a particular group. It checks for static membership by default. If you also want to test the nested or dynamic membership, you need to use the optional flags as described in the "Parameters" section of this table. You must have view access for the dynamic filter attribute.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ gm_memberOfAGroup.wsdl
Parameters  
proxysourceuid The DN for a non-logged-in user (proxy user) whose access rights are being tested.

Rules: Required. Single value, a DN.

uid The DN of the entry.

Rules: Required. Single value, a DN.

checkNested Set this parameter to true to check nested groups for membership.

Rules: Optional. Single-valued, a flag.

Default: false

Note: Using the TurnOffNestedGroupEvaluation parameter in the Identity Server groupdbparams.xml file does not override checkNested in the memberOfAGroup IdentityXML call. For details, see the chapter on performance in the Oracle Access Manager Deployment Guide.

checkDynamic Set this parameter to true to check dynamic groups for membership.

Rules: Optional. Single-valued, a flag.

Default: false.

Note: Using the TurnOffDynamicGroupEvaluation parameter in the Identity Server groupdbparams.xml file does not override checkDynamic in the memberOfAGroup IdentityXML call. For details, see the chapter on performance in the Oracle Access Manager Deployment Guide.


2.7.1.16 Request group attribute change

Function name canUserModifyGroupProfileAttr
Request example: <oblix:request application="groupservcenter" function="canUserModifyGroupProfileAttr" version="NPWSDL1.0">
Description: Verifies that a non-logged in user can change a particular attribute in a group's profile.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ gm_canUserModifyGroupProfileAttr.wsdl
Parameters  
uid The DN of the group whose attribute you want to modify.

Rules: Required. Single value, a DN.

proxysourceuid The DN for a non-logged-in user (proxy user) whose access rights are being tested.

Rules: Required. Single value, a DN.

targetAttribute The schema name (not the display name) for the desired attribute.

Rules: Required. Single value, a string.


2.7.1.17 Request group attribute change through a workflow

See "Request User Attribute Change Through a Workflow". Note that the application name is groupservcenter.

2.7.2 Functions to Perform Group Manager Actions

The following IdentityXML functions allow you to perform the following actions. These are get and set functions.

2.7.2.1 View Group Attributes

See "View User Attributes". Note that the application name is groupservcenter.

2.7.2.2 Modify Group Attributes

IdentityXML requests for gathering the attribute list pertaining to modifying a profile (modifyUser, modifyGroup, and modifyObject), no longer depend on a panel in the Identity System. For these functions, the attribute parameter must be configured in the Identity System. However, the attribute parameter need not be included in a panel configured for a user, group, or object profile. The GUI-based request for gathering the attribute list pertaining to modifying a profile continues to require the attributes listed on a panel.

Note:

With IdentityXML, an attribute listed in the negativeListForEntityAttributes list in the globalparams.xml file can can only be read and cached. For details, see the topic on tuning the internal DBAgent cache in the Oracle Access Manager Deployment Guide.
Function name modifyGroup
Request example: <oblix:request application="groupservcenter" function="modifyGroup" version="NPWSDL1.0">
Description: Use this function to change group attributes.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ gm_modifyGroup.wsdl
Parameters  
uid The DN of the group whose attributes are to be changed.

Rules: Required. Single value, a DN.

attrName Required. See "Attribute Parameters" for details.
attrOperation Required. See "Attribute Parameters" for details.
attrNewValue Required. See "Attribute Parameters" for details.
noOfFields Required. See "Attribute Parameters" for details.
ObAuxClassesOldValues The old values of the auxiliary class names that you want to replace. This is used only to change the name information for auxiliary classes associated with groups. Use this parameter once for each auxiliary class name to be removed.

If you attempt to specify a value for which you do not have access, you get an error message "Invalid value for attributeObAuxClasses."

You find the values for these using the Identity System Console, Group Manager Configuration, Group Types, Configure Group Type Panels. Select the group, and find the Associated ObjectClass name displayed.

Rules: Required only if the attribute is for an auxiliary class and the ObAuxClassesOperation is a REPLACE, otherwise ignored. Multivalued.

ObAuxClassesOperation The type of operation to perform on the attribute. This is used only to change the name information for auxiliary classes.

Legal values are:

ADD: Add the auxiliary class name to the existing attributes.

DELETE: Delete the auxiliary class name from the existing attributes.

REPLACE: Delete the old auxiliary class name and replace it with the new auxiliary class name.

If you specify any other value or no value, you get an error message "Invalid value for attribute ObAuxClasses."

Rules: Required only if the attribute is for an auxiliary class. Single value.

ObAuxClassesValues The name of the auxiliary class that you want to add, delete, or replace. This is used only to change the name information for auxiliary classes.

Use this parameter once for each auxiliary class name to be added or removed.If you attempt to specify a value for which you do not have access, you get an error message "Invalid value for attributeObAuxClasses".

To find the values for these, use the Identity System Console, Group Manager Configuration, Group Types, Configure Group Type Panels. Select the group, and find the Associated ObjectClass name.

Rules: Required if the attribute is for an auxiliary class. Multivalued. Valid values are the string names of the configured auxiliary classes available. (Auxiliary classes are configured through the System Console Configure Object Class function, see the Oracle Access Manager Identity and Common Administration Guide.)

attrOldValue Optional/Required. Required only if the attrOperation is a REPLACE. This needs to be an exact match. If not, no change takes place.

See "Attribute Parameters" for details.


2.7.2.3 Create group

See "Create User Using a Workflow". Note that the application name is groupservcenter.

2.7.2.4 Delete Group

Function name delete (group)
Request example: <oblix:request application="groupservcenter" function="delete" version="NPWSDL1.0">
Description: Use this function to delete a group. You have very little control over this function, beyond specifying the name of the group. Determination of the workflow to be used is made by the application. The workflow selected satisfies all of the following: 1) the target domain contains the group entry; 2) you are a participant in the initiate step of the workflow, and 3) the group types of the group to be deleted are a subset of the group types in the workflow definition.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ gm_delete.wsdl
Parameters  
uid Rules: Required. Single value, a DN.

2.7.2.5 Get groups that I am a member, owner, or administrator of

Function name myGroupsProfile
Request example: <oblix:request application="groupservcenter" function="myGroupsProfile" version="NPWSDL1.0">
Description: Use this function to get the profiles for groups you are a member, owner or an administrator of. Parameters used here override the configured Group Manager Options.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ gm_myGroupsProfile.wsdl
Parameters  
attrName Optional. See "Attribute Parameters" for details.
showAdministratorOfGroups Use this parameter to ask for groups you, or another user, are an administrator of to be included in the response.

Rules: Optional. At least one of the parameters in the showxxx list must be used. Single value, Boolean, true or false.

Default: false

showDynamicGroups Use this parameter to ask for groups you, or another user, are a dynamic member of to be included in the response.

showMemberOfGroups must also be used, set to true.

Rules: Optional. Single value, Boolean, true or false.

Default: false.

Note: Using the TurnOffDynamicGroupEvaluation parameter in the Identity Server groupdbparams.xml file does not override showDynamicGroups in the myGroupsProfile IdentityXML call. For details, see the chapter on performance in the Oracle Access Manager Deployment Guide.

showMemberOfGroups Use this parameter to ask for groups that you, or another user, are a member of to be included in the response.

Rules: Optional. Single value, Boolean, true or false.

Default: false—Optional.

showNestedGroups Use this parameter to ask for nested groups you, or another user, are a member of to be included in the response. showMemberOfGroups must also be used, set to true. And one or both of showStaticGroups and showDynamicGroups must also be used, set to true.Rules: Optional. Single value, Boolean, true or false.Default: false

Note: Using the TurnOffNestedGroupEvaluation parameter in the Identity Server groupdbparams.xml file does not override showNestedGroups in the myGroupsProfile IdentityXML call. For details, see the chapter on performance in the Oracle Access Manager Deployment Guide.

showOwnerOfGroups Use this parameter to ask for groups you, or another user, are an owner of to be included in the output.

Rules: Optional. Single value, Boolean, true or false.

Default: false

showStaticGroups Use this parameter to ask for groups you, or another user, are a static member of to be included in the response.

showMemberOfGroups must also be used, set to true.

Rules: Optional. Single value, Boolean, true or false.

Default: false


Note:

The show... options do not all have the same precedence. The parameters showOwnerOfGroups and showAdministratorOfGroups is always applied if entered.

The parameter showMemberOfGroups must be set to true to use showStaticGroups, showDynamicGroups, and showNestedGroups. The showNestedGroups parameter can only be set to true if either or both of the nested group categories showStaticGroups and showDynamicGroups is set to true.The IdentityXML request uses these options instead of the configured Group Manager options that may have been set using the System Console.

2.7.2.6 Get groups that a user is a member, owner, or administrator of

Function name userGroupsProfile
Request example: <oblix:request application="groupservcenter" function="userGroupsProfile" version="NPWSDL1.0">
Description: Use this function to get the profiles for groups that another user is a member, owner or an administrator of.
Rights: The logged-in user must be able to grant read capability on the proxysourceuid classname attribute.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ gm_userGroupsProfile.wsdl
Parameters  
proxysourceuid The DN for a non-logged-in user (proxy user) whose group profile you want.

Rules: Required. Single value, a DN.

attrName Optional. See "Attribute Parameters" for details.
showAdministratorOfGroups Use this parameter to ask for groups you, or another user, are an administrator of to be included in the response.

Rules: Optional. At least one of the parameters in the showxxx list must be used. Single value, Boolean, true or false.

Default: false

showDynamicGroups Use this parameter to ask for groups you, or another user, are a dynamic member of to be included in the response.

showMemberOfGroups must also be used, set to true.

Rules: Optional. Single value, Boolean, true or false.

Default: false.

Note: Using the TurnOffDynamicGroupEvaluation parameter in the Identity Server groupdbparams.xml file does not override showDynamicGroups in the userGroupsProfile IdentityXML call. For details, see the chapter on performance in the Oracle Access Manager Deployment Guide.

showMemberOfGroups Use this parameter to ask for groups that you, or another user, are a member of to be included in the response.Rules: Optional. Single value, Boolean, true or false.Default: false—Optional.
showNestedGroups Use this parameter to ask for nested groups you, or another user, are a member of to be included in the response. showMemberOfGroups must also be used, set to true. And one or both of showStaticGroups and showDynamicGroups must also be used, set to true.Rules: Optional. Single value, Boolean, true or false.Default: false

Note: Using the TurnOffNestedGroupEvaluation parameter in the Identity Server groupdbparams.xml file does not override showNestedGroups in the userGroupsProfile IdentityXML call. For details, see the chapter on performance in the Oracle Access Manager Deployment Guide.

showOwnerOfGroups Use this parameter to ask for groups you, or another user, are an owner of to be included in the output.

Rules: Optional. Single value, Boolean, true or false.

Default: false

showStaticGroups Use this parameter to ask for groups you, or another user, are a static member of to be included in the response.

showMemberOfGroups must also be used, set to true.

Rules: Optional. Single value, Boolean, true or false.

Default: false


Example 2-17 illustrates getting the groups that a user is a member, owner, or administrator of.

Example 2-18 Example of Getting the Groups that a User is a Member, Owner, or Administrator Of

<?xml version="1.0"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas-xmlsoap.org/soap/envelope/"
  xmlns:oblix="http://www.oblix.com"> 
<SOAP-ENV:Body>
<oblix:request function="userGroupsProfile" mode="dataonly" version="NPWSDL1.0"> >
<oblix:params>
<oblix:param name="proxysourceuid">cn=dummyuser,o=Person,c=ES</oblix:param>
<oblix:param name="showMemberOfGroups">true</oblix:param>
<oblix:param name="showNestedGroups">true</oblix:param>
</oblix:params>
</oblix:request>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

2.7.2.7 View group members

Function name viewGroupMembers
Request example: <oblix:request application="groupservcenter" function="viewGroupMembers" version="NPWSDL1.0">
Description: View all or selected members of a group. To get selected members of the group, you use the SearchAttr, SearchOperation, or SearchString parameters. You may use only one set. The length of the string value provided for SStn or SearchString must be at greater than or equal to the value for the groupMemberSearchStringMiminumLength parameter in the groupservcenterparams.xml file. If you set this value to zero, you do not need to use the SLkn, SStn, and STyn parameters or the SearchAttr, SearchOperation, and SearchString parameters, and all members of the group are returned in the search.

This function gets all or some members of the specified group. The search is allowed only on one field. You can only have only one triplet of STy1, SLk1 and SSt1 or SearchString, SearchOperation, and SearchAttr. If you don't specify any search parameters, this function returns all members of the group if the administrator has set the minimum search length to be 0 through the groupMemberSearchStringMiminumLength parameter in the Identity Server/oblix/apps/groupservcenter/bin/groupservcenterparams.xml file. If this is set to 0, then the search returns all the members of the group. If this is not 0, then the search triplet must be specified, plus the string to search for (as specified through SSt1) should have at least the same number of characters as specified by the groupMemberSearchStringMiminumLength parameter.

In order to view group members, the access control requirements are the following:

1. To view any members (Static, Dynamic, Nested), you need to have View right on the Member attribute.

2. To view Dynamic members, you also need to have View right on the "Dynamic Filter" attribute.

Rights: To view any members (Static, Dynamic, Nested), you need to have the View right on the Member attribute. To view. Dynamic members, you must additionally have the View right on the Dynamic Filter attribute.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ gm_viewGroupMembers.wsdl
Parameters  
uid The DN of the group whose members are to be listed.

Rules: Required. Single value, a DN.

attrName Optional. Use one or more instances of this to specify the attributes that you want to see for each group member. Use the LDAP name of each attribute, not its display name. If you do not specify particular attributes the default is to show the class attribute of the person object class. See "Attribute Parameters" for details.
memberIDsOnly Optional. Values are true or false. If you set this flag, only the class attribute is returned even if other attributes are requested. This limitation exists because The Identity System reads the data from the cache rather than the directory. This feature only takes affect after the first request, after all caches are initialized. The advantage of this flag is that directory hits are minimized.

When this flag is set to true, attributes requested with the attrName parameter are ignored, with the exception of the class attribute and attributes matching any search criteria.

Rules: Optional. Boolean, true or false.

Default: false.

showDynamicUserMembers Specifies whether dynamic members of a group are to be included in the response.

Rules: Optional. At least one of the show parameters in the list must be used and be set to true. Single value, Boolean, true or false.

Default: false.

Note: Using the TurnOffDynamicGroupEvaluation parameter in the Identity Server groupdbparams.xml file does not override showDynamicUserMembers. For TurnOffDynamicGroupEvaluation details, see performance chapter of the Oracle Access Manager Deployment Guide.

showNestedUserMembers Specifies whether nested members of a group are to be included in the response.

Rules: Optional. Single value, Boolean, true or false.

Default: false

Note: Using the TurnOffDNestedroupEvaluation parameter in the Identity Server groupdbparams.xml file does not override showNestedUserMembers. For TurnOffDNestedroupEvaluation details, see performance chapter of the Oracle Access Manager Deployment Guide.

showStaticUserMembers Optional.
SearchAttr Required. See "Search Parameters" for details.
SearchOperation Required. See "Search Parameters" for details.
SearchString Required. See "Search Parameters" for details.
groupMemberType Specifies the type of members that you want to view, for example "user" or "group". The value is the LDAP name of the object class that contains the type of objects you want to view. This is a single-valued attribute. You can only retrieve one type of group member at a time. Nested and dynamic evaluation is performed only for members who are users. Nested and dynamic evaluation is not performed for members that are groups or generic objects.

Rules: Required.


2.7.2.8 Expand group

Function name expandGroup
Request example: <oblix:request application="groupservcenter" function="expandGroup" version="NPWSDL1.0">
Description: Expands a dynamic group into its current static members.
Rights: To expand a group, the user must have the view rights for the group name and for the attributes Group Dynamic Filter and Group Expansion, and modify rights for the Member attribute. Group Dynamic Filter is the attribute that is of semantic type, dynamic filter. The Group Expansion attribute is the attribute of type, obgroupexpandeddynamic in the oblixadvancedgroup auxiliary objectclass. Member is the attribute that is of semantic type, Static Member.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ gm_expandGroup.wsdl
Parameters  
groupsToExpand A target group you want to expand. One or the other of these must be provided.

Rules: Optional. Multivalued, a DN.

expandAllGroups Expands all groups that you have rights to expand. If set to true, then all such groups are expanded. If set to false, then only the groups specified with the groupsToExpand parameter are expanded.

Rules: Optional. Single value, Boolean, true or false.

Default: false


2.7.2.9 Flush the Group Cache

Function name flushGroupCache
Request example: <oblix:request application="groupservcenter" function="flushGroupCache" version="NPWSDL1.0">
Description: Use this function to remove groups from the group cache. One of the two parameters shown in the "Parameters" section of this table must be provided.
Rights: To flush the group cache, the user must be a Master Administrator.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ gm_flushGroupCache.wsdl
Parameters  
flushGroup Optional. Removes from the group cache those groups whose dn is specified as a value.
flushGroupAll Optional.Removes all groups from the group cache if value = true.

2.7.2.10 Subscribe a user to a group

Function name subscribeUserToGroup
Request example: <oblix:request application="groupservcenter" function="subscribeUserToGroup" version="NPWSDL1.0">
Description: Add (subscribe) a user other than yourself to a group. The other user does not need to be logged in. The response returns the profile for the group.
Results: The output is the profile of the group, defined by the schema file oblix\WebServices\XMLSchema\gsc_groupprofile.xsd.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ gm_subscribeUserToGroup.wsdl
Parameters  
uid The DN of the group being subscribed to. This DN must fall under the searchbases of the logged-in user.

Rules: Required. Single value, a DN.

proxysourceuid The DN for a non-logged-in user who is subscribing to the group. This DN must fall under the searchbases of the logged-in user

Rules: Required. Single value, a DN.


2.8 Organization Manager Functions

If you are an administrator, the Organization Manager enables you to create and delete organizations and other objects (such as floor plans and assets) that do not belong in the User Manager or Group Manager. The Organization Manager enables end users to view organizational entities such as floor plans. The organizational entities that a person can view depend upon the rights granted by a Master Administrator.

The following IdentityXML functions allow you to programmatically access the Organization Manager. Note that all functions follow a similar syntax:

<oblix:request application="objservcenter" function="name" version="version">

For example:

<oblix:request application="objservcenter" function="canIViewObjectProfile" version="NPWSDL1.0">

Note:

The version tag is required if you are using IdentityXML with Oracle Access Manager 6.5 and higher versions.

For documentation of the pre-6.5 IdentityXML version tag, see the following:

http://www.oracle.com/technology/

2.8.1 Functions to Test For Attribute Permissions

The following functions provide a yes or no response as to whether you or another user have read, write, delegate, and notify permissions set for a particular attribute.

2.8.1.1 Can I view an object's profile

Function name canIViewObjectProfile
Request example: <oblix:request application="objservcenter" function="canIViewObjectProfile" version="NPWSDL1.0">
Description: Verifies that you can view an organization's profile.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ om_canIViewObjectProfile.wsdl
Parameters  
uid The DN of the organization whose profile you want to view.

Rules: Required. Single value, a DN.


2.8.1.2 Can I view an attribute in the object's profile

Function name canIViewObjectProfileAttr
Request example: <oblix:request application="objservcenter" function="canIViewObjectProfileAttr" version="NPWSDL1.0">
Description: Verifies that you can view a particular attribute in an organization's profile.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ om_canIViewObjectProfileAttr.wsdl
Parameters  
uid The DN of the organization whose attribute you want to view.

Rules: Required. Single value, a DN.

targetAttribute The schema name (not the display name) for the desired attribute.

Rules: Required. Single value, a string.


2.8.1.3 Can I modify an attribute in an object's profile

Function name canIModifyObjectProfileAttr
Request example: <oblix:request application="objservcenter" function="canIModifyObjectProfile" version="NPWSDL1.0">
Description: Verifies that you can change a particular attribute in an organization's profile.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ om_canIModifyObjectProfileAttr.wsdl
Parameters  
uid The DN of the organization whose attribute you want to change.

Rules: Required. Single value, a DN.

targetAttribute The schema name (not the display name) for the desired attribute.

Rules: Required. Single value, a string.


2.8.1.4 Can I request modification through a workflow of an attribute in an object's profile

Function name canIRequestObjectAttrModification
Request example: <oblix:request application="objservcenter" function="canIRequestObjectAttrModification" version="NPWSDL1.0">
Description: Verifies that you can change a particular attribute in an organization's profile, using a workflow.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ om_canIRequestObjectAttrModification.wsdl
Parameters  
uid The DN of the organization whose attribute you want to change.

Rules: Required. Single value, a DN.

targetAttribute The schema name (not the display name) for the desired attribute.

Rules: Required. Single value, a string.


2.8.1.5 Can I create a new object

Function name canICreateObject
Request example: <oblix:request application="objservcenter" function="canICreateObject" version="NPWSDL1.0">
Description: Verifies that you can create a new organization.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ om_canICreateObject.wsdl
Parameters  
ObDomainName A subtree within which a test is being requested.

Rules: Optional. Single value, a DN.

Default: If no value is provided, the Identity System checks to see if you have the tested rights in any domain.


2.8.1.6 Can I delete an existing object

Function name canIDeleteObject
Request example: <oblix:request application="objservcenter" function="canIDeleteObject" version="NPWSDL1.0">
Description: Verifies that you can delete an existing object.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ om_canIDeleteObject.wsdl
Parameters  
uid Rules: Required. Single value, a DN.

2.8.1.7 Can this user view an object's profile

Function name canUserViewObjectProfile
Request example: <oblix:request application="objservcenter" function="canUserViewObjectProfile" version="NPWSDL1.0">
Description: Verifies that a non-logged in user can view an organization's profile.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ om_canUserViewObjectProfile.wsdl
Parameters  
uid The DN of the organization whose profile you want to view.

Rules: Required. Single value, a DN.

proxysourceuid The DN for a non-logged-in user (proxy user) whose access rights are being tested.

Rules: Required. Single value, a DN.


2.8.1.8 Can this user view an attribute in an object's profile

Function name canUserViewObjectProfileAttr
Request example: <oblix:request application="objservcenter" function="canUserViewObjectProfileAttr" version="NPWSDL1.0">
Description: Verifies that a non-logged in user can view a particular attribute in an organization's profile.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ om_canUserViewObjectProfileAttr.wsdl
Parameters  
uid The DN of the organization whose attribute you want to view.

Rules: Required. Single value, a DN.

proxysourceuid The DN for a non-logged-in user (proxy user) whose access rights are being tested.

Rules: Required. Single value, a DN.

targetAttribute The schema name (not the display name) for the attribute.

Rules: Required. Single value, a string.


2.8.1.9 Can a user modify an attribute in an object's profile

Function name canUserModifyObjectProfileAttr
Request example: <oblix:request application="objservcenter" function="canUserModifyObjectProfileAttr" version="NPWSDL1.0">
Description: Verifies that a non-logged in user can change a particular attribute in an organization's profile.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ om_canUserModifyObjectProfileAttr.wsdl
Parameters  
uid The DN of the object whose attribute you want to modify.

Rules: Required. Single value, a DN.

proxysourceuid The DN for a non-logged-in user (proxy user) whose access rights are being tested.

Rules: Required. Single value, a DN.

targetAttribute The schema name (not the display name) for the desired attribute.

Rules: Required. Single value, a string.


2.8.1.10 Can a user create a new object

Function name canUserCreateObject
Request example: <oblix:request application="objservcenter" function="canUserCreateObject" version="NPWSDL1.0">
Description: Verifies that a non-logged in user can create a new object.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\om_canUserCreateObject.wsdl
Parameters  
proxysourceuid The DN for a non-logged-in user (proxy user) whose access rights are being tested.

Rules: Required. Single value, a DN.

ObDomainName A subtree within which a test is being requested.

Rules: Optional. Single value, a DN.

Default: if no value is provided, the Identity System checks to see if you have the tested rights in any domain.


2.8.1.11 Can a user delete an existing object

Function name canUserDeleteObject
Request example: <oblix:request application="objservcenter" function="canUserDeleteObject" version="NPWSDL1.0">
Description: Verifies that a non-logged in user can delete an existing organization.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ om_canUserDeleteObject.wsdl
Parameters  
proxysourceuid The DN for a non-logged-in user (proxy user) whose access rights are being tested.

Rules: Required. Single value, a DN.

uid Rules: Required. Single value, a DN.

2.8.1.12 Can this user request an object attribute modification

Function name canUserViewObjectAttrModification
Request example: <oblix:request application="objservcenter" function="canUserRequestObjectAttrModification" version="NPWSDL1.0">
Description: Verifies that a non-logged in user can request a change to a particular attribute in an object profile using a workflow.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ om_canUserRequestObjectAttrModification.wsdl
Parameters  
uid The DN of the object whose attribute you want to modify.

Rules: Required. Single value, a DN.

proxysourceuid The DN for a non-logged-in user (proxy user) whose access rights are being tested.

Rules: Required. Single value, a DN.

targetAttribute The schema name (not the display name) for the desired attribute.

Rules: Required. Single value, a string.


2.8.2 Functions to Perform Organization Manager Actions

The following functions allow you to perform actions in the Organization Manager. These are get and set functions.

2.8.2.1 View object attributes

See "View User Attributes" for details.

2.8.2.2 Modify object attributes

IdentityXML requests for gathering the attribute list pertaining to modifying a profile (modifyObject), no longer depend on a panel in the Identity System. For this function, the attribute parameter must be configured in the Identity System. However, the attribute parameter need not be included in a panel configured for an object profile. The GUI-based request for gathering the attribute list pertaining to modifying a profile continues to require the attributes listed on a panel.

Note:

With IdentityXML, an attribute listed in the negativeListForEntityAttributes list in the globalparams.xml file can only be read and cached. For details, see the topic on tuning the internal DBAgent cache in the Oracle Access Manager Deployment Guide.
Function name modifyObject
Request example: <oblix:request application="objservcenter" function="modifyObject" version="NPWSDL1.0">
Description: Use this function to modify object attributes.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ om_modifyObject.wsdl
Parameters  
uid The DN of the object whose attributes are to be changed.

Rules: Required. Single value, a DN.

attrName Optional. If no attrNames are specified, all the attributes of the entry that the caller has access to view are returned. This parameter is useful when you want to modify a few attributes and only want those attributes back in the result of a modify call. This can save on performance when the profile contains a large number of attributes. See "Attribute Parameters" for details.
attrOperation Required. See "Search Parameters" for details.
attrNewValue Required. See "Attribute Parameters" for details.
NoOfFields Required. See "Attribute Parameters" for details.
attrOldValue Required/Optional. Required only if the attrOperation is a REPLACE.

2.8.2.3 Request object attribute change through a workflow

See "Request User Attribute Change Through a Workflow".

2.8.2.4 Create an object

See "Create User Using a Workflow" for details.

2.8.2.5 Self-registration

See "Self-Registration Using a Workflow" for details.

2.8.2.6 Delete object

Function name delete (organization)
Request example: <oblix:request application="objservcenter" function="delete" version="NPWSDL1.0">
Description: Use this function to delete an organization.
WSDL file: WebPass_install_dir\oblix\WebServices\WSDL\ om_delete.wsdl
Parameters  
uid The DN of the group or whose attributes are to be changed.

Rules: Required. Single value, a DN.

ObWorkflowName The name of the workflow that you want to use to create or change the value(s) for an attribute.

Find the full DN for ObWorkflowName under the view menu for workflow definition under the particular application.

Rules: Required. Single value, a DN.

ObWfComment Provides a comment for a step in a workflow.

Rules: Optional. Single value, string.

NoOfFields Optional. Required. See "Attribute Parameters" for details.
attrName Optional. The attribute specified should be an attribute configured in the Identity System console, and it should be part of one of the panels configured for the View Profile of the user, group, or organization. Otherwise, it is considered invalid. See "Attribute Parameters" for details.
attrNewValue Required. See "Attribute Parameters" for details.
attrOldValue Optional/Required. Required only if the attrOperation is a REPLACE.

2.9 Code Examples of Deployed IdentityXML Functions

The following sections provide examples of how IdentityXML can be packaged and deployed.

2.9.1 Java Application Example

Example 2-19 sends a SOAP message contained in a file to a Identity System application using HTTP.

The code for this example is located in:

Component_install_dir\identity\oblix\unsupported\integsvs\

Example 2-19 illustrates the basics of IdentityXML programming. For instance, the Identity System can be scripted using techniques like this. You can write small programs that do one thing, such as transmit a pre-composed message, and glue them together in Perl or shell scripts to perform more complex tasks with the Identity System. The intelligence concerning the message contents need not be part of the IdentityXML client.

Example 2-19 Java Example to Query the Identity System using SOAP

/**
 * This is a very simple SOAP example of how to invoke Oracle Access Manager
 * through SOAP.  
 *
 * This program will make a soap request (send the request in soap.xml)
 * to the argument hostname:port/oblix/apps/corpdir/bin/corpdir.cgi
 * 
 * Requirements: 
 * *** ObSoapClient, a complete http client library from innovation, is 
 *     required to run this test.  The software is free, and licensed under the
 *     GNU Lesser General Public License.
 *     HTTPClient is available at http://www.innovation.ch/java/HTTPClient
 *     This program has been tested with HTTPClient Version 0.3-2
 *
 * To run:
 * *** java ObSoapClient [-h hostname] [-p port] [-f inputfile] [-u oblixurl]
 * 
 */
 
import java.net.URL;
import java.io.IOException;
import java.io.FileReader;
import java.io.BufferedReader;
import HTTPClient.CookieModule;
import HTTPClient.HTTPConnection;
import HTTPClient.HTTPResponse;
import HTTPClient.ModuleException;
import HTTPClient.NVPair;
 
public class ObSoapClient
{
        static String hostname = "sunlight.oracle.com";
        static String filename = "soap.xml";
        static int port = 80;
        static String oburl = "/identity/oblix/apps/userservcenter/bin/userservcenter.cgi"; 
 
        public static void collectArgs(String args[]) 
        {
                for (int i = 0; i < args.length; i++) {
                        if (args[i].equals("-h") && args.length >= i+1)
                                hostname = args[i+1];
                        else if (args[i].equals("-f") && args.length >= i+1)
                                filename = args[i+1];
                        else if (args[i].equals("-p") && args.length >= i+1)
                                port = Integer.parseInt(args[i+1]);
                        else if (args[i].equals("-u") && args.length >= i+1)
                                oburl = args[i+1];
                        else if (args[i].equals("-h") || args[i].equals("-help")) {
                                System.out.println("Usage: java ObSoapClient [-h hostname] [-p port] [-f filename] [-u oblixurl] \n");
                        }
                }
        }
 
        /**
   * Read from soap.xml in current directory and return as string.
         */
        public static String getRequestFromFile()
        {
                StringBuffer data = new StringBuffer();
                try {
                        BufferedReader reader = new BufferedReader(new FileReader(filename));
 
                        for (String line = reader.readLine(); line != null;
                                line = reader.readLine()) {
                                data.append(line);
                                data.append("\r\n");
                        }
                } catch (Exception e) {
                        System.out.println(e.toString());
                }
                return data.toString();
        }
 
        public static void main(String args[]) throws Exception
        {
                try { 
                        CookieModule.setCookiePolicyHandler(null);
 
                        // initiate connection
                        collectArgs(args);
                        HTTPConnection con = new HTTPConnection(hostname, port); 
 
                        // collect response
                        NVPair header[] = new NVPair[1];
                        header[0] = new NVPair("Content-Type", "text/xml");
                        HTTPResponse rsp = 
                                con.Post(oburl,
                                getRequestFromFile(), 
                                header); 
 
                        // get status and act accordingly
                        if (rsp.getStatusCode() >= 300) { 
                                System.err.println("Received Error: "+rsp.getReasonLine()); 
                                System.err.println(new String(rsp.getData())); 
                        } else 
                                System.out.println(new String(rsp.getData()));
                } catch (IOException ioe) { 
                        System.err.println(ioe.toString()); 
                } catch (ModuleException me) { 
                        System.err.println("Error handling request: " + me.getMessage()); 
                } catch (Exception e) {
                        System.out.println(e.toString());
                }
        }
        
}
 
/*
        NVPair form_data[] = new NVPair[2];
 
        form_data[0] = new NVPair("login", "J.Smith");
        form_data[1] = new NVPair("password", "J.Smith");
//      form_data[2] = new NVPair("uid", 
//              "cn=John Smith,ou=Corporate,o=Company,c=US");
//      form_data[3] = new NVPair("program", "personPage");
//      form_data[4] = new NVPair("tab_id", "Employees");
 
//      HTTPResponse rsp = con.Post("/oblix/apps/corpdir/bin/corpdir.cgi", form_data); 
 
*/

You should inspect the files, copy the one you wish to send into the current directory of the application, and modify the request parameters within the XML file to specify parameters that make sense for your directory (such as valid uid for a view request). Make sure you have that HTTPClient package from Innovation in your CLASSPATH. Then send the request with the following command:

java Lookup -f inputfile [-h hostname] [-p port][-u oblixurl]

2.9.2 Java Servlet Example

This example builds on the previous one. This example is a Java Servlet that runs within a Web or application server. Since simply printing out the result is not useful for a servlet, this one shows a simple example of using an Identity System attribute value to dynamically generate an HTML page. The servlet assumes your SOAP message invokes the User Manager view program, and gets user profile data as a response. It then uses the JAXP XML parser to parse the SOAP message containing the user profile, and extracts the email address attribute for the user being viewed.

If you log into User Manager before running this servlet, and edit the email attribute for the user you are going to look up so that it reads red or green, you can see that the value is used by the servlet in generating the resulting HTML page. It uses this value for the BGCOLOR attribute of the BODY element on the page, as well as printing it out. If you specify a valid color or #RRGGBB value, the page is displayed in that color.

The servlet assumes the following request to view a user profile from User Manager. This request, and many other examples, are installed in:

unsupported/integsvcs/um_view.xml

You should copy and modify the request file to specify a valid user uid for your directory. Make sure to put it in the current working directory for the servlet, or specify the full path when reading the file.

Example 2-20 is an example request file.

Example 2-20 Request File Example

<?xml version="1.0" ?> 
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas-xmlsoap.org/soap/envelope/"
xmlns:oblix="http://www.oblix.com">

<SOAP-ENV:Body>
<oblix:authentication xmlns:oblix="http://www.oblix.com" type="basic">
<oblix:login>user1k1</oblix:login> 
<oblix:password>oblix</oblix:password> 
</oblix:authentication>

<oblix:request function="view" version="NPWSDL1.0">
<oblix:params>
<oblix:uid>cn=Rohit Valiveti,ou=Sales, ou=Dealer1k1,ou=Latin America,
ou=Ford,o=Company,c=US</oblix:uid> 
<oblix:attrName>mail</oblix:attrName> 
</oblix:params>
</oblix:request>

</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

This request could easily have been constructed in code, but it is stored as a file for the purposes of this example. Note the general structure of the SOAP message, and the parameter elements being requested.

Example 2-21 is the code for MyobServelet, which sends this request, parses the result, and generates an HTML page dynamically as the result of the request. MyobServelet is derived from HttpServlet. It uses JAXP, a SAX parser for XML freely available from Sun Microsystems, and HTTPClient, a freely available HTTP client package available from Innovation. You may choose to use such packages, or integrate with your own as needed.

Example 2-21 MyobServelet.java

/**
* This example illustrates how to use the 
* Identity System via the IdentityXML interface from a Java servlet.
* The example uses two freely available third-party Java packages:
*   1. HTTPClient, from Innovation
*          (http://www.innovation.ch/java/HTTPClient)
*   2. JAXP, from Sun Microsystems
*         (http://java.sun.com/xml/xml_jaxp.html) 
* HTTPClient encapsulates the client side of the HTTP protocol.
* JAXP provides APIs for XML parsing and XSL processing.
*
* What This Servlet Does:
* This servlet reads a SOAP request from a text file /tmp/um_view.xml.
* It could quite easily have hard-coded the request, or built it
* from parameters, or fetched it from a database.  Reading it from
* a file just provides some simple flexibility and allows the code
* to be uncluttered with that detail.  The servlet uses HTTPClient
* to connect to the web server hosting the Identity System,
* sends the SOAP message to the User Manager application's URL
* (hard-coded in this example), and receives the response.  It then
* creates an XML parser, and uses a custom document handler,
* MyObReader, to handle only those elements of interest during the
* parse. In this case, MyObReader only cares about the ObEmail
* element.  When it finds the element, it stores the value, which
* is then available to this servlet via the MyObReader.getEmail()
* method after parsing.
* 
* As an HTTPServlet, a natural response for this servlet is an
* HTML page.  To illustrate use of Identity data in building the
* page returned, this servlet does something a little unusual: it
* uses the value of the user's email address as a color, and uses
* it to set BGCOLOR attribute of the BODY element in the output HTML.
*
* To demonstrate the example, you should edit the SOAP message to
* specify the DN of the user profile in your Identity System that
* you want to use.  Then, logged in as an NP admin, change the
* user's email address to a valid HTML color value. like "green"
* or an RGB value, like "#ffddff".  Then run the servlet (i.e.
* install in your WS and fetch .../servlets/EmailColor). The
* page built by the servlet should appear, with its background
* rendered in the color you saved as the email address.
* 
* The helper class, MyObReader, extends the DefaultHandler content
* handler of JAXP by adding handler methods for the ObEmail element
* and its nested ObValue element containing the email address,
* which is what this example is looking up. After the parse,
* the helper class is queried for the email address, and this
* is added to the HTTPSerlvlet output stream (a simple HTML page)
* which is sent back to the browser.
* To run:
*   Edit the SOAP message file, and make sure the hard-coded
*   path in this class points to where you saved the SOAP message.
*   Build the MyObServlet class and the MyObReader helper class.
*   Put the class files and JAR files for these two classes, plus
*   the HTTPClient package and JAXP in your web server's classpath
*   for servlets. For iPlanet Web Server, you can find this
*   in the console under   
*   Servlets/Configure JVM Attributes/Classpath.
*   Restart your web server if necessary.
*   Point your browser at <yourServletRoot>/ObSoapClient
*/
import java.io.*;
import java.net.*;
import java.util.*;
import javax.servlet.*;
import javax.servlet.http.*;
import HTTPClient.*;
// JAXP packages
import javax.xml.parsers.*;
import org.xml.sax.*;
import org.xml.sax.helpers.*;
public class MyObServlet extends HttpServlet{
   // Host and port of the web server for the Identity System
   static String hostname = "localhost";
   static String filename = "c:/temp/um_view.xml"; // NT PATH !
        static int port = 80;
   
   // URL for User Manager
   static String oburl =
         "/identity/oblix/apps/userservcenter/bin/
            userservcenter.cgi"; 
 
   public static String getRequestFromFile(HttpServlet s){
      StringBuffer data = new StringBuffer();
      try      {
               BufferedReader reader = new BufferedReader
                     (new FileReader(filename));
 
               for (String line = reader.readLine(); line != null;
                                line = reader.readLine()){
                  data.append(line);
               }
            } catch (Exception e) {
                        s.getServletContext().log(e.toString());
            }
      return data.toString();
   }
public void doGet(HttpServletRequest req,
                        HttpServletResponse res)
         throws ServletException, IOException {
      try { 
         CookieModule.setCookiePolicyHandler(null);
         // Initiate new HTTP connection to WebPass server
         HTTPConnection con = new HTTPConnection(hostname, port); 
         // Send SOAP message, collect response
         NVPair header[] = new NVPair[1];
         header[0] = new NVPair("Content-Type", "text/xml");
         String rqString = getRequestFromFile(this);
         getServletContext().log("request is: " + rqString);
         HTTPResponse rsp = con.Post(oburl, rqString, header); 
 
         // Check HTTP status and act accordingly
         if (rsp.getStatusCode() >= 300) { 
                   
            getServletContext().log("Received Error:
                  "+rsp.getReasonLine()); 
            getServletContext().log(new String(rsp.getData())); 
                   
         } else {
                   
            // HTTP success
                                                           
               getServletContext().log
                  ("got SOAP result. next is parsing.");
 
            // Create a JAXP SAXParserFactory and configure it
               SAXParserFactory spf =
                     SAXParserFactory.newInstance();
               spf.setValidating(false);
   
               XMLReader xmlReader = null;
               try {
               // Create a JAXP SAXParser
                  SAXParser saxParser = spf.newSAXParser();
           
                  // Get the encapsulated SAX XMLReader
                  xmlReader = saxParser.getXMLReader();
               } catch (Exception ex) {
                     getServletContext().log(ex, ex.toString());
                     System.exit(1);
               }
// Set the ContentHandler of the XMLReader
               // Keep our content handler around to query later
               MyObReader myHandler = new MyObReader();
               xmlReader.setContentHandler(myHandler);    
               // Set an ErrorHandler before parsing
               xmlReader.setErrorHandler
                     (new MyErrorHandler(System.err));    
               try {
               // parse the XML document
                  xmlReader.parse
                        (new InputSource(rsp.getInputStream()));
                  res.setContentType("text/html");
                  PrintWriter out = res.getWriter();   
                  out.println("<HTML>");
                  out.println("<HEAD>");
                  out.println("<TITLE>");
                  out.println("Identity System via Servlet");
                  out.println("</TITLE>");
                  out.println("</HEAD>");   
               // the example assumes an admin has set
               // the email address to a color value instead
                  String emailAddress = myHandler.getEmail();
                  String bgColorAttr = "bgcolor=\"" +
                        emailAddress.trim() + "\"";
                  out.println("<BODY " + bgColorAttr + ">");   
                  out.println("<H1>");
                  out.println("Identity System via Servlet");
                  out.println("</H1>");
                  out.println("<P>");
                  out.println("The e mail address is: "
                        + emailAddress);
                  out.println("</P>");
                  out.println("</BODY>");
                  ut.println("</HTML>");
               }  catch (SAXException se) {
                  getServletContext().log(se, se.getMessage());
                  System.exit(1);
               } catch (IOException ioe) {
                  getServletContext().log(ioe, ioe.getMessage());
                  System.exit(1);
               }       }
         } catch (IOException ioe) { 
            getServletContext().log(ioe, ioe.getMessage()); 
         } catch (ModuleException me) { 
            getServletContext().log(me, "Error handling request: "
            +    me.getMessage()); 
         } catch (Exception e) {
            getServletContext().log(e, e.toString());   }       }
// Error handler to report errors and warnings
   private static class MyErrorHandler implements ErrorHandler {
      /** Error handler output goes here */
      private PrintStream out;
 
      MyErrorHandler(PrintStream out) {
      this.out = out;
      }
 
/**
* Returns a string describing parse exception details
*/
      private String getParseExceptionInfo(SAXParseException spe) {
         String systemId = spe.getSystemId();
         if (systemId == null) {
            systemId = "null";
         }
         String info = "URI=" + systemId +
            " Line=" + spe.getLineNumber() +
         ": " + spe.getMessage();
         return info;
      }
 
// The following methods are standard SAX ErrorHandler methods.
// See SAX documentation for more info.
 
      public void warning(SAXParseException spe)
            throws SAXException {
         out.println("Warning: " + getParseExceptionInfo(spe));
      }
 
      public void error(SAXParseException spe)
            throws SAXException {
         String message = "Error: " + getParseExceptionInfo(spe);
         throw new SAXException(message);
      }
 
      public void fatalError(SAXParseException spe)
            throws SAXException {
         String message = "Fatal Error: " 
               + getParseExceptionInfo(spe);
         throw new SAXException(message);
      }
   }
}

Example 2-22 shows the code for MyObReader.

Example 2-22 MyobServelet.java

/*
* A simple SAX content handler that locates
* an email address in the Identity System
* SOAP response for a User Manager 'view' operation.
* This class extends DefaultHandler provided by JAXP package
* by adding start/end element and character handler methods to
* help in locating the data we are after, and an accessor method
* for our client to extract the data.
*
* Note:
*    This helper class makes assumptions, including
*    its intimate knowledge of the structure of its input.
*    If more than one email address is found, that information
*    is lost. This class is to illustrate the technique.
*    Requirements:
*       JAXP
*/
// APache XML packages
import org.xml.sax.*;
import org.xml.sax.helpers.*;
import java.util.*;
import java.io.*;
public class MyObReader extends DefaultHandler {
   private boolean inEmail = false;
   private boolean inEmailValue = false;
   private String theEmail = "no.email.address.found"; 
   // HANDLERS ///////////////////////////////////////////////
   // parser calls this for each element in a document
   public void startElement(String namespaceURI, String localName,
         String rawName, Attributes atts)
         throws SAXException{
      if (localName.equals("ObEmail")) {
         inEmail = true;
      }
      if (inEmail && localName.equals("ObValue")) {
         inEmailValue = true;      }
   }
   // parser calls this for each element in a document
   public void endElement(String namespaceURI, String localName,
         String rawName)
         throws SAXException{
      // Are we closing an ObEmail?
      if (inEmail && localName.equals("ObEmail")) {
         inEmail = false;
      }       
      // Are we closing an ObEmail/ObValue?
      if (inEmailValue && localName.equals("ObValue")) {
         inEmailValue = false;      }    }
// parser calls this for character content found inside
   // elements.
   // captures characters while inside an ObEmail/ObValue
   public void characters(char[] ch, int start, int length)
         throws SAXException{
      if (!inEmailValue) return;
      theEmail = new String(String.copyValueOf(ch,start,length));
   }
        
   // ACCESSORS /////////////////////////////////////////////////
   public String getEmail() {
      return new String(theEmail);
   }
}

The servlet begins by establishing a connection to the Identity System (using a WebPass on a specified Webserver) using an HTTPConnection object. It then reads in the SOAP message that contains the request shown in the previous example from a file, and uses an HTTPClient object to POST the SOAP message to the server.

WebPass recognizes the request as SOAP message, and passes it on to the Identity System's IdentityXML processing logic interpretation. If the message is validated, the enclosed IdentityXML request is processed. The data resulting from the request and the response code are packaged and transmitted back to the servlet as a SOAP response. After verifying that the request generated a successful response code, the servlet creates and configures a JAXP SAX parser, passing in a custom content handler, MyObReader, which scans the data for the email address attribute.

If the document is successfully parsed, the MyObReader object provides the email address attribute value through its getEmail() method. In this example, it is assumed that the administrator has entered some text like green in the email address field.

The example servlet looks up this information, and uses it in generating the result HTML page. The value is inserted as the BGCOLOR attribute of the BODY tag in the HTML document. The page is returned showing the value in text, and the page background is green.

2.9.3 ObSSOCookie Example

The following example shows how to use Java to post a SOAP request (or make IDXML calls) to the Identity Server when it is protected using the Access System. This example makes use of the obSSOCookie.

Note:

The Access Manager SDK must be installed to create this type of request. See "Installing the Access Manager SDK" for details

Example 2-23 illustrates a SOAP request that uses the obSSOCookie.

Example 2-23 SOAP Request Using the obSSOCookie

/**
 * This is a very simple SOAP example of how to invoke Oracle Access Manager
 * through SOAP.
 *
 * This program will make a soap request (send the request in soap.xml)
 * to the argument hostname:port/oblix/apps/corpdir/bin/corpdir.cgi
 * In this particular example the Identity server is protected using Basic over LDAP and the
 * ObUserSession class is used to retrieve the token which is used to set the ObSSOCookie.
 * You might also need to pass the IP adress to the ObUserSession or turnoff IPValidation for the
 * Webgate in Netpoint\WebGate\access\oblix\apps\webgate\WebGateStatic.lst.
 *
 *
 * Requirements:
 * *** HTTPClient, a complete http client library from innovation, is
 *     required to run this test.  The software is free, and licensed under the
 *     GNU Lesser General Public License.
 *     HTTPClient is available at http://www.innovation.ch/java/HTTPClient
 *     This program has been tested with HTTPClient Version 0.3-2
 *    ObSoapClientWebGate is written as an AccessGate using the Access Server API's so
 *     you will need to install the Access SDK and do the required configurations to run
 *     this class as an Access Gate.
 *
 * To run:
 * *** java ObSoapClientWebGate [-h hostname] [-p port] [-i <Access SDK install dir>] [-l loginName] [-w password] [-f inputfile] [-u oblixurl]
 *
 */
 
import java.net.*;
import java.io.IOException;
import java.io.FileReader;
import java.io.BufferedReader;
import java.util.*;
import java.io.*;
import java.text.*;
import HTTPClient.*;
import HTTPClient.CookieModule;
import HTTPClient.HTTPConnection;
import HTTPClient.HTTPResponse;
import HTTPClient.ModuleException;
import HTTPClient.NVPair;
import HTTPClient.Cookie;
import com.oblix.access.*;
 
public class ObSoapClientWebGate
{
 
        static String hostname = "host.company.com";
        static String filename = "soap.xml";
        static String accessSDKinstalldir = "";
        static int port = 80;
        static String userName = "";
        static String password = "";
        static String res = "/identity/oblix";
        static String oburl = "/identity/oblix/apps/userservcenter/bin/userservcenter.cgi";
 
 
        public static void collectArgs(String args[])
        {
                for (int i = 0; i < args.length; i++) {
                        if (args[i].equals("-h") && args.length >= i+1)
                                hostname = args[i+1];
                        else if (args[i].equals("-f") && args.length >= i+1)
                                filename = args[i+1];
                        else if (args[i].equals("-p") && args.length >= i+1)
                                port = Integer.parseInt(args[i+1]);
                        else if (args[i].equals("-u") && args.length >= i+1)
                                oburl = args[i+1];
                        else if (args[i].equals("-i") && args.length >= i+1)
                                accessSDKinstalldir = args[i+1];
                        else if (args[i].equals("-l") && args.length >= i+1)
                                userName = args[i+1];
                        else if (args[i].equals("-w") && args.length >= i+1)
                                password = args[i+1];
                        else if (args[i].equals("-help")) {
                                System.out.println("Usage: java ObSoapClientWebGate [-h hostname] [-p port] [-f filename] [-i <Access SDK install dir>] [-l loginName] [-w password] [-u oblixurl] \n");
                                System.exit(1);
                        }
                }
        }
 
        /**
   * Read from soap.xml in current directory and return as string.
         */
        public static String getRequestFromFile()
        {
                StringBuffer data = new StringBuffer();
                try {
                        BufferedReader reader = new BufferedReader(new FileReader(filename));
 
                        for (String line = reader.readLine(); line != null;
                                line = reader.readLine()) {
                                data.append(line);
                        }
                } catch (Exception e) {
                        System.out.println(e.toString());
                }
                System.out.println(data.toString());
                return data.toString();
        }
 
        public static void main(String args[]) throws Exception
        {
                try {
                        CookieModule.setCookiePolicyHandler(null);
                        AuthorizationInfo.setAuthHandler(null);
                        // initiate connection
                        collectArgs(args);
                        HTTPConnection con = new HTTPConnection(hostname, port);
                        // Check if user is authenticated, if yes pass the cookie while posting.
                        String token = null;
                        token = authenticate(userName, password, res);
                        if (token == null) {
                                System.out.println("Authentication failed for User " + userName + " Exiting program");
                                System.exit(1);
                        }
                        System.out.println("TOKEN: " + token);
 
                                Cookie SSOCookie = new Cookie("ObSSOCookie", URLEncoder.encode(token), ".oracle.com", "/", null, false);
                        CookieModule.addCookie(SSOCookie);
                        System.out.println();
 
                        // collect response
                        NVPair header[] = new NVPair[1];
                        header[0] = new NVPair("Content-Type", "text/xml");
                                HTTPResponse rsp = con.Post(oburl,getRequestFromFile(),header);
 
                        // get status and act accordingly
                        if (rsp.getStatusCode() >= 300) {
                                System.err.println("Received Error: "+rsp.getReasonLine());
                                System.err.println(new String(rsp.getData()));
                        } else{
                                        System.out.println();
                                        System.out.println();
                                        System.out.println();
                                System.out.println(new String(rsp.getData()));
 
                                                        }
 
 
 
                } catch (IOException ioe) {
                        System.err.println(ioe.toString());
                } catch (ModuleException me) {
                        System.err.println("Error handling request: " + me.getMessage());
                } catch (Exception e) {
                        System.out.println(e.toString());
                }
        }
 
        public static String authenticate(String userName, String password, String res)
        {
                String token = null;
                ObResourceRequest resReq = null;
                ObUserSession user = null;
 
                Hashtable cred = new Hashtable();
                cred.put("userid", userName);
                cred.put("password", password);
                System.out.println("Authenticating user " + userName + " password " + password + " for res " + res);
                try
                {
                        ObConfig.initialize(accessSDKinstalldir); //"D:\\oblix\\install\\panacea\\ois\\identity\\AccessServerSDK"); // put the correct path to your AccessSDK installation here
                        resReq = new ObResourceRequest("HTTP", res, "GET");
                        // check if it is protected, if yes, create a user session
                        if (resReq.isProtected())
                        {
                                System.out.println("is protected");
                                user = new ObUserSession(resReq, cred, "192.168.1.126");
                                if (user.getStatus() == ObUserSession.LOGGEDIN)
                                {
                                        System.out.println("user status is LOGGEDIN " + user.getStatus());
                                        if(user.isAuthorized(resReq))
                                        {
                                                System.out.println("Permission GRANTED");
                                        }
 
                                        token = user.getSessionToken();
                                }
                        }
                        ObConfig.shutdown();
                }
                catch (ObAccessException oe)
                {
 
                        ObConfig.shutdown();
                        oe.printStackTrace();
                }
                return token;
        }
 
}