Managing the Need to Know Component

B Managing the Need to Know Component

This appendix provides information on how to install and configure the Need to Know (NTK or NtkDocDisclosure) component for Content Server. It also describes how to use the component to customize Content Server security areas including user access to content, search results, user credentials, behavior of metadata changes, and use of WHERE clause in searches.

This appendix covers the following topics:

B.1 Introduction

The Need to Know (NtkDocDisclosure or NTK) component supports customization for these Content Server security areas:

Content security: Changing user access to content items.
Search results: Modifying the display of search results.
Hit list roles: Changing user credentials for query and check-in pages.
Content metadata security: Altering the behavior of metadata changes for content items.
WHERE clause calculation: Modifying use of the WHERE clause in searches.

For example, with standard security, users can only view content for which they have at least Read permission. The Need to Know component can change this in two ways:

All users can be allowed to see content items from specified security groups in a search results list, even though they may not be able to view the metadata or document itself.
Read and Write permission can be expanded or restricted within specified security groups using a query against content metadata and user attributes.

The Need to Know component provides a HTML administration interface to display security configuration status information, enable editing of security configuration values, and enable viewing and testing of Idoc Script for security configuration values.

B.1.1 Features

The Need to Know component is implemented through the following features:

The Need to Know component is applied by security group. You must identify which security groups will use the component. All content in the specified security groups will appear in the search results for all users.
The component provides the option of making all accounts visible, so a user can get a search hit on a content item regardless of its account.
The Security Group list on the Search page will show all specified security groups. If accounts are enabled, all accounts will appear in the Accounts list on the Search page.
A new DocDisclosureQuery metadata field and new hit list role must be created to support the Need to Know function. The hit list role is given read access to all specified security groups.
You can create new user attribute fields or use existing ones in Need to Know queries.
When a document is checked in, a query can be defined in the DocDisclosureQuery metadata field. The query conditions can include content metadata and user attributes, and the query results determine access permission to the document. Queries can be entered manually in Idoc Script, or the Disclosure Query Security applet can be used to build the query.
Whenever a user does a search, the hit list role is dynamically applied to the user, giving them read access to all content in the specified security groups. Each content item is then checked for a query in the DocDisclosureQuery field, which determines the user's access to that content item.
If the DocDisclosureQuery field is empty, standard security applies. Standard security can also be explicitly specified in the query field, or it can be used in a boolean combination with other document and user attributes to expand or refine the read access.
If a query is entered for a content item that is not in a NTK security group, the query does not run, and standard security applies.
If a user already has more than Write or higher access to the security group, the query in the DocDisclosureQuery field does not run, and standard security applies.
A global query can be defined for all content, so individual queries do not have to be specified for each content item. You can set up the system to allow the global query to be overridden when a query is entered during check-in.

B.1.2 Applications

This component can be used as the starting point for a more complicated security implementation, such as:

Providing integrated tracking for downloads of sensitive documents.
Controlling Write or higher privileges through custom logic.
Implementing view limits and subscription control, where documents within a certain security group may only be downloaded so many times.
Controlling access by incorporating entries from a custom database table or results from a custom API. This is a hook for externally controlled authorization.

B.2 Installing the Need to Know Component

Install the component using either the Component Wizard or the command-line ComponentTool.

Topics

B.2.1 Installing the NTK Component with Component Wizard

This procedure describes how to install the Need to Know component using the Component Wizard.

Launch the Component Wizard. For information on using standalone applications, see Running Administration Applications in Standalone Mode.
In the Component Wizard page, choose Options, then Add.
In the Add Component window, select the radio button for Use Existing Component.
Browse to the location where the WebCenter Content shiphome was installed and locate the Need to Know component directory. For example:
MW_HOME\WC_CONTENT_ORACLE_HOME\ucm\cs\idc\components\NeedToKnow
Select the NeedToKnow.hda file and click OK.
Click Enable.

The NTK component is enabled.

B.2.2 Installing the NTK component with ComponentTool

This procedure describes how to install the Need to Know component using the Component Tool.

Run the Component Tool and specify the NeedToKnow.hda file with the following path, using your configuration name and path for WC_CONTENT_ORACLE_HOME:

MW_HOME\WC_CONTENT_ORACLE_HOME\ucm\cs\idc\components\NeedToKnow\NeedToKnow.hda

B.3 Configuring the Need to Know Component

This section describes the procedure to set up a basic security configuration using the Need to Know component. This procedure explains how to set up security configuration variables, a custom metadata field, and a hit list role. After you have set up the basic configuration, you can use the Need to Know component interface to edit, test, and improve the security configuration.

On the Content Server portal, choose Administration, then Admin Server, then General Configuration.
On the General Configuration page, under the Additional Configuration Variables heading, scroll to the bottom of the text area, and add the following code:
```
SpecialAuthGroups=group1,group2,...
```
In the code:
- Replace group1,group2,... with the security groups that will use the Need to Know component.
- Security groups must be entered in lowercase letters.
- Any security groups not listed will have standard security applied.
Note:

Other products such as Oracle WebCenter Content: Records also can use the SpecialAuthGroups configuration variable, so be careful to use unique names for security groups that use the Need to Know component.
If you want to specify content item-level queries, use the Configuration Manager to add a new metadata field. (This is not necessary if you will be using only the global query.) A new metadata field must be added by using the Configuration Manager; it cannot be added from the Need to Know component interface.
- You can use any field name and title you wish, such as DocDisclosureQuery or NeedToKnow.
- The field must be specified as a memo field.
- After adding the field, click Update Database Design, then click Rebuild Search Index.
Note:

If your Content Server instance already has a large amount of content, rebuilding the search index can take a long time (up to a couple of days). Consider rebuilding during system maintenance periods or at times of non-peak system usage.
Use the User Admin administration applet to add a hit list role.
- You can use any role name you wish, such as hitlist or NTKrole.
- Give Read access to all the security groups that were specified in the SpecialAuthGroups configuration entry.
- If you want the security groups that were specified in the SpecialAuthGroups configuration entry to be listed on the check-in page or update page, you will need to give Write access to this role.
- You can create two different hit list roles with different names and permissions. One role can be configured with the Need to Know component to be a Query role in a content search, and the other role can be configured with the Need to Know component to be an Update role in content check-ins and updates.
- Do not assign this role to any users. If the hit list role is configured to be a Query or Update role, it is automatically added to the user's attributes.
If you want to set user access permissions that extend the limits of Need to Know security, use the General Configuration page to include extra security configuration settings in the Additional Configuration Variables section. Scroll to the bottom of the text area and enter the configuration settings as necessary.
If you want to add new user attribute fields for use in Need to Know queries, use the User Admin tool to add user attribute fields.
Restart the Content Server instance.

Note:

When the Need to Know component has been installed, certain security configuration values are stored in the IntradocDir/data/needtoknow/ntk_config.hda file. These values can be edited by using the Need to Know administration interface, described in Administration Interface or by directly editing the ntk_config.hda file.

B.4 Using the Need to Know Component

This section covers the following topics:

B.4.1 Security Configuration Customization

The Need to Know component provides additional security configuration support focused on the following areas:

Content Security: Changing user access to content items.
Search Results: Changing the display of search results.
Hit List Roles: Changing user credentials for query and check-in pages.
WHERE Clause Calculation: Changing use of the WHERE clause in searches.
Content Metadata Security: Changing the behavior of metadata changes for content items.

B.4.1.1 Content Security

Standard security uses security roles, groups, and accounts to determine if a user has the appropriate privilege level to access a content item. The Need to Know component enables you to customize the process of determining user privilege. You can use the Need to Know component interface to set configuration fields and create Idoc Script to specify Read, Write, and Delete privilege levels. The Idoc Script also can contain user and content metadata values.

The Need to Know component computes content security uses the following process:

A user clicks a link to view content information.
If the user has the Admin role, standard security is used and the user can view the content.
If the security group of the content item is not a Need to Know authorization group, then standard security is used to evaluate the user's Read request.
If Need to Know security is not enabled at the Read privilege level, then standard security is used to evaluate the user's Read request.
If Need to Know security is not limited at the Read privilege level, and the user has standard security access to the content item, the user is given access to the content.
The Need to Know security Idoc Script (in this case the Read security script) is evaluated.
The Need to Know access flag (in this case, isNTKReadAccess) is evaluated to determine if the user has access to the content. Access is allowed or denied based on the Need to Know access flag.

The Need to Know component also enables you to test security configuration scripts for each access level: Read, Write, and Delete. For a test you can specify a user and a content ID, and you have the option of specifying roles and accounts. These attributes are used in the test instead of the user's actual attributes. For example, you could test Idoc Script using an external user whose attributes may not be accessible. After the test is run, the component reports on whether the user has access to the content item, whether Need to Know security was used, and if Need to Know security was not used then the reason why.

For information on using the Need to Know component interface to configure content security, see the NTK Configuration Information page and the Content Security Configuration Information page. For samples of Idoc Script that can configure content security, see Security Customization Samples.

The following Idoc Script functions can be used in the Script fields to determine content security. See Introduction to the Idoc Script Custom Scripting Language in Developing with Oracle WebCenter Content.

Idoc Script Function	Description
allStrIntersect	Takes two required comma-delimited strings and one optional Boolean flag as parameters. If all values in the second string occur in the first string, the function returns true. If the optional parameter is set to true and the second value is an empty string, the function returns true. By default, the optional parameter is false. The comparison of values in the comma-delimited strings are not case sensitive.
includeNTKDeleteSecurityScript	Evaluates the Delete security script and makes the `isNTKDeleteAccess` variable available for use in the Read or Write security scripts. If this function is used in the Delete security script, it is ignored.
includeNTKReadSecurityScript	Evaluates the Read security script and makes the `isNTKReadAccess` variable available for use in the Write or Delete security scripts. If this function is used in the Read security script, it is ignored.
includeNTKWriteSecurityScript	Evaluates the Write security script and makes the `isNTKWriteAccess` variable available for use in the Read or Delete security scripts. If this function is used in the Write security script, it is ignored.
isDisclosureQuery	Evaluates the query for the disclosure field (if specified) and returns true or false. An optional parameter can be specified to determine if the function should return true or false if the disclosure query is empty. If the disclosure field has not been specified or does not exist, this function always returns false.
isMetaChange	This variable is set if the content security call involves a content update or a check in.
isStrIntersect	Takes two required comma-delimited strings and one optional Boolean flag as parameters. If at least one value in the second string occurs in the first string, the function returns true. If the optional parameter is set to true and the second value is an empty string, the function returns true. By default, the optional parameter is false. The comparison of values in the comma-delimited strings are not case sensitive.
stdSecurityCheck	Checks standard security for the current access level. For example, if the function is in the Read security script, it checks security at the Read access level.

B.4.1.2 Search Results

The Need to Know component enables you to customize the presentation of the search results that are returned from a search query. Two configuration values can be set using the NTK interface: Hidden Fields, and Script.

The Hidden Fields value is a list of fields that can be hidden from view on the Search Results page. The values are set to empty strings. To hide the fields, the field hideFields must be set in the component search results Idoc Script.

Idoc Script controls the presentation of the search results. Idoc Script is evaluated for each row in the search results. A number of fields can be set in script to alter the presentation of search results. To see the list of fields and how to use the Need to Know component interface to customize script for search results presentation, see the Search Results Configuration Information page.

The Need to Know component uses the securityCheck Idoc Script function to determine search results presentation. The securityCheck function checks the security against the current content item (standard security or Need to Know security), depending on the configuration values. The function has an option parameter to determine what access level to check:

1 = Read
2 = Write
4 = Delete
8 = Admin

If no parameter is used with securityCheck, by default it checks the Read access level.

For examples of Idoc Script that can alter search results presentation, see Security Customization Samples.

B.4.1.3 Hit List Roles

Hit list roles enable you to change user credentials for using content Search, Content Check In, and Update pages. Using the User Admin applet, you can add a hit list role with any name you wish. You do not assign the role to a user; when the role is enabled it is automatically added to a user's attributes when doing a search, check in, or update.

When creating a hit list role, you must give Read access to all the security groups that you specify in the SpecialAuthGroups configuration entry. If you want these security groups to be listed on the Content Check In page or Update page, you also need to add Write access to the hit list role.

Using the Need to Know component Hit List Roles Configuration Information page, you can implement hit list roles in two forms: Query and Update. A hit list role used in a query is applied to content searches. A hit list role used in an update is applied to content check-ins and updates.

For more information about how to use hit list roles, see the NTK Configuration Information page and the Hit List Roles Configuration Information page. For samples of using hit list roles, see Security Customization Samples.

B.4.1.4 WHERE Clause Calculation

The Need to Know component provides two filters that enable you to customize the query WHERE clause that is used to retrieve search results:

preDetermineWhereClause: Overrides the entire WHERE clause.
postDetermineWhereClause: Appends to the standard security WHERE clause.

The code for these filters is located in the NTKFilter Java class. For samples of how these filters work, see Security Customization Samples.

B.4.1.5 Content Metadata Security

The Need to Know component provides a filter called checkMetaChangeSecurity that enables you to alter the behavior of metadata changes when a content item is checked in or updated.

The code for this filter is located in the NTKFilter Java class. For an example of how the filter works, see Security Customization Samples.

B.4.2 Disclosure Query Security Applet

The Disclosure Query Security applet is used to define a query for a particular content item during check-in.

Surrounding text describes disc_query.gif.

To access the applet, click the Update button next to the DocDisclosureQuery field on the Content Check In Form page.

Element	Description
Field	Select a user attribute field to be specified in the query. This list includes User Locale, User Name, User Role, and all of your custom user attribute fields.
Operator	Select an operator to apply to the Field and Value. The following operators are used for all fields except User Role: Is: The value in the specified Field matches the specified Value. Is Not: The value in the specified Field does not match the specified Value. Begins With: The value in the specified Field starts with the specified Value. Contains: The value in the specified Field contains the specified Value. The User Role field has only one operator, Has Member, and displays a drop-down list of roles in the Value field.
Value	Enter the value to be specified in the query. If an option list was specified for the selected field, choose the value from the drop-down list. If no option list was specified for the selected field, type the value in the text box.
Add	Enters the query specified by the Field, Operator, and Value fields into the Query Expression text box. Each click of the Add button appends the current settings to the query as an AND clause.
Update	Updates a selected query clause with the parameters specified in the Field, Operator, and Value fields
Merge	Creates an OR clause (inserts a pipe character) for the selected query clause. This button is enabled under the following conditions: The Field in the drop-down list matches the Field specified in the selected query clause. The Operator in the selected query clause cannot be "Is Not". The Operator in the drop-down list cannot be "Is Not". Note: The pipe character does not appear in the Query Expression for a User Roles query clause, but it will appear in the DocDisclosureQuery field.
Query Expression	Displays each clause of the query as a single line.
Delete	Deletes the selected query clause.
Append	Appends the Query Expression to any existing query in the DocDisclosureQuery field on the Content Check In Form page.
Replace	Replaces any existing query in the DocDisclosureQuery field on the Content Check In Form page with the Query Expression.
Cancel	Closes the Disclosure Query Security applet without applying any query changes.

B.4.3 Query Syntax

The Disclosure Security Query applet creates queries with the correct Idoc Script syntax, but you can also enter your own queries directly in the DocDisclosureQuery field. The following Idoc Script syntax is used in disclosure queries:

Note:

You can learn how to correctly format query clauses for direct entry in the DocDisclosureQuery field by experimenting with the Disclosure Query Security Applet.

B.4.3.1 Like Operator

The like operator matches substrings and wildcard strings. Enclose all strings in single quotes.

B.4.3.1.1 Substrings

Use the like operator to match substrings.

B.4.3.1.2 Wildcard Strings

Use wildcard strings to match variable characters and options. Wildcard strings use the syntax

* = Match 0 or more characters
? = Match exactly 1 character
| = Separates multiple options, only one of which needs to match

For example, the following code would match "MyClient", "3rd Quarter MyClient Report", "MyClient Visit", "Meeting with MyClient", and "1996 Reports". This string would not match "My Client", "All 1996 Reports", or "1996 Report".

dDocName like '*MyClient*|199? Reports'

B.4.3.2 Boolean Operators

Query clauses can be joined by and, or, and not Boolean operators.

The Boolean operators must be lowercase letters.

Each clause must be in parentheses. For example:

(uRoles like '*:contributor:*') and (uUserLocale like 'hq')

B.4.3.3 UserName Variable

The variable UserName is the name of the user who is currently logged in. For example, the following code would grant privileges only to the users jgreen or hbrown.

UserName like 'jgreen|hbrown'

B.4.3.4 stdSecurity Variable

The variable stdSecurity specifies the standard security model; it is mapped to the stdSecurityCheck Idoc Script function. This variable can be used in Boolean combination with other query clauses to refine access (using the and operator) or expand access (using the or operator). For example, the following code would grant access to the document if the user would normally be able to access the document or they are jgreen or hbrown.

stdSecurity or UserName like 'jgreen|hbrown'

B.4.3.5 User Attribute Fields

When specifying user attribute fields in a query, use the format uFieldName. For example:

uMyUserField like 'Value'

B.4.3.6 User Roles

User roles require a special form because the UserRoles Idoc Script function returns all the roles for the current user in comma delimited form. (In this example, a uRoles shortcut has been defined for this function.) For example, the uRoles value could be:

role1,role2,...,role10

Therefore, to specify a query string that includes the value role1, wildcards must be included so that the query will recognize the value regardless of its position in the role list. For example:

uRoles like '*role1*'

However, this query string would also grant security access to a user with the role role10, which might not be a role you want to include. To limit the uRoles value to only those roles specified in the query, you need to use the DelimitedUserRoles function and syntax, which includes single quotes and colons on each side of the role value as follows:

uRoles like '*:role1:*'

To match either role1 or role2, use this syntax:

uRoles like '*:role1:*|*:role2:*'

B.4.4 Defining a Content-Level Query

To define a query for an individual content item:

Open the Content Check In Form page (for a new content item) or the Info Update Form page (for an existing content item).
Click the Update button next to the DocDisclosureQuery field (the name of this field will be whatever you named it during installation).
In the Disclosure Query Security applet, select a Field, an Operator, and a Value to create a query clause.
- Field: Select from a user attribute list which includes User Locale, User Name, User Role, and all of your custom user attribute fields.
- Operator: Select an operator to apply to the Field and Value. The following operators are used for all fields except User Role:
  - Is: The value in the specified Field matches the specified Value.
  - Is Not: The value in the specified Field does not match the specified Value.
  - Begins With: The value in the specified Field starts with the specified Value.
  - Contains: The value in the specified Field contains the specified Value.
  The User Role field has only one operator, Has Member, and enables a drop-down list of roles in the Value field.
- Value: If an option list was specified for the selected field, choose the value from the drop-down list. If no option list was specified for the selected field, type the value in the text box.
Click Add.

The query clause is added to the Query Expression text box.
Continue building the query:
- To add another query clause with an and operator, enter the values and click Add.
- To change an existing query clause, enter the new values, select the query line you want to change, and click Update.
- To create an or clause, enter the new values, select the query line you want to change, and click Merge.
- To delete a query clause, select the query line and click Delete.
Enter the query expression in the DocDisclosureQuery field.
- To replace the existing query in the DocDisclosureQuery field with the query expression in the applet, click Replace.
- To append the query expression in the applet to the existing query in the DocDisclosureQuery field, click Append.
The Disclosure Query Security applet converts the query clauses to the appropriate syntax for the query and enters the query in the DocDisclosureQuery field on the Content Check In Form or Info Update Form page.

Note:

You can learn how to correctly format query clauses for direct entry in the DocDisclosureQuery field by experimenting with the Disclosure Query Security applet.
After filling out the rest of the fields, click Check In or Update.

The disclosure query is validated, and if the query is ill-formed, an error message tells you the specific problem with the query.

B.5 Administration Interface

After the Need to Know component has been installed, the NTK Configuration Information link is available through the Administration tray or menu. This link provides access to the NTK Configuration Information page, which provides security configuration status information and the capability to edit the security configuration.

The Need to Know component provides the following configuration pages:

B.5.1 NTK Configuration Information Page

The NTK Configuration Information page provides information about Need to Know content security configuration, search results configuration, and hit list roles configuration. This page also enables you to edit the security configuration, edit the search results configuration, edit the hit list roles configuration, view Idoc Script and hidden fields for the configuration, and test Idoc Script.

The surrounding text describes ntkconfall.gif.

To access this page, from the main menu choose Administration, then NTK Configuration Information.

Element	Description
Access Level	Displays the permission levels (Read, Write, Delete) for access to content items.
Enabled	Indicates whether Need to Know security is enabled for Read, Write, or Delete access. No: Need to Know security is disabled for the access level. This is the default. Yes: Need to Know security is enabled for the access level.
Limit Access	Specifies whether Read, Write, and Delete access is limited by Need to Know security. If Need to Know security is used to limit user access, it does so regardless of whether the user has standard Read, Write, or Delete access to a content item. If Need to Know security is not used to limit user access, the user has standard access to a content item. This feature enables you to create a security model more restrictive than the standard security model. No: Access is not limited by Need to Know security. This is the default Yes: Access is limited by Need to Know security.
Script	Provides links to view or test Idoc Script that is evaluated to determine if a user has Read, Write, or Delete access to a content item. The Need to Know component uses one of three parameters as a flag to determine if access is given: Read access: isNTKReadAccess Write access: isNTKWriteAccess Delete access: isNTKDeleteAccess Click View in the row for the access level for which you want to view the Idoc Script that the Need to Know component evaluates to determine if a user has Read, Write, or Delete access. Click Test in the row for the access level for which you want to test the Need to Know security configuration. The NTK Test Content Security page appears. You can use this page to create and run a test of Idoc Script for security configuration. For more information, see Test NTK Content Security Page.
Disclosure Field	Displays the custom metadata field that is evaluated for the Idoc Script function `isDisclosureQuery`. The disclosure field can be used to create a content-specific query. The default value is `<none>`. Use the Configuration Manager to create this field, and make it a memo field type. For more information, see Installing the Need To Know Component and Configuring the Need to Know Component. When the disclosure field exists, an Update button appears next to the field where it appears on the Content Check In Form page. Click the button to access the Disclosure Query Security Applet (see Disclosure Query Security Applet). The applet helps you create queries based on the user metadata.
Security Auth Groups	Displays a list of security groups for which Need to Know security is used. The groups must be a subset of the `SpecialAuthGroups` configuration variable. If no groups are selected, all `SpecialAuthGroups` are used. The default value for `SpecialAuthGroups` is `<All Special Auth Groups>`. Use the Configuration Manager to specify a `SpecialAuthGroups` value in the `config.cfg` file. For more information, see Installing the Need To Know Component and Configuring the Need to Know Component.
Debug	Displays the status of the debugging option. Yes: Debugging information is written to a log file for any security check that occurs for a content item. Users with the administrator role are not logged because they always receive access to the content item. No: Debugging information is not written to a log file.
Edit (Content Security Integration Information)	Displays the Content Security Configuration Information page, where the content security configuration can be changed
Hidden Fields	Click View to display a list of fields that can be hidden on the Search Results page.
Script	Click View to display the Idoc Script that controls the presentation of the Search Results page.
Edit (Search Results Configuration Information)	Displays the Search Results Configuration Information page, where the search results security configuration can be changed.
Query Role	Displays the name of the query role, or `<none>`. This role is applied on the Search query page.
Update Role	Displays the name of the update role, or `<none>`. This role is applied on a content check-in or update page.
Allow Hit List Role for Anonymous Users	Applies the hit list role for anonymous users. No: The hit list role is not applied for anonymous users. This is the default value. Yes: The hit list role is applied for anonymous users.
Edit (Hit List Roles Configuration Information)	Displays the Hit List Roles Configuration Information page, where the hit list roles security configuration can be changed.

B.5.2 Content Security Configuration Information Page

The Content Security Configuration Information page enables you to change security and access configuration for Read, Write, Delete, and other options for the Need to Know component.

To access this page, click Edit in the Content Security Configuration Information area of the NTK Configuration Information page.

Element	Description
Read Options: Use Security	Use security as specified in the Script field. No: Do not use Need to Know content security. This is the default value. Yes: Use Need to Know content security.
Read Options: Limit Access	Limit access permissions as specified in the Script field. No: Do not limit access permissions. This is the default value. Yes: Limit access permissions.
Read Options: Script	Enter Idoc Script in this field to specify the Need do Know security configuration for Read permission.
Write Options: Use Security	Use security as specified in the Script field. No: Do not use Need to Know content security. This is the default value. Yes: Use Need to Know content security.
Write Options: Limit Access	Limit access permissions as specified in the Script field. No: Do not limit access permissions. This is the default value. Yes: Limit access permissions.
Write Options: Script	Enter Idoc Script in this field to specify the Need to Know security configuration for Write permission.
Delete Options: Use Security	Use security as specified in the Script field. No: Do not use Need to Know content security. This is the default value. Yes: Use Need to Know content security.
Delete Options: Limit Access	Limit access permissions as specified in the Script field. No: Do not limit access permissions. This is the default value. Yes: Limit access permissions.
Delete Options: Script	Enter Idoc Script in this field to specify the Need to Know security configuration for Delete permission.
Other Options: Disclosure Field	Select the name of a disclosure field from the list. This field is used to configure security in a content-specific query. Note: If you create a metadata field for content item-level queries using the Configuration Manager, that field will appear as an option in the list.
Other Options: Security Auth Groups	Enter the `SpecialAuthGroups` to be used in content-specific queries. If you use the General Configuration page to create a specific security group for the Need to Know component, you can specify the group here. If you need to add a security group, you can also edit the Additional Configuration Variables `SpecialAuthGroups` value in the `config.cfg` file.
Other Options: All Auth Groups	Specifies that the Need to Know component use all `SpecialAuthGroups` instead of a specific group listed in the Security Auth Groups field. This check box is selected by default. Note: Other products such as Records Management can also use the `SpecialAuthGroups` variable. Be careful to specify only the security groups you want to use the Need to Know security configuration.
Other Options: Debug	Select whether to use debugging to view security checking for a content item. Yes: Debugging information is written to a log file for any security check that occurs for a content item. Users with the administrator role are not logged because they always receive access to the content item. When debugging is used, two additional options are visible: View and Clear. Click View to view the log file of debugging information. Click Clear to empty the log file of information. No: Debugging is not used and information is not written to a log file. This is the default value.
Update	Updates the content security information to use the new settings, restarts the Content Server instance, and returns you to the NTK Configuration Information page.
Reset	Returns the Content Security configuration settings to their last saved values.

B.5.3 Search Results Configuration Information Page

The Search Results Configuration Information page enables you to customize the search results that are returned from a search query. This does not affect what content items are returned, just how the results appear.

Surrounding text describes ntksrconf.gif.

To access this page, click Edit in the Search Results Configuration Information area of the NTK Configuration Information page.

Element	Description
Hidden Fields	Displays the list of fields that are hidden from view in a content search query result. The values are set to empty strings. These fields are hidden if the field hideFields is set in the search results script.
Available Fields	Displays the list of fields that are included in a content search query result.
Add	Select a field name and click Add to move the field from the Available Fields list to the Hidden Fields list, making the field hidden in a content search result.
Remove	Select a field name and click Remove to move the field from the Hidden Fields list to the Available Fields list, making the field visible in a content search result
Script	Enter Idoc Script in this field to control the presentation of search results. The Idoc Script is evaluated for each row in the search results. A number of fields can be set to alter the presentation: docInfo:enabled: Set to 0 to disable the content information link. docInfo:link: Set to alter the content information page link. docInfo:image_small: Set to alter the small image for the information link. docInfo:image_large: Set to alter the large image for the information link. url:enabled: Set to 0 to disable the URL link. url:link: Set to alter the URL link. url:image: Set to alter the image for the URL link. revHistory:enabled: Set to 0 to disable the revision history link. revHistory:link: Set to alter the revision history link. checkout:enabled: Set to 0 to disable to checkout link. checkout:linkF: Set to alter the checkout link. actions:enabled: Set to 0 to disable the actions popup link. checkInSimilar:enabled: Set to 0 to disable the Check In Similar link. email:enabled: Set to 0 to disable the email link. dynConv:enabled: Set to 0 to disable the Dynamic Converter link.
Update	Updates the configuration for search query results, restarts the Content Server instance, and returns you to the NTK Configuration Information page.
Reset	Returns the Search Results configuration settings to their last saved values.

B.5.4 Hit List Roles Configuration Information Page

The Hit List Roles Configuration Information page enables you to configure hit list roles for users.

The surrounding text describes hitlist.gif.

To access this page, click Edit in the Hit List Roles Configuration Information area of the NTK Configuration Information page.

Element	Description
Query Role	Select the hit list role to be applied as the query role when the Search page is used. Security group roles with Read access are displayed in the list of selections, including any security group roles for which the user already has Read access. This role is separate from content security. You could have a content item appear in Search results configured for content security, but the user would not be able to view the Content Information page for that item.
Update Role	Select the hit list role to be applied as the update role when the Update page is used. Security group roles with Write access are displayed in the list of selections, including any security group roles for which the user already has Write access. When the content item is actually checked in or updated, this role is not applied. This field is probably most useful in conjunction with content security. For examples of using this field, see Security Customization Samples.
Allow Hit List Role for Anonymous Users	Applies the hit list roles for anonymous users. No: Do not apply the hit list roles for anonymous users. This is the default value. Yes: Apply the hit list roles for anonymous users.
Update	Updates the hit list configuration, restarts the Content Server instance, and returns you to the NTK Configuration Information page.
Reset	Returns the Hit List Roles configuration settings to their last saved values.

B.5.5 Test NTK Content Security Page

The Test NTK Content Security page enables you to run a test security script for a user.

To access this page, click Test in the Script column for one of the access permission levels displayed on the NTK Configuration Information page.

Element	Description
Access Level	Displays the access level for the permissions level you select to test: Read, Write, or Delete.
Script	Enter Idoc Script for the content security configuration to be tested.
User	Enter the user ID for the test.
Set Attributes	Select the check box to automatically set the user attributes to match the user's existing attributes.
Roles	Enter the roles assigned to the user for the test. Use this field if you are testing with external users where attributes may not be accessible.
Accounts	Enter the accounts assigned to the user for the test. Use this field if you are testing with external users where attributes may not be accessible.
Content ID	Enter the content ID for the test.
Test	Click Test to test the configuration specified on the Test NTK Content Security page. The Need to Know component test returns results on whether the user has the specified access, whether Need to Know security was used, and if Need to Know security was not used then the reason why.
Reset	Returns the Test NTK Content Security configuration settings to their last saved values.

B.6 Security Customization Samples

This section contains samples of security model customization.

B.6.1 Content Security Samples

This section contains samples of content security customization:

B.6.1.1 Simple Idoc Script Function

This sample allows Read access if the user Color custom field and the content Color custom field match.

<$if strEquals(uColor, xColor)$>
<$isNTKReadAccess=1$>
<$endif$>

B.6.1.2 Using stdSecurityCheck

This sample allows Read access if the user Color is Blue and the user has standard security to the content.

<$if stdSecurityCheck() and strEquals(uColor, "Blue")$>
<$isNTKReadAccess=1$>
<$endif$>

B.6.1.3 Using isStrIntersect

This sample returns true because 3 is a member of the first string.

<$if isStrIntersect("1,2,3,4", "5,3")$>
<$isNTKReadAccess=1$>
<$endif$>

This sample returns false because neither 5 or 6 is a member of the first string.

<$if isStrIntersect("1,2,3,4", "5,6")$>
<$isNTKReadAccess=1$>
<$endif$>

This sample returns false because the second string is empty and the third parameter is not specified.

<$if isStrIntersect("1,2,3,4", "")$>
<$isNTKReadAccess=1$>
<$endif$>

This sample returns true because the second string is empty and the third parameter is true.

<$if isStrIntersect("1,2,3,4", "", 1)$>
<$isNTKReadAccess=1$>
<$endif$>

This sample returns false because the second string is empty and the third parameter is false. Note that the third parameter can be a string (for example, "True" or "T") or a number (for example, 1, 0).

<$if isStrIntersect("1,2,3,4", "", 0)$>
<$isNTKReadAccess=1$>
<$endif$>

B.6.1.4 Using allStrIntersect

This sample returns false because 5 is not a member of the first string.

<$if allStrIntersect("1,2,3,4", "5,3")$>
<$isNTKReadAccess=1$>
<$endif$>

This sample returns true because 3 and 4 are members of the first string.

<$if allStrIntersect("1,2,3,4", "3,4")$>
<$isNTKReadAccess=1$>
<$endif$>

The samples in Using isStrIntersect (page 4-2) that use the third parameter would work the same with allStrIntersect.

B.6.1.5 Using includeNTKReadSecurityScript

Read script:

<$if strEquals(dDocType, "Document")$>
<$isNTKReadAccess=1$>
<$endif$>

Write script:

<$includeNTKReadSecurityScript()$>
<$if isNTKReadAccess and strEquals(uColor, "Red")$>
<$isNTKWriteAccess=1$>
<$endif$>

The user has Write access to the content item if they have read access (type is Document) and the user's Color is Red.

B.6.2 Search Result Samples

This section contains samples of search results customization:

B.6.2.1 Disabling Links

This sample disables the URL and Content Information link if the user does not have Read access to the content item. This could be used if you set the query role to show extra content items in the search results, but don't want users to see links to them.

<$if not securityCheck()$><$docInfo:enabled=0$><$url:enabled=0$><$endif$>

B.6.2.2 Changing Links

This sample alters the Content Information and URL link to another service if the Color of the content is Red.

<$if strEquals(xColor, "Red")$><$docInfo:link=HttpCgiPath & "?IdcService=GET_USER_INFO"$><$url:link="javascript:alert('Cannot view content.')"$><$endif$>

B.6.2.3 Changing Images

This sample alters the Content Information link if the Color of the content item is Green.

<$if strEquals(xColor, "Green")$><$docInfo:image_small=HttpImagesRoot & "oracle/tree_icons/historical.gif"$><$endif$>

B.6.3 Hit List Roles Samples

This section contains samples of hit list roles customization:

B.6.3.1 Using the Query Hit List Role

If you set the Query role to be queryRole, and queryRole has Write access to the security group NTKGroup, then NTKGroup will appear in the security group option list. You could then limit what content information appears by customizing the Search Results configuration values

B.6.3.2 Creating a Black Hole Check In

By using the Update role, you could create a scenario where a user could check in a content item and then not be able to view or edit it. You would need to do the following:

Create a role called updateRole that has Read/Write access to the security group NTKGroup.
Update the Write content security script so that if a meta change is occurring and the security group is NTKGroup, allow access.

<$if isMetaChange and strEquals(dSecurityGroup, "NTKGroup")$><$isNTKWriteAccess=1$><$endif$>