Adding custom attributes

ServiceNow support custom fields for user object. The adapters supports only the standard set of attributes but you can customize the adapter to support custom attributes.

Procedure

  1. Copy the adapter profile JAR file and extract the files.
    1. Download the adapter package from the IBM® Passport Advantage® website.
    2. Copy the ServiceNowProfile.jar file, which is included in the adapter package, into a temporary directory.
    3. Run the following command to extract the contents of the ServiceNowProfile.jar file: 
      cd c:\temp
jar -xvf ServiceNowProfile.jar

      The jar command creates the c:\temp\ServiceNowProfile directory.

      The JAR file contains a ServiceNowProfile folder with the following files:
      • CustomLabels.properties
      • erServiceNowAccount.xml
      • erServiceNowService.xml
      • schema.dsml
      • service.def
      • servicenowAL.xml
  2. Update the schema.dsml file, which identifies all of the standard user account attributes. Modify the file to identify new custom attributes.
    1. Open schema.dsml in a text editor.
    2. Add the custom attribute at the end of attributes.
      For example:
      <attribute-type single-value="true">
<name>erServiceNowCustomAttribute</name>
<object-identifier>1.3.6.1.4.1.6054.3.177.2.1001</object-identifier>
<syntax>1.3.6.1.4.1.1466.115.121.1.15</syntax>
</attribute-type>
      Note:
      • In the attribute-type, use single-value to indicate whether the attribute is single-value or multi-value.
      • The attribute name must start with a prefix erServiceNow to easily identify the attributes that are used with IBM® Security Privileged Identity Manager.
      • The Object Identifier (OID) is increased by 1. Start a new range of number for custom attribute to avoid OID conflicts with future version of adapters. For example, you can start your attribute OID from 1.3.6.1.4.1.6054.3.177.2.1000, so the first attribute OID is 1.3.6.1.4.1.6054.3.177.2.1001. An error message is displayed if there is any conflict in the OID.
    3. If the custom field references another table, define the field as supporting data.
      Verify the page URL to determine what the custom field references from the ServiceNow UI. For example, https://XXX.service-now.com/cmn_department_list.do?sysparm_target=sys_user.department&sysparm_target_value=1231342432&sysparm_nameofstack=reflist&sysparm_clear_stack=true&sysparm_element=department&sysparm_reference=cmn_department&sysparm_view=sys_ref_list&sysparm_additional_qual=&sysparm_dependent=&sysparm_domain_restore=false
      Note:

      The referenced table is shown as sysparm_reference=cmn_department. The value for department is referring to the SYSID in cmn_department, and displays the Name from cmn_department.

      There must be an attribute erServiceNowDepartment in erServiceNowAccount object class to represent the Department Field on ServiceNow. The adapter also needs an object class to store the SYSID and Name in LDAP. For example, the object class for the department supporting data in the adapter:
      <class superior="top">
<name>erServiceNowDepartmentClass</name>
<description>Department supporting data</description>
<object-identifier>1.3.6.1.4.1.6054.3.177.1.5</object-identifier>
<attribute ref="erServiceNowDepartmentSysID" required="true"/>
<attribute ref="erServiceNowDepartmentName" required="false"/>
</class>

      The erServiceNowDepartmentSysID and erServiceNowDepartmentName are referring to the cmn_department table.

      The OID for custom filed object class must start from a new range, preferably from 1.3.6.1.4.1.6054.3.177.1.100 onwards.

  3. Add the attribute and its label in the CustomLabels.properties file to show the correct label on Adapter account form.
    Use the format attribute=label.
    Note: The attribute name must be in lowercase. For example: erservicenowcustomattribute=Custom Field One
  4. Modify the assembly lines to add new mappings for the custom attributes. The Assembly Lines in servicenowAl.xml contain mapping instructions from IBM Security Privileged Identity Manager request to ServiceNow.
    1. Launch the Security Directory Integrator Configuration Editor.
    2. Select File > Open Security Directory Integrator Configuration File to open the servicenowAL.xml.
    3. Select snAdd > addUser, which contains the mapping for the Add user operation.
    4. In the OutputMap, add the name of the custom field exactly as the API Name on ServiceNow.
    5. Change the default value of work.[custom field name] to work.[custom attribute name]. For example. work.u_custom_field to work.erServiceNowCustomAttribute.
    6. Add the attribute to snModify > Output Map.
    7. Add the attribute to snRecon. Select searchUser and add the custom attribute.
    8. In the Input Map, set Work Attribute as erServiceNowCustomAttribute and Assignment as conn.u_custom_field.
    9. For attribute with supporting data, such as erServiceNowDepartment:
      • Set the Assignment in searchUser's Input Map as conn.departmentValue.
      • In the Override GetNext, search for 
        if(usersList[currentUser].department)
{usersList[currentUser].departmentValue 
= usersList[currentUser].department.value; }
      • Add the custom attribute. This piece of script is to retrieve the department.value, which is the SYSID.
      • Assign it to departmentValue which is used in the Input mapping.
      • In the searchChoice, add the Input Map for supporting data attributes: 
        erServiceNowDepartmentName maps to conn.erServiceNowDepartmentName, 
erServiceNowDepartmentSysID maps to conn.erServiceNowDepartmentSysID
      • In After Initialize, add the following line for your custom attribute: 
        addToChoiceMap(supporting data object class anme, titleName, 
attribute name, attribute SYSID, url for the table supporting data referred to)
        For example, the code for department is: 
        addToChoiceMap(“erServiceNowDepartmentClass”,”name”,”erServiceNowDepartmentName”,
“erServiceNowDepartmentSysID”,”/api/now/v1/table/cmn_department”)
    10. Save and export back to servicenowAL.xml.
  5. Create a JAR file and install the new adapter profile.
    1. Create a JAR file using the files in the \temp directory. Run the following commands: 
      cd c:\temp
jar -cvf ServiceNowProfile.jar ServiceNowProfile
    2. Import the ServiceNowProfile.jar file into the IBM Security Identity server.
    3. Restart the dispatcher.
      Note: See the LDAP and trace logs if there is a problem loading the profile.
  6. Modify the adapter form to view or edit the new custom attribute. Otherwise, the attribute is not displayed even if the Assembly Lines work.

    You can set the attribute value type according to the field type on ServiceNow.

    For attribute with supporting data, set the type to DropDown Box. The filter must have Attribute as the Name or Label in the supporting data. The Source is the SYSID, and Filter is objectclass equals supporting data object class. For example:
    Attribute: erservicenowdepartmentname
Source Attribute: erservicenowdepartmentsysid
Filter:(objectclass=erservicenowdepartmentclass)

    For more information about modifying account form, see the IBM Security Identity Manager product documentation.