Search for	Example	Results
A single word	`cat`	Topics that contain the word "cat". You will also find its grammatical variations, such as "cats".
A phrase. You can specify that the search results contain a specific phrase.	`"cat food"` (quotation marks)	Topics that contain the literal phrase "cat food" and all its grammatical variations. Without the quotation marks, the query is equivalent to specifying an OR operator, which finds topics with one of the individual words instead of the phrase.

Search for	Operator	Example
Two or more words in the same topic	`AND` `and` `+` (plus symbol) `&` (ampersand)	`cat AND dog` `"cat food"+milk` `"cat food"&"dog food"`
Either word in a topic	`OR` `or` `\|` (pipe)	`cat OR dog` `cat \| dog`
Topics that do not contain a specific word or phrase	`NOT` `not` `!` (exclamation point)	`NOT cat` `! dog`
Topics that contain one string and do not contain another	`^` (caret)	`cat ^ mouse`
A combination of search types	`( )` parentheses	`cat + (dog \| mouse)` `cat \| dog + (! mouse)`

Universal CMDB11.0

Develop > Developer Reference > Creating Discovery and Integration Adapters > Developing Generic Database Adapters > Adapter Configuration Files > The orm.xml File

The orm.xml File

This file is used for mapping CMDB CITs to database tables.

A template to use for creating a new file is located in the C:\UCMDB\UCMDBServer\runtime\fcmdb\CodeBase\GenericDBAdapter\META-INF directory.

To edit the XML file for a deployed adapter, navigate to Adapter Management > db-adapter > Configuration files.

The orm.xml Schema

The following table explains the common elements of the orm.xml file. The complete schema can be found at http://java.sun.com/xml/ns/persistence/orm_1_0.xsd. The list is not complete, and it mainly explains the specific behavior of the standard Java Persistence API for the Generic Database Adapter.

Element Name and Path	Description	Attributes
entity-mappings	The root element for the entity mapping document. This element should be exactly the same as the one given in the GDBA sample files.
description (entity-mappings)	A free text description of the entity mapping document. (Optional)
package (entity-mappings)	The name of the Java package that will contain the mapping classes. Should always contain the text generic_db_adapter.	Name: name Description: The name of the UCMDB CI type to which this entity is mapped. If this is entity is mapped to a link in the CMDB, the name of the entity should be in the format <end_1>_<link_name>_<end_2>. For example, node_composition_cpu defines an entity that will be mapped to the composition link between a node and a CPU. If the name of the CI type is the same as the name of the Java class without the package prefix, this field can be omitted. Is required?: Optional Type: String Name: class Description: The fully qualified name of the Java class that will be created for this DB entity. The name of the Java class' package should be the same as the name given in the package element. You may not use Java reserved words, such as interface or switch, as the class name. Instead, add the prefix gdba_ to the name (so interface will be generic_db_adapter.gdba_interface. Is required?: Required Type: String
table (entity-mappings>entity)	This element defines the primary table of the DB entity. Can only appear once. Required.	Name: name Description: The name of the primary table. If the name of the table does not contain the schema to which it belongs, the table will be searched only in the schema of the user that was used to create the integration point. This can also be any valid SELECT statement. If this is a SELECT statement, it must be encapsulated with parentheses. Is required?: Required Type: String
secondary-table (entity-mappings > entity)	This element may be used to define a secondary table for the DB entity. This table must be connected to the primary table with a 1-to-1 relationship. You may define more than one secondary table. Optional.	Name: name Description: The name of the secondary table. If the name of the table does not contain the schema to which it belongs, the table will be searched only in the schema of the user that was used to create the integration point. This can also be any valid SELECT statement. If this is a SELECT statement, it must be encapsulated with parentheses. Is required?: Required Type: String
primary-key-join-column (entity-mappings > entity > secondary-table )	If the secondary table and primary table are not connected using fields with the same name, this element defines the name of the primary key field in the secondary table that needs to be connected to the primary key field of the primary table.	Name: name Description: The name of the primary key field in the secondary table. If this element does not exist, it is assumed that the primary key field has the same name as the primary key field of the primary table. Is required?: Optional Type: String
inheritance (entity-mappings > entity)	If the current entity is the parent entity for a family of DB entities, then use this element to mark it as such. Optional.	Name: strategy Description: Defines the way the inheritance is implemented in your DB. Is required?: Required Type: One of the following values: SINGLE_TABLE: This entity and all child entities exist in the same table. JOINED: The child entities are in joined tables. TABLE_PER_CLASS: Each entity is completely defined by a separate table.
discriminator-column (entity-mappings > entity)	If the inheritance is of type SINGLE_TABLE, this element is used to define the name of the field used to determine the type of entity for each row.	Name: name Description: The name of the discriminator column. Is required?: Required Type: String
discriminator-value (entity-mappings > entity)	This element defines the type of the specific entity in the inheritance tree. This name needs to be the same as the name defined in the discriminator.properties file for the value group of this specific entity type.
attributes (entity-mappings > entity)	The root element for all of the attribute mappings for an entity.
id (entity-mappings > entity attributes)	This element defines the key field for the entity. There must be at least one id field defined. If more than one id element exists, its fields create a compound key for the entity. You should try and avoid compound keys for CI entities (not for links).	Name: name Description: A string of type idX, where X is a number between 1 and 9. The first id should be marked as id1, the second as id2 and so on. This is NOT the name of the key attribute in UCMDB. Is required?: Required Type: String
basic (entity-mappings > entity attributes)	This element defines a mapping between a field in the table, which is not part of the table's primary key, and a UCMDB attribute.	Name: name Description: The name of the UCMDB attribute to which the field is mapped. This attribute must exist in the UCMDB CI type to which the current entity is mapped. Is required?: Required Type: String
column (entity-mappings > entity > attributes >id -OR- (entity-mappings > entity > attributes > basic)	Defines the name of the column in the table for basic mapping or an id field.	Name: name Description: The name of the field. Is required?: Required Type: String Name: table Description: The name of the table to which the field belongs. This must be either the primary table or one of the secondary tables defined for the entity. If this attribute is omitted, it is assumed that the field belongs to the primary table. Is required: Optional Type: String
one-to-one (entity-mappings > entity > attributes)	Defines a column whose value is in another table, and the two tables are connected using a one-to-one relationship. This element is only supported for link entity mappings and not for other CI types. This is the only way to define a mapping between a table and a UCMDB link.	Name: name Description: Which of the two ends this field represents. Is required?: Required Type: Either end1 or end2 Name: target-entity Description: The name of the entity to which the end refers. Is required?: Required Type: One of the entity names defined in the entity mapping document.
join-column (entity-mappings > entity attributes > one-to-one)	Defines the way to join the target-entity defined in the parent one-to-one element and the current entity.	Name: name Description: The name of the field in the current table that will be used to perform the one-to-one join. Is required?: Required Type: String Name: name Description: The name of a field in the joint entity by which to perform the join. If this attribute is omitted, it is assumes that the joint table has a column with the same name as the field defined in the name attribute. Is required?: Optional Type: String

Example of Creating the orm.xml File

The example presented here demonstrates how to create the orm.xml file. In this example, SQL tables in a remote database are mapped to CI types in UCMDB.

Given tables with the following format in the remote database, populate the Hosts table with nodes, the IP_Addresses table with IP Addresses, and create links between the nodes and IP Addresses as follows:

Hosts Table

host_name	host_id
Test1	1
Test2	2
Test3	3

IP_Addresses Table

ip_address	ip_id
10.1.1.1	1
10.2.2.2	2
10.3.3.2	3
10.4.4.4	4

Host_IP_Link Table (links between Nodes and IP Addresses)

host_id	ip_id
1	1
2	2
2	3
3	4

The primary key for the Hosts table is the host_id field and the primary key in the IP_Addresses Table table is the ip_id field. In the Host_IP_Link table the host_id and the ip_id are foreign keys from the Hosts Table and IP_Addresses Table.

According to the tables above, create the orm.xml file according to the following steps. The entities used in this example are node, ip_address, and node_containment_ip_address

Create the node entity by mapping the host_id from the Hosts table as follows:

<entity-mappings xmlns="http://java.sun.com/xml/ns/persistence/orm"

	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.0"

	xsi:schemaLocation="http://java.sun.com/xml/ns/persistence
	/orm_1_0.xsd">

<description>test_integration</description>

<package>generic_db_adapter</package>

<entity class="generic_db_adapter.node">

<table name="Hosts"/>

<attributes>

	<id name="id1">

		<column updatable="false" insertable="false" name=
			"host_id"/>

		<generated-value strategy="TABLE"/>

	</id>

	<basic name="name">

		<column updatable="false" insertable="false" name=
			"host_name"/>

	</basic>

</attributes>

</entity>

The entity class must be a CI Type that already exists in UCMDB. The table name is the table within the database that contains both an ID and the Host information. The ID attribute is required to identify specific hosts and is used later in the mapping. In this example, the name attribute of this entity is populated with the host_name column in the hosts table.

For the next entity, map the IP Addresses from the Interfaces table:

<entity name="ip_address" class="generic_db_adapter.ip_address">

<table name="IP_Addresses"/>

<attributes>

<id name="id1">

	<column insertable="false" updatable="false" name="ip_id"/>

	<generated-value strategy="TABLE"/>

</id>

<basic name="name">

	<column updatable="false" insertable="false" name="ip_address"/>

</basic>

</attributes>

</entity>

Next the link between the Node and the IP Address must be created by means of the mapping table, and reference the ip_id field (though it could reference both the host_id and ip_id fields if desired).
```
<entity name="node_containment_ip_address" 
```
```
	class="generic_db_adapter.node_containment_ip_address">
```
```
<table name="Host_IP_Link"/>
```
```
<attributes>
```
```
<id name="id1">
```
```
	<column updatable="false" insertable="false" name="ip_id"/>
```
```
	<generated-value strategy="TABLE"/>
```
```
</id>
```
```
<many-to-one target-entity="node" name="end1">
```
```
	<join-column name="host_id"/>
```
```
</many-to-one>
```
```
<one-to-one target-entity="ip_address" name="end2">
```
```
	<join-column name="ip_id"/>
```
```
</one-to-one>
```
```
</attributes>
```
```
</entity>
```
The entity name for the container has the format: [end1 CIT]_[link CIT]_[end2 CIT]. So for this example, since the link CI Type is containment, the entity name for the container is: node_containment_ip_address and the entity class is generic_db_adapter.node_containment_ip_address. The ID is required in this block of code, and while this example works with a single ID of the Interface, both columns could reference id1 and id2. The code for that would be:
```
<id name=”id1”>
```
```
<column updatable=”false” insertable=”false” name=”ip_id”/>
```
```
<generated-value strategy=”TABLE”/>
```
```
</id>
```
```
<id name=”id2”>
```
```
<column updatable=”false” insertable=”false” name=”host_id”/>
```
```
<generated-value strategy=”TABLE”/>
```
```
</id>
```
The two ends of this link are ‘many-to-one’ and ‘one-to-one’, meaning each IP Address will be linked to 1 node, but a node may be linked to many IP Addresses. The columns included are from the Links table and reference the Hosts and Interfaces tables.

Parent topic: Adapter Configuration Files

Send Help Center feedback