Skip to main content
Kinetic Community

Adding a Custom Field to a Retrieve Handler

This solution describes how to add a custom fields to an existing "generic" task handler.

Usage

This solution describes how to add two custom fields, Officer Name and Officer Login ID, to the results returned by the person retrieve handler. The custom fields and handler you need to modify may be different, but the necessary modifications should be the same. There are four steps to take:

  1. Update handler name to include company name or abbreviation
  2. Make sure the search is returning either all fields or a list that includes the customer fields. (init.rb)
  3. Add the custom fields to the returned results in the init.rb
  4. Add the custom fields to the returned results in the node.xml

There are three additional steps that should be done for documenation purposes.

  1. Update the simple_output.xml to include the new results
  2. Update the README to include the new results
  3. Update the CHANGELOG to indicate the updates made

Example

The attached example is a modification of this "generic" handler.

Code Updates

1.  Update handler name to include company name or abbreviation

Rename the folder of the task handler

bmc_itsm7_person_retrieve_acme_v1

Update the taskDefinition id and name (line 2) and handler name (line 15) in node.xml. The id should be all lower case with underscores instead of spaces. The name is not case sensitive.

<?xml version="1.0" encoding="UTF-8"?>
<taskDefinition id="bmc_itsm7_person_retrieve_acme" name="BMC ITSM7 Person Retrieve ACME" schema_version="1.0" version="1">
    <author>linda.koestler@kineticdata.com</author>
    <description>
        Retrieves a single ITSM v7.x CTM People entry related to the
        Remedy Login specified.
    </description>
    <helpurl>http://ktc.kineticdata.com/handler/bmc_itsm7_person_retrieve</helpurl>
    <visible>true</visible>
    <deferrable>false</deferrable>
    <parameters>
        <parameter id="remedy_login_id" label="Remedy Login ID:" required="true"
          tooltip="The Remedy Login ID associated to the CTM People record to retrieve"/>
    </parameters>
    <handler name="bmc_itsm7_person_retrieve_acme" version="1">

Update the Class name in init.rb (line 7 in init.rb in the handler). This should be the same as the taskDefinition id with only the first letter of each "word" capitalized and with the underscores removed. A capital V followed by the version number is always on the end of the class name.

class BmcItsm7PersonRetrieveAcmeV1

2.  Make sure the search is returning either all fields or a list that includes the customer fields. (init.rb)

In this case, as is the case with most retrieve handlers, the search returns all fields.

# Retrieve a single entry from CTM:People based on Remedy Login ID
    entry = @@remedy_forms['CTM:People'].find_entries(
      :single,
      :conditions => [%|'4' = "#{@parameters['remedy_login_id']}"|],
      :fields => :all
    )

No change is necessary.

3.  Add the custom fields to the returned results in the init.rb

The two lines below are added between the <results> tags with the other results.

  <result name="OfficerLoginID">#{escape(entry['OfficerLoginID'])}</result>
  <result name="OfficerName">#{escape(entry['OfficerName'])}</result>

4. Add the custom fields to the returned results in the node.xml

The two lines below are added between the <results> tags with the other results.

  <result name="OfficerLoginID"/>
  <result name="OfficerName"/>

Documentation Updates

1.  Update the simple_output.xml to include the new results

The two lines below are added between the <results> tags with the other results.

  <result name="OfficerLoginID"></result>
  <result name="OfficerName"></result>

2.  Update the README to include the new results

The following lines below are added to the Results section of the README.

[OfficerLoginID]
  The 'OfficerLoginID' of the retrieved CTM:People record.
[OfficerName]
  The 'OfficerName' of the retrieved CTM:People record.

3.  Update the CHANGELOG to indicate the updates made

The following lines below are added to the top of the CHANGELOG

BMC_ITSM7_Person_Retrieve_ACME (2013-06-28)
* Added two custom fields, OfficerLoginID and OfficerName,
   to results

Completing the Handler Updates

You will want test the updated handler against your system using the test harness. Then you will be ready to zip up the folder and import the handler into your system.

Note that this particular handler won't actually work on your system and return values for these two fields unless your system actually has these two custom fields. This is an example for you to work off of to add your own custom fields.