Mapping the custom fields to the extended attributes by using the ISPF dialog

The extended attribute definitions in the RACF adapter are managed through the ISPF dialog that was installed as part of installation of the adapter. The adapter uses the mapped fields for generating the RACF commands for provisioning and for reconciliation.

Before you begin

This dialog requires a display that has at least 32 lines. Use a model 3 or model 4 3270 display if possible. You also must have the SPECIAL attribute or at least READ authority to the CSDATA segment by way of field-level access control.

About this task

The ISPF dialog generates and saves a file in the read/write data directory. This file is created so that only the administrator can make updates, and the adapter has read access.

Note: When a new extended attribute is added, the RACF adapter needs to be restarted. Complete these steps to create the adapter file that maps the RACF custom fields to the extended attributes.

Procedure

Log on to TSO on the z/OS operating system.
From ISPF 6 option, run the command EXEC 'hlq.SAGRCENU(AGRCCFG)' to start the ISPF dialog.
The License page is displayed.
Press Enter to display this message on the screen.
```
------------------ ISIM RACF Adapter Customization -------------------
Option ===> Location: 1

Security Identity Manager RACF Adapter

	Initial Customization

		1 Initial Customization
		  If this is a new installation, select this option.

		2 Customize to support RACF custom fields
		  If you have USER CSDATA fields defined, select this option.

		X Exit
```
Note: When you run the dialog, take note of the following considerations:
- You can return to the previous menu at any time by pressing F3 or END on the Menu selection screen.
- If you press F3 on a data entry screen, the values that you entered are not saved.
Tip: You can load previously saved parameters from the initial installation by selecting Initial Customization on the first panel, then Load Default or Saved Variables. This option completes the fields USS Adapter read/write home and RACF z/OS Unix group for the ISIM adapter with values used during the installation.
Select Customize to support RACF custom fields. You must have the SPECIAL attribute or at least READ authority to the CSDATA segment by way of field-level access control.
```
------------------ ISIM RACF Adapter Customization -------------------
Option ===>

	RACF custom field support

	Select the custom fields with an S.
	Type S * on the command line to select all fields.
	Type SAVE on the command line to save the selected fields and
	attribute names to the data directory in the read/write home.

	USS Adapter read/write home
===>
	RACF z/OS Unix group for the ISIM adapter ===>

S 	Field			Type			Max len			Attribute name			Comments
- -------- ---- ------- -------------------------- ------------------
		EMPFLAG	 FLAG	    003				  erracempflag
		EMPHEX	  HEX	     0512	      erracemphex
		EMPROOM	 CHAR	    080				  erracemproom
		EMPSER	  INT	     008				  erracempser
		INT01	   INT	     008				  erracint01
```
This panel lists all fields that are defined in the RACF USER CSDATA segment. The panel shows:
- The data type.
- The maximum value length allowed.
- A generated attribute name that is based on the field name.
USS Adapter read/write home

This parameter must be the read/write home as specified in the Disk location parameters panel during installation. The custom fields and corresponding attribute names that are selected are written to the UDF.dat file in the data directory of the read/write home.

RACF z/OS Unix group for the ISIM adapter

This parameter must be the group for the adapter as specified in the Adapter-specific parameters panel during installation. It is used to give the adapter read access to the UDF.dat file.

Attribute name

Attribute names are required for selected fields. The attribute names are modifiable. The attribute names must be unique and must not contain the characters '$', '*' or '-'. If the attribute names contain any of those characters, the adapter profile cannot be imported correctly. The generated default attribute names might need to be modified to remove any disallowed characters. The maximum length for an attribute name is 31 characters. The attribute name is converted to lowercase.
If the data directory in the USS Adapter read/write home directory already contains an UDF.dat file, then the fields that are defined in this UDF.dat file are pre-selected in the list of custom fields.
```
------------------ ISIM RACF Adapter Customization -------------------
Option ===>
	RACF custom field support

	Select the custom fields with an S.
	Type S * on the command line to select all fields.
	Type SAVE on the command line to save the selected fields and
	attribute names to the data directory in the read/write home.

	USS Adapter read/write home
		===> /var/ibm/security/isimracf
	RACF z/OS Unix group for the ISIM adapter ===> OMVS

S 	Field			Type			Max len			Attribute name			Comments
- -------- ---- ------- -------------------------- ------------------
S 	EMPFLAG   FLAG	   003	        erracempflag	     Defined in UDF.dat
S 	EMPHEX    HEX	    0512	       erracemphex	      Defined in UDF.dat
S 	EMPROOM   CHAR	   080	        erracemproom	     Defined in UDF.dat
S 	EMPSER    INT	    008	        erracempser	      Defined in UDF.dat
	  INT01     INT	    008	        erracint01
```
You might see the following in the comments column:

Invalid attribute name

You selected a field and the attribute name contains characters that are not valid. The attribute name must be corrected before it can be saved.

Length discrepancy

The maximum length for the custom field that is saved in the UDF.dat does not match the maximum length for that field in the USER CSDATA segment.

This error might occur if the USER CSDATA segment is updated after the UDF.dat file was created. The maximum length value displayed is the value from the USER CSDATA segment.

If the UDF.dat file is saved, the USER CSDATA segment value is the value that is saved. If you change the length of one or more fields in the USER CSDATA segment, optionally, save the UDF.dat file to avoid this error.

Defined in UDF.dat

Indicates that the custom field is in the current UDF.dat file in the specified read/write home directory.
Type S in the selection column to select any additional custom fields you want to support.
If you want to remove a field that is defined in the UDF.dat, remove the S from the selection column. You can page up and down if necessary. The selections are maintained. If you want to select all custom fields, type S* on the command line.
When you are finished selecting the custom fields, type SAVE on the command line. The UDF.dat file is saved with read and write permissions for the administrator and read permission for the group for the adapter specified.
Note: The administrator is the user who is selecting and saving the custom fields to be supported.

Results

The next time that the RACF adapter is cycled, it picks up the extended attributes. See the following sections for information about how to update and import the RACF Adapter profile. Importing the profile makes the new attribute definitions available to the IBM® Security Privileged Identity Manager server.