Integrate > Service Manager integration methods and tools > BDM Mapping Management > Field Mapping

Field Mapping

The Field Mapping tab of a BDM mapping defines the field mappings between a Service Manager object and a BDM object. This section describes how to configure the columns on this tab, and provides detailed information about the inner objects, functions, and variables that can be used to configure callbacks in the SM Callback and BDM Callback columns.

Field Mapping columns

The following table describes the columns on the Field Mapping tab.

Column Name Description
SM Object Field

The name of a field in the Service Manager file, and can be selected from the list.

Note Do not select the first item such as [probsummary] in the list, which references the name of the file that you want to map to BDM. The BDM mapping utility does not support complex structures at this time (for example, an array of arrays or an array within an array of structures).
Direction Indicates the mapping direction of a field mapping, and has only three values to select from.
  • ->: from SM Object Field to BDM Object Field/Attribute.
  • <-: from BDM Object Field/Attribute to SM Object Field.
  • <->: in both directions.
BDM Object Field/Attribute

The name of a field in the BDM object, and should be in a format like XPath of XML.

For example, the following XML segment:

<is_registered_for target_role='xxx'>
    <target_global_id>xxx</target_global_id>
    <target_type>xxx</target_type>  
    <configuration_item>                          
      <id>xxx</id> 
      <type>xxx</type> 
      <description>xxx</description> 
    </configuration_item>
</is_registered_for>

should be formatted as:

is_registered_for/@target_role    (@ means it is an attribute)
is_registered_for/ target_global_id
is_registered_for/ target_type
is_registered_for/ configuration_item/ id
is_registered_for/ configuration_item/ type
is_registered_for/ configuration_item/ description
  • You can use an array to represent repetitive elements. For example: 
    <users>
   <user>
       <name>xxx</name>
       <email>xxx</email>
   </user>
   <user>
       <name>xxx</name>
       <email>xxx</email>
   </user>
   ...
</users>

    Can be described as:

    users/user[0]/name
users/user[0]/email
users/user[1]/name
users/user[1]/email
  • The namespace of a BDM field should be formatted as: 
    ns:property1/ns:subproperty2

    ns is the alias of a namespace, and should be included in the BDM Callback of the @xmlns mapping entry:

    $xmlns({..., "ns":"http://www.xxx.com/xxx/xxx", ...})
    If the alias is omitted, then a default namespace configured in @xmlns will be used:
    '\$':"http://www.xxx.com/xxx/xxx"
SM Default Value Defines the default value of the SM Object Field if there is no value in the corresponding BDM Object Field/Attribute when mapping the BDM object to the Service Manager object.
SM Callback

Enter custom JavaScript code, which will be invoked when mapping BDM Object Field/Attribute to SM Object Field. For information about how to configure callbacks, see the Callbacks section below.

Note If no callback is configured, the BDM Object Field/Attribute will be directly mapped to the SM Object Field.
BDM Default Value Defines the default value of the BDM Object Field/Attribute if there is no value in the corresponding SM Object Field when mapping the Service Manager object to the BDM object.
BDM Callback Enter custom JavaScript code for mapping between the BDM Object Field/Attribute and the SM Object Field. When mapping the Service Manager object to the BDM object, the custom JavaScript code will be invoked. For more information about how to configure callbacks, see the Callbacks section below.
BDM Type Select one from the list: String (default), Number, and DateTime. If no BDM Type is selected, the default type (String) will be used.
Value Mapping Group The name of a value mapping group to which the BDM Object Field/Attribute and SM Object Field belong. A value mapping group contains a collection of enumerated BDM/SM value pairs. The Service Manager value and BDM value will be mapped according to the configuration on the Value Mapping tab.
Description Enter a text description for this BDM mapping.

Callbacks

In the SM Callback and BDM Callback columns, you can enter custom JavaScript code for mapping between the Service Manager object and BDM object. Some inner objects, variables, and functions can be used in the custom JavaScript code. The key word $ is reserved to identify these inner objects, variables, and functions.

Reserved key word ($)

The following rules apply when you use the reserved key word: $.

  • If you want to use your own variable prefixed with '$', you must escape it with character '\'. For example: 
    var \$test = 'abc';
  • You can also use inner variables and objects in a string. For example: 
    var strTemp = "Incident Number: $sm.number";

    If you want to use a '$' in a string, you must escape it. For example:

    cost: 100 \$ ...
  • In a regular expression, you do not need to escape '$' with '\': 
    var regExpr = /^[Jj]ava[Ss]cript$/

    However, if you define with the RegExp object, you must escape '$', because '$' is in a string:

    var regExpr = new RegExp( "^[Jj]ava[Ss]cript\$" );

Inner objects, functions, and variables

The following tables list the inner objects, functions, and variables.

  • Inner Objects

    Object Name Member Method Signature / Method Description

    $sm

    The current Service Manager object.

    value(field)

    field: The name of a field of the Service Manager object. If you do not include the <field> parameter, the currently configured field is used. Subfields should be separated with a forward slash ('/').

    This function is used to extract the value of a field of the Service Manager object. If you do not include the <field> parameter, it will return the current field value. For example: 

    $sm.value( "id" )
    $sm.value( "resolution[0]" )
    $sm.value()

    setValue(value, field)

    value: The value of the <field> to be set.

    field: The name of a field of the Service Manager object. If you do not include the <field> parameter, the currently configured field will be used.

    This function is used to set the value of a field of the Service Manager object. If you do not include the <field> parameter, it will return the current field value.

    $bdm

    The current BDM object.

    value(field)

    field: The name of a field of the BDM object. If you do not include the <field> parameter, the currently configured field will be used. Subfields should be separated with a forward slash ("/").

    This function is used to extract the value of a field of the BDM object. If you do not include the <field> parameter, it will return the current field value. For example: 

    $bdm.value( "is_registered_for/configuration_item" )
    $bdm.value( "ns:users/ns:user[0]/name" )
    $bdm.value()

    setValue(value, field)

    value: The value to be set for the <field>.

    field: The name of a field of the BDM object. If you do not include the <field> parameter, the currently configured field will be used.

    Note The field value must be the value in the BDM Object Field/Attribute column.

    This function is used to set the value of a field of the BDM object.

    $ctx

    The current mapping context object, which is used to hold some variables to be used in the whole mapping process.

    set(key, value)

    key: The key to be set for the <value>.

    value: The value to be kept in the mapping context object for the key.

    This function is used to set a key-value pair in a mapping context object. For example: 

    $ctx.set("affected_ci", affected_ci)

    get(key)

    key: The key in a key-value pair.

    This function is used to get the value of a key in a mapping context object. For example: 

    var affected_ci = $ctx.get("affected_ci")

  • Inner functions

    Function Signature Description
    $xmlns()

    Used to define an xml namespace.

    Example:

    $xmlns({"\$":"http://www.hp.com/2009/software/data_model",
    "bdm":" http://www.hp.com/2009/software/data_model"}).

    In this example, "\$":"http://www.hp.com/2009/software/data_model" is a default namespace, where reserved key word $ is escaped with a backslash ("\"); "bdm":" http://www.hp.com/2009/software/data_model" is another namespace, where bdm is the alias of the namespace. You can add more namespaces, but there is only one default namespace.

    $afterString(str)

    str: A portion of the current mapping field value.

    Used to return the portion of the current mapping field value that is after the string specified by the <str> parameter.

    Example:

    $afterString("urn:x-hp:software:servicemanager:incident:id:")

    If the current mapping field is 'global_id' of the BDM object, and its value is urn:x-hp:software:servicemanager:incident:id:7B21A623-158B-45D4-9C7C-3D2821096A44, the $afterString will return: 7B21A623-158B-45D4-9C7C-3D2821096A44.

    $prefix(str)

    str: The string value to be prefixed before the current mapping field value.

    Used to prefix a string before the current mapping field value.

    Example:

    If the current mapping field is 'id' of the Service Manager object and its value is "5A8EABC6-CA1B-499B-A230-4D6DE07487D8", 

    $prefix("urn:x-hp:software:servicemanager:incident:id:")

    will return urn:x-hp:software:servicemanager:incident:id: 5A8EABC6-CA1B-499B-A230-4D6DE07487D8.

    $select(fileName, query)

    • filename: The name of a valid Service Manager file.
    • query: The Service Manager query language.

    Used to do select the SM object from the SM DB.

    Example:

    var requestedBy = $select("contacts",'operator.id="falcon"');

    $combine(delimiter)

    delimiter: A symbol or character used to separate the combined values.

    		 Used to combine the current field values of the Service Manager/BDM object into one string.

    combine(arr, delimiter)

    • arr: An array of values to be combined.
    • delimiter: A symbol or character used to separate the combined values.

    Used to combine the specified array of values into one string.

    Example:

    combine( ['a','b','c'], ',')
    $isCreate() Used to verify if the current operation has created an SM object in Service Manager (true) or not (false).
    $isUpdate() Used to verify if the current operation has updated an SM object in Service Manager (true) or not (false).

  • Inner variables

    Variable Name Description
    $result This variable is used to hold the returned result that will be assigned to the current target field of the Service Manager/BDM object if the custom JavaScript code cannot generate a value (for example, the 'if' statement cannot generate a value, and thus needs to use the $result variable to hold the result): 
    var affected_ci = $ctx.get("affected_ci");
if( affected_ci ) {
	$result = affected_ci['type'];
}

Related topics

BDM Mapping Management
Value Mapping
Atom Mapping
Customizing BDM mapping configuration