Variables

Pre-defined Variables

Custom Variables

Using Variables in Dynamic Resources

Using Variables in Dynamic Roles

A COGNITUM application may contain variables instantiated on each user session. These variables may be used in the definition of resources, links and roles making them dynamic, as documented in “Using variables in dynamic resources” and “Using variables in dynamic roles”. They can also be used in links as described in “Configuring or modifying a link”.

In the COGNITUM Console, a variable is defined by a name and an evaluation factor. COGNITUM manages two types of variables:

• Pre-defined variables: $userDN, $userRDN, $userRDNValue, $login
• Custom variables defined by the application designer

Pre-defined Variables

In COGNITUM, some pre-defined variables are available. They are automatically evaluated each time a session is created:

• $userDN is the Distinguished Name (dn) of the connected user. When the data source is a relational database, the identification request must be set, otherwise it retrieves the user login.
• $userRDN is the Relative Distinguished Name (rdn) of the connected user. This variable is not available for relational databases.
• $userRDNValue is the value of the Relative Distinguished Name of the connected user. This variable is not available for relational databases.
• $login is the login value when connecting to COGNITUM, for example aborel or "uid=aborel, ou=group, o=company.com".
• $datasource::suffix returns the data source suffix (LDAP only).

For example, a user named John Doe connects a COGNITUM application. He is identified in the directory with the following dn:

cn=John Doe, ou=Marketing, o=mycompany, c=US

It is assumed that the user concept is brought about in this application through the Users resource.

The related variables for this user are:

• $userDN="cn=John Doe, ou=Marketing, o=mycompany, c=US"
• $userRDN="cn=John Doe"
• $userRDNValue="John Doe"
• $login=jdoewhen using the uid as the login attribute

COGNITUM also supports the following $userDN syntax:

• $(resourcename)userDN.[attribute] is the value of the attribute of the directory entry of the connected user.
• $userDN.up(n) is the dn of the parent entry n levels above the directory entry of the connected user.
• $(resourcename)userDN.[attribute].up(n) may also be used when the attribute is a DN itself.

For example, the features of the user John Doe are as follows:

• dn: "cn=John Doe, ou=Marketing, o=mycompany, c=US"
• cn: "John Doe"
• mail: "[email protected]" ■ ou: "Marketing"
• manager: "cn=John Smith, ou=Marketing, o=mycompany, c=US"

The related $userDN syntaxes are:

• $(Users)[email protected]
• $(Users)userDN.manager="cn=John Smith, ou=Marketing, o=mycompany, c=US"
• $(Users)userDN.manager.cn="John Smith"
• $userDN.up(1)="ou=Marketing, o=mycompany, c=US"
• $userDN.up(2)="o=mycompany, c=US"
• $(Users)userDN.manager.up(1)="ou=Marketing, o=mycompany, c=US"

For example, the data LDAP data source is defined with the suffix o=itc.com.

• $datata::suffix="o=itc.com"

Custom Variables

Although pre-defined variables cover most scenarios, COGNITUM makes it possible for the designers to specify their own variables. Typically custom variables are required when pre-defined variables cannot produce the required results.

Variables can be created in Java.

Creating a custom variable

Designers can define custom variables in the COGNITUM Console through a wizard. In order to open the New Variable wizard, the New Variable command must be chosen. It is accessible with a click on the cogwheel-like toolbar button.

Figure: New custom variable definition

Application: This is the application which the variable is bound to. When available, a click on the list box makes it possible to select another application.

Name: It is the label of the variable. The name should be intuitive enough to be easily recognized by the application designers in the COGNITUM Console. Non-alphanumerical characters and blank spaces are prohibited.

A click on the Next button displays the Variable Code screen.

Figure: New custom variable code configuration

Java Class: This is the Java class defining the variable role. A click on the torch button makes it possible to select and load another Java class.

Default Class Name: A click on the button fills in the Java Class box with its default name.

Generate the Source File: Selecting this check box allows to create a pattern program displaying the name of the methods to be used, the specific location of the values to be entered and comments. The file is created in the folder

COGNITUM-root/Server/webapps/application/WEB-INF/dc/variables/classes/cdm/custom/variable/

A click on the Finish button creates the variable.

To create a variable in Java

1. In the COGNITUM Console tree, select the Variables item and click the New Variable toolbar button.
2. In the Application box, you can choose the application which you want the new variable to be applied to.
3. Enter the label of the variable in the Name box.
4. Click the Next button.
5. In the Java Class box enter the name of the Java class to be used to define the variable role, or click the torch button to select a Java class.
6. Click the Default Class Name to populate the Java Class box with the default name.
7. Check the Generate the Source File to write the class file in the folder COGNITUM-root/Server/webapps/application/WEB-INF/dc/variables/classes/cdm/custom/variable/
8. Click Finish.

Copying a custom variable

A custom variable created and configured for an application can be duplicated into the same application, or into another application. This feature allows to bypass the complete variable creation process.

The Copy command is accessible from a selected variable from its context menu or from the Edit menu.

The target Variables item must be selected before choosing the Paste command from the context menu or from the Edit menu. When the variable is duplicated within the same application, a message box pops up to give another name for the duplicate.

Parameter changes may prove necessary. See “Modifying a custom variable”.

To copy a variable

1. In the COGNITUM Console tree, select the variable to copy.
2. Choose the Copy command from the context menu.
3. Select the target Variables item.
4. Choose the Paste command from the context menu.
5. Update the parameters of the variable duplicate as required.

Testing a custom variable

Once a custom variable is created through the New Variable wizard, COGNITUM makes it possible to test its accuracy and consistency in the Variable Test area of the Variable property view.

Figure: Testing a custom variable

DN: It is the DN with which the variable is tested when necessary. The torch button allows the application designer to search from a list of available DNs in the directory. With the Base DN and filter entered in the Search for the DN of a user box, the Search button displays the list of the available accounts and DNs. The selected cn/dn completes the DN box in the Variable property view.

Password: It is the password associated with the specified DN.

Test: A click on this button checks that the account DN and password are correct before testing the variable itself. A message box pops up to tell the result of the account test.

Test Code: A click on this button launches the test on the variable with the account entered above.

Results: In this area, the result of the test is displayed when the variable responds properly. When the variable is wrong, a warning box pops up and gives access to details on the spotted error.

To test a custom Java variable

1. In the COGNITUM Console tree, select the Java variable you want to test.
2. In the Properties tab, specify an account in the DN and Password boxes when required to test the variable. Check it with the Test button.
3. Click Test Code.

4. When the variable responds:

5. properly, the Result area displays the returned values,

6. inaccurately, a warning box pops up and gives access to information on the faulty variable.

Modifying a custom variable

A custom variable can be modified at any time:

• Once a variable is added to the tree. Its parameters can still be modified or reset.
• To update an existing or duplicated variable.

When a variable is selected in the COGNITUM Console tree, the Properties tab is displayed.

Choosing a variable in the COGNITUM Console tree displays its property view. The variable can be modified in the Variable Definition and Associated Java Class areas.

Figure: Custom variable properties

Name: The label of the variable can be changed provided it does not contain non-alphanumerical characters or blank spaces.

Java Class: This is the Java class defining the variable behavior. A click on the torch-like button opens up the Choose the Java Class dialog box.

Figure: Choose the Java Class box

Java Class: In the Choose the Java Class dialog box, a click on the torch button allows to select another Java class.

Default Class Name: A click on this button fills in the Java Class box with its default name.

Generate the Source File: This check box is displayed when the source file has not been generated previously. Selecting the check box allows to create a pattern program displaying the name of the methods to be used, the specific location of the values to be entered and comments. The file is created in the folder

COGNITUM-root/Server/webapps/application/WEB-INF/conf/variables

A click on OK validates the new Java class selection. The Choose the Java Class dialog box is closed.

Edit: In the Properties property view of the variable, a click on this button opens up a text editor displaying the Java class code.

Compile: A click on the button compiles the .java file to turn it into a .class file.

The variable can be tested again as described in “Testing a custom variable”. A click on the Apply button validates the parameters.

To modify a custom Java variable

1. In the COGNITUM Console tree, select the variable you want to update in its Properties tab.
2. In the Name box, you can change the label of the variable.
3. To change the class specified in the Java Class box, click the torch button and select another class in the Choose the Java Class dialog box.
4. Click the Edit button to edit the Java class code and modify it.
5. Click the Compile button to compile the .java file.
6. Click Apply to validate any changes brought to the variable.

Deleting a custom variable

COGNITUM makes it possible to delete a variable easily and safely. The Delete command is accessible from a selected variable context menu.

The Delete Variable message box pops up, as the variable may well be used in the definition of a resource, a role or a link. Clicking Yes launches the deletion.

A second confirmation box may be displayed. Clicking Yes confirms the deletion. COGNITUM automatically updates the variables list.

To delete a variable

1. In the COGNITUM Console tree or property view, click the variable you want to delete.
2. Choose Delete from the context menu.
3. Validate the removal in the warning boxes.

Using Variables in Dynamic Resources

Resources are necessary to browse and search directory data. A resource is defined by the filter on the accessed data source, whether LDAP or RDBMS, as described in Chapter 4, “Resources”.

A variable can be used in the definition or the context of a resource. The resource is dynamic when it includes an item relative to the connected user. Instances of dynamic resources can be:

• My Card,
• People in My Department,
• Groups I am a member of,
• My Security Administrator,
• Users In My Country.

A variable is specified in the Definition tab of a selected resource property view.

Figure: Setting variables in dynamic resources

A variable of a resource definition always begins with the $ prefix in the Filter box.

For example, with an LDAP data source, the properties of a dynamic resource instance can take the following format:

• MyCard resource:
• Base: $userDN
• Filter: (objectclass=inetOrgPerson)
• Scope: Object
• PeopleInMyDepartment resource:
• Base: $userDN.up(1)
• Filter: (objectclass=inetOrgPerson)
• Scope: One Level
• MyGroups resource:
• Base: ou=groups, o=mycompany, c=US
• Filter:(&(objectclass=groupofUniqueNames)(uniqueMember=$ userDN))
• Scope: Sub Tree
• MySecurityAdministrator resource (provided the security_zone object has an administrator object including the dn of the security administrator):
• Base: $security_zone.administrator
• Filter: (objectclass=inetOrgPerson)
• Scope: Object
• UsersInMyCountry resource:
• Base: $userDN.country
• Filter: (objectclass=inetOrgPerson)
• Scope: Sub Tree

Using Variables in Dynamic Roles

A dynamic role is a set of users that comply with a specified LDAP or SQL query. The query may include a variable. When a user connects an application, COGNITUM evaluates the user against the available roles using the query defined for the dynamic role. When the directory responds positively, the user is authenticated as a member of the dynamic role, and inherits the rights of the role. For more information about roles in COGNITUM, see “

Roles

”.

The Dynamic Role property view is necessary to make a role dynamic with a variable.

A variable is specified in the Definition tab of the property view of a selected dynamic role.

Figure: Setting variables in dynamic roles

The variable is part of the request and entered in the Filter box.

For example, with an LDAP data source, a dynamic role can be Secretary standing for a virtual group of users whose title attribute would be secretary.

The Secretary role could be defined as:

• Base: $userDN
• Filter: (title=secretary)
• Scope: Object

To be useful, the definition of the role (baseDN in filter) must contain at least one variable, the value of which changes according to the logged-in user—for example $userDN, $login, and so on.

Another dynamic role example could be an Administrator dynamic role. A user would belong to the role when he/she is a member of one of the groups below "ou=groups, o=mycompany, c=US" the name of which starts with admin. The Administrator role could be defined in the property view as:

• Base: ou=groups, o=mycompany, c=US
• Filter: (&(cn=admin*)(uniquemember=$userDN))
• Scope: One Level