Manually Configuring CA Integration using Dynamic Field Mapping

Sample ATConfig files

This section contains sample ATConfig files that you can edit to suit your needs. 

APM 11

Example - Custom to Extended.atconfig

Example - picklist handler field to APM picklist native field.atconfig

Example - string handler field to APM string native field

Example - int handler field to APM int native field.atconfig

Example - money handler field to APM decimal extended field.atconfig

Example - nullabledecimal handler field to APM native double field.atconfig

Example - datetime handler field to APM native datetime field.atconfig

APM 12

Example - APM 12 - Custom to Native.atconfig

Example - APM12 - Native to Native.atconfig

We don't support publishing to APM 12 extended fields. 

Service Desk

Example - SD12 - Custom to Native.atconfig

Example - SD12 - Handler to Native.atconfig

Example - SD12 - Custom to Asset Extension Field 4.7.0.59 and lower.atconfig

Example - SD12 - Custom to Asset Extension Field 4.7.0.60 and up.atconfig

SD extended fields are "compiled", meaning that if you add a "Foo" extended field to an SD asset object, the SD asset object just appear to have a new "Foo" property, and you should just be able to map to it as if it were an SD native field.

SD extension fields are fields that live in other tables related to the asset table. They are mapped based on family name (e.g. computer workstations have a Service Desk family name of "Hardware.Workstation", and its extension table is "har_worx"). See this CA support document for family names and their associated extension tables.

Basic anatomy of a field mapping in ATConfig

ATConfig files are large and complex. To manage field mappings, you only need to concern yourself with a few major sections:

Mapping simple value fields vs foreign key fields

If you have a text custom field mapping to a text extended field, that's a simple mapping. During publishing, the only thing that happens there is the custom field value gets written to the mapped repository field. Same with numeric and date data types.

Repositories have foreign key fields, however.  Take the example below for specifying the processor speed unit (e.g. MHz, GHz). Those actual values are stored in their own table, and referenced by ID from ca_owned_resource. If you wanted to map to the processor_speed_unit field, you have two options:

• Magically know that MHz=4 and GHz=11 and create a picklist in AssetTrack that displays MHz, GHz but sends the values 4 and 11 at publishing time via a simple int field mapping. This is a simple and easy way to accomplish this and it may work well for examples like this where there are only a few values, but the downsides are that if the IDs change (most likely in a Dev/Test/Production environment difference), then you'll be publishing the wrong int value. For other foreign key fields like Model, manually managing the ID values like this is unmanageable because there are too many records.
• Set up DFP so that you can simply send the string "MHz" and have DFP do the lookup to translate that value into 4. We call these "foreign key mappings".

ca_owned_resource

ca_processor_speed_unit

Here is an example of setting up a foreign key mapping:

<!-- Handler field "ProcessorSpeedUnits" [picklist] > APM 12 Asset - Alternate Host Name -->
<ATFieldPublishingMap>
	<!-- The AssetTrack GUID or Fixed Name for the field ... in this example, the fixed name for the handler field, ProcessorSpeedUnits -->
	<FixedName>ProcessorSpeedUnits</FixedName>
	
	<!-- The AssetTrack GUID for the ITAM Handler -->
	<HandlerId>3528688B-170C-4f10-8D7C-7919D8AC83B7</HandlerId>
	
	<!-- A unique ID for this FieldPublishingMap row in the DB ... (e.g. Guid.NewGuid) -->
	<Id>e6a03bb0-98a6-11e2-9e96-0800200c9a66</Id>
	
	<!--
	The XML blob describing the mapping, XML characters escaped
	<Apm12Mapping xmlns="http://assettrack.assetmgi.com/">
		<!-- The Type name of the root object that is the parent of the foreign key object --\>
		<!-- to which you are publishing ... mostly always "asset"                         --\>
		<ApmTypeName>asset</ApmTypeName>
		
		<!-- The root object's property holding the foreign key id of the foreign key ob-  --\>
		<!-- ject to which you want to publish your value.                                 --\>
		<ApmPropertyName>processorspeedunitskey</ApmPropertyName>
		
		<!-- The Type name of the foreign key object to which the value shold be published --\>
		<ApmForeignKeyType>processorspeedunits</ApmForeignKeyType>
		
		<!-- The foreign key object property holding the id referenced by the parent obj.  --\>
		<ApmForeignKeyIdProperty>id</ApmForeignKeyIdProperty>
		
		<!-- The foreign key object property where the value should be published.          --\>
		<ApmForeignKeyValueProperty>value</ApmForeignKeyValueProperty>
	</Apm12Mapping>
	-->
	<MappingXml>&lt;Apm12Mapping xmlns=&quot;http://assettrack.assetmgi.com/&quot;&gt;&lt;ApmTypeName&gt;asset&lt;/ApmTypeName&gt;&lt;ApmPropertyName&gt;processorspeedunitskey&lt;/ApmPropertyName&gt;&lt;ApmForeignKeyType&gt;processorspeedunits&lt;/ApmForeignKeyType&gt;&lt;ApmForeignKeyIdProperty&gt;id&lt;/ApmForeignKeyIdProperty&gt;&lt;ApmForeignKeyValueProperty&gt;value&lt;/ApmForeignKeyValueProperty&gt;&lt;/Apm12Mapping&gt;</MappingXml>
			
	<!-- The type of field map ... vs APM11FieldMap / ServiceDeskFieldMap -->
	<TypeName>Apm12FieldMap</TypeName>
</ATFieldPublishingMap>

Reference

If you want a deeper understanding for how things work, the information below is explains how the files are authored.

The <ATFieldPublishingMap> atconfig element

Dynamic field mappings are described by a <ATFieldPublishingMap> node in the atconfig (whose properties map to a single row in the FieldPublishingMap table), which consists of the following information:

• The handler to which the mapping applies
• The AssetTrack field for which data will be collected (the source field in publishing)
• The repository destination where the data will be published (API object and property the handler will use)
  

Specific elements of the ATFieldPublishingMap element 

Examples

Below are specific examples for configuring a Dynamic Field Mapping for the following types of AssetTrack fields:

• Native AssetTrack fields
• Custom AssetTrack fields
• Handler fields (fields that show up underneath the handler node of the field list when one of the supported handlers is added to a form)

For the sake of brevity, we will be focusing on UAPM 11 as the destination (MappingXml portion of the ATFieldPublishingMap.  In a later section, we will focus on describing the MappingXml objects.

Native AssetTrack fields

A Native AssetTrack field is a statically-defined, permanent field in the AssetTrack code base, such as Asset.Cost.

In this example, we publish the data collected against the static Asset.Cost field to the APM Asset.Capacity object ... doesn't make sense, but both are decimal (double) types.

<FieldPublishingMaps>
	<ATFieldPublishingMap>
		<!-- The AssetTrack fixed GUID for the field (see the AssetTrack Field Ids list below) ... in this example, Asset.Cost -->
		<FixedName>fa61b96e-6162-4565-9bcb-1ee950ed1481</FixedName>
		<!-- The AssetTrack GUID for the UAPM Handler -->
		<HandlerId>C2BA244F-90A3-4cae-A8A6-0C3FBB4F815C</HandlerId>
		<!-- A unique ID for this FieldPublishingMap row in the DB ... Guid.NewGuid -->
		<Id>c38d04eb-f424-41a3-bd0c-2165059598c3</Id>
		<!-- The XML blob describing the mapping, XML characters escaped
		<Apm11Mapping xmlns="http://assettrack.assetmgi.com/">
			<ApmTypeName>Asset</ApmTypeName> <!-- The APM11 api object to which this field will publish its collected data --\>
			<ApmPropertyName>Capacity</ApmPropertyName> <!-- the APM11 api object field to which this field will publish its collected data --\>
			<PublishNullEmpty>false</PublishNullEmpty>
		</Apm11Mapping>
		-->
		<MappingXml>&lt;Apm11Mapping xmlns="http://assettrack.assetmgi.com/"&gt;&lt;ApmTypeName&gt;Asset&lt;/ApmTypeName&gt;&lt;ApmPropertyName&gt;Capacity&lt;/ApmPropertyName&gt;&lt;PublishNullEmpty&gt;false&lt;/PublishNullEmpty&gt;&lt;/Apm11Mapping&gt;</MappingXml>
		<!-- The type of field map ... "APM11FieldMap" / "APM12FieldMap" / "ServiceDeskFieldMap" -->
		<TypeName>Apm11FieldMap</TypeName>
		
	</ATFieldPublishingMap>
</FieldPublishingMaps>

Custom AssetTrack fields or Handler fields

Both custom field and handler field mappings are identified and applied during publishing by the FixedName element.  So instead of a GUID, the fixed name for the field identifies the value that we should publish.  In this case, we will publish a custom field called collection_date to the APM asset field, Audit Date.

<FieldPublishingMaps>
  <ATFieldPublishingMap>

    <!-- The fixed name of the custom field or handler field ... in this example, a custom field with the fixed name, collection_date -->
    <FixedName>collection_date</FixedName>

    <!-- The AssetTrack GUID for the UAPM Handler -->
    <HandlerId>5A22F1D6-5FFF-11DC-8314-0800200C9A66</HandlerId>

    <!-- A unique ID for this FieldPublishingMap row in the DB ... Guid.NewGuid -->
    <Id>5500b5c0-9bd7-11e2-9e96-0800200c9a66</Id>

    <!-- The XML blob describing the mapping, XML characters escaped
      <Apm11Mapping xmlns="http://assettrack.assetmgi.com/">
        <ApmTypeName>Asset</ApmTypeName>
        <ApmPropertyName>AuditDate</ApmPropertyName>
        <PublishNullEmpty>false</PublishNullEmpty>
      </Apm11Mapping>
    -->
    <MappingXml>&lt;Apm11Mapping xmlns=&quot;http://assettrack.assetmgi.com/&quot;&gt;&lt;ApmTypeName&gt;Asset&lt;/ApmTypeName&gt;&lt;ApmPropertyName&gt;AuditDate&lt;/ApmPropertyName&gt;&lt;PublishNullEmpty&gt;false&lt;/PublishNullEmpty&gt;&lt;/Apm11Mapping&gt;</MappingXml>
    <TypeName>Apm11FieldMap</TypeName>
  </ATFieldPublishingMap>
</FieldPublishingMaps>

The <ATHandlerFieldDefinition> element

Handler fields show up in the field list of form design when one of the dynamic-field-supported handlers is added to a form.  They can be manually configured in the ATConfig file by specifying the ATHandlerFieldDefinition element, which consists of the following information:

• The handler to which the mapping applies
• The AssetTrack field for which data will be collected (the source field in publishing)
• The repository destination where the data will be published (API object and property the handler will use)

Specific elements of the ATFieldPublishingMap element 

Examples

<HandlerFieldDefinitions>
 <ATHandlerFieldDefinition>
 <!-- No value for this field, given this is an config-defined handler field for the UAPM 11 handler -->
 <FieldId xsi:nil="true" />
 
 <!-- Fixed name for the handler field ... referenced in the fieldmap -->
 <FixedName>DeploymentStatus</FixedName>
 
 <!-- GUID for the UAPM 11 handler -->
 <HandlerId>C2BA244F-90A3-4cae-A8A6-0C3FBB4F815C</HandlerId>
 
 <!-- Unique GUID for this specific handler field definition -->
 <Id>8aa0f578-e0de-4516-b7ea-61701820568e</Id>
 
 <!-- XML blob describing the handler field's properties ...
 Serialized HandlerFieldProperties containing resultant value type and specific field type's properties (e.g. StringFieldProperties)
 See HandlerFieldProperties example -->
 <PropertiesXml>&lt;HandlerFieldProperties xmlns="http://assettrack.assetmgi.com/"&gt;&lt;ItemType&gt;String&lt;/ItemType&gt;&lt;FieldProperties d2p1:type="StringFieldProperties" xmlns:d2p1="http://www.w3.org/2001/XMLSchema-instance"&gt;&lt;FieldDisplayName&gt;Deployment Status&lt;/FieldDisplayName&gt;&lt;RequiredForNewAssets&gt;false&lt;/RequiredForNewAssets&gt;&lt;ScanPatterns /&gt;&lt;ScanPrefixes /&gt;&lt;MaxLength&gt;200&lt;/MaxLength&gt;&lt;PickList&gt;&lt;Elements&gt;&lt;PickListItem&gt;&lt;DisplayValue&gt;Backup&lt;/DisplayValue&gt;&lt;Index&gt;0&lt;/Index&gt;&lt;Value&gt;Backup&lt;/Value&gt;&lt;/PickListItem&gt;&lt;PickListItem&gt;&lt;DisplayValue&gt;Development&lt;/DisplayValue&gt;&lt;Index&gt;1&lt;/Index&gt;&lt;Value&gt;Development&lt;/Value&gt;&lt;/PickListItem&gt;&lt;PickListItem&gt;&lt;DisplayValue&gt;Disaster Recovery&lt;/DisplayValue&gt;&lt;Index&gt;2&lt;/Index&gt;&lt;Value&gt;Disaster Recovery&lt;/Value&gt;&lt;/PickListItem&gt;&lt;PickListItem&gt;&lt;DisplayValue&gt;Production&lt;/DisplayValue&gt;&lt;Index&gt;3&lt;/Index&gt;&lt;Value&gt;Production&lt;/Value&gt;&lt;/PickListItem&gt;&lt;PickListItem&gt;&lt;DisplayValue&gt;QA&lt;/DisplayValue&gt;&lt;Index&gt;4&lt;/Index&gt;&lt;Value&gt;QA&lt;/Value&gt;&lt;/PickListItem&gt;&lt;PickListItem&gt;&lt;DisplayValue&gt;Test&lt;/DisplayValue&gt;&lt;Index&gt;5&lt;/Index&gt;&lt;Value&gt;Test&lt;/Value&gt;&lt;/PickListItem&gt;&lt;/Elements&gt;&lt;SortOrder&gt;ByIndex&lt;/SortOrder&gt;&lt;/PickList&gt;&lt;/FieldProperties&gt;&lt;/HandlerFieldProperties&gt;</PropertiesXml>
 
 </ATHandlerFieldDefinition>
 </HandlerFieldDefinitions>

PropertiesXml examples (serialized HandlerFieldProperties)

Picklist field properties

<HandlerFieldProperties xmlns="http://assettrack.assetmgi.com/">
  <!-- Valid values include String, NullableDecimal, NullableDateTime -->
  <ItemType>String</ItemType>
  <FieldProperties d2p1:type="StringFieldProperties" xmlns:d2p1="http://www.w3.org/2001/XMLSchema-instance">
    <RequiredForNewAssets>false</RequiredForNewAssets>
    <ScanPatterns />
    <ScanPrefixes />
    <FieldDisplayName>Deployment Status</DisplayName>
    <MaxLength>100</MaxLength> 

    <!-- The Picklist element is optional -->

    <PickList DefaultValue="Backup">

      <Elements>
        <PickListItem>
          <DisplayValue>Backup</DisplayValue>
          <Index>0</Index>
          <Value>Backup</Value>
        </PickListItem>
        <PickListItem>
          <DisplayValue>Production</DisplayValue>
          <Index>1</Index>
          <Value>Production</Value>
        </PickListItem>
      </Elements>
      <SortOrder>ByIndex</SortOrder>
    </PickList>
  </FieldProperties>
</HandlerFieldProperties>

Int field properties

<HandlerFieldProperties xmlns="http://assettrack.assetmgi.com/">
 <ItemType>String</ItemType>
 <FieldProperties d2p1:type="StringFieldProperties" xmlns:d2p1="http://www.w3.org/2001/XMLSchema-instance">
   <FieldDisplayName>Processor Count</FieldDisplayName>
   <RequiredForNewAssets>false</RequiredForNewAssets>
   <ScanPatterns />
   <ScanPrefixes />
   <MaxLength>100</MaxLength>
 </FieldProperties>
</HandlerFieldProperties>

DateTime field properties

<HandlerFieldProperties xmlns="http://assettrack.assetmgi.com/">
 <ItemType>NullableDateTime</ItemType>
 <FieldProperties d2p1:type="StringFieldProperties" xmlns:d2p1="http://www.w3.org/2001/XMLSchema-instance">
   <FieldDisplayName>Acquire Date</FieldDisplayName>
   <RequiredForNewAssets>false</RequiredForNewAssets>
   <ScanPatterns />
   <ScanPrefixes />
   <MaxLength>100</MaxLength>
 </FieldProperties>
</HandlerFieldProperties>

Specific examples defined in TestLodge

TestLodge has specific test examples defined with corresponding atconfig files.  This is a good source for answering questions of, "How would I map a field of type x and data type y to a foreign repository field of configuration z?"

http://ami.testlodge.com/projects/1012/test_suites/7069

AssetTrack Handler Ids

TaskItemDataType Enum Values

• Decimal
• NullableDateTime
• NullableDecimal
• String
• Int32
• NullableInt32
• Boolean
• NullableBoolean

AssetTrack native field IDs

APM 11 Asset object properties

• AcquireDate [string]
• AltAssetID [string]
• AlternateHostName [string]
• AssetAlias [string]
• AssetName [string]
• AssetSourceID [string]
• AssetType [string]
• AuditDate [string]
• BackupServicesContactID [string]
• BillingContactID [string]
• CabinetLocation [string]
• Capacity [double]
• CapacityUnits [string]
• ClassValue [string]
• CompanyBoughtForID [string]
• ContactCompanyID [string]
• ContactID [string]
• CostCenter [string]
• Department [string]
• DeploymentStatus [string]
• DisasterRecoveryContactID [string]
• DiscoveryLastRunDate [string]
• DNSName [string]
• ExcludeReconciliationKey [int]
• FloorLocation [string]
• GLCode [string]
• HostName [string]
• Inactive [string]
• InstallationDate [string]
• IPAddress [string]
• IsAssetKey [int]
• IsCIKey [int]
• ItemName [string]
• LicenseCount [int]
• LicenseDuration [int]
• LicenseDurationUnit [string]
• LicenseInformation [string]
• LicenseKey [string]
• LicenseType [string]
• LocationID [string]
• MacAddress [string]
• MaintenanceOrganizationID [string]
• MaintenanceVendorID [string]
• Managed [string]
• ManagedBySWCM [int]
• ManufacturerID [string]
• NetworkContactID [string]
• OperatingSystem [string]
• OrganizationBoughtForID [string]
• PreviousResourceTag [string]
• Priority [string]
• ProcessorCount [int]
• ProcessorSpeed [double]
• ProcessorSpeedUnits [string]
• ProcessorType [string]
• ProductVersion [string]
• PurchaseOrderID [string]
• Quantity [int]
• ReconciliationDate [string]
• RequisitionID [string]
• ResourceDescription [string]
• ResourceOwnerID [string]
• ResponsibleOrganizationID [string]
• ResponsibleVendorID [string]
• RoomLocation [string]
• SellerCompanyID [string]
• SerialNumber [string]
• ServiceType [string]
• ShelfLocation [string]
• SlotLocation[string]
• Status [string]
• StatusDate [string]
• Subclass [string]
• SupportContact1ID [string]
• SupportContact2ID [string]
• SupportContact3ID [string]
• SWCMLicenseEffectiveDate [string]
• SWCMLicenseTerminationDate [string]
• SWCMLicenseTermTypeKey [int]
• TotalDiskSpace [double]
• TotalDiskSpaceUnits [string]
• TotalMemory [double]
• TotalMemoryUnits [string]
• UserField1 [string]
• UserField2 [string]
• UserField3 [string]
• UserField4 [string]

APM 12 Asset object properties

• acquiredate [nullable DateTime]
• altassetid [string]
• alternatehostname [string]
• assetalias [string]
• assetfamilyid [nullable int]
• assetid [string]
• assetname [string]
• auditdate [nullable DateTime]
• backupservicescontactid [string]
• billingcontactid [string]
• cabinetlocation [string]
• classkey [nullable int]
• companyboughtforid [string]
• contactid [string]
• costcenterkey [nullable int]
• creationdate [nullable DateTime]
• creationuser [string]
• departmentkey [nullable int]
• disasterrecoverycontactid [string]
• discoverylastrundate [nullable DateTime]
• dnsname [string]
• environmenttypeid [nullable int]
• excludereconciliationkey [nullable bool]
• floorlocation [string]
• glcodekey [nullable int]
• helpdesksupportcontactid [string]

• hostname [string]

• hwsupportcontactid [string]
• inactiveflag [nullable bool]
• installationdate [nullable DateTime]
• ipaddress [string]
• isassetkey [nullable bool]
• iscikey [nullable bool]
• lastupdatedate [nullable DateTime]
• lastupdateuser [string]
• licenseid [string]
• licenseinformation [string]
• lifecyclestatusdate [nullable DateTime]
• lifecyclestatuskey [nullable int]
• locationid [string]
• macaddress [string]
• maintenanceorganizationid [string]
• maintenancevendorid [string]
• managedassetflag [nullable bool]
• manufacturerid [string]
• modelid [string]
• networkcontactid [string]
• operatingsystemkey [nullable int]
• organizationboughtforid [string]
• ossupportcontactid [string]
• previousassettag [string]
• processorcount [nullable int]
• processorspeed [nullable double]
• processorspeedunitskey [nullable int]
• processortype [string]
• productversion [string]
• purchaseorderid [string]
• quantity [nullable int]
• reconciliationdate [nullable DateTime]
• registeredassettypeid [nullable int]
• requisitionid [string]
• resourcedescription [string]
• resourceownerid [string]
• responsibleorganizationid [string]
• responsiblevendorid [string]
• roomlocation [string]
• sellercompanyid [string]
• serialnumber [string]
• servicestatusdate [nullable DateTime]
• servicestatusid [nullable int]
• shelflocation [string]
• slotlocation [string]
• subclasskey [nullable int]
• swcmlicenseid [nullable int]
• tenantid [string]
• totaldiskspace [nullable double]
• totaldiskspaceunitskey [nullable int]
• totalmemory [nullable double]
• totalmemoryunitskey [nullable int]
• versionnumber [nullable int]

TaskDataItemType Enum Values

• AssetTypeTaskItem
• AssigneeTaskItem
• Decimal
• IdentifiableTaskItem
• LocationTaskItem
• OrganizationTaskItem
• ManufacturerTaskItem
• NullableDateTime
• NullableDecimal
• ProductTaskItem
• String
• VendorTaskItem
• Int32
• StockroomTaskItem
• ArrayOfTaskDataItems
• NullableInt32
• Boolean
• NullableBoolean
• CostCenterTaskItem
• PurchaseOrderTaskItem
• SkuTaskItem

Serialized HandlerFieldProperties containing resultant value type and specific field type's properties (e.g. StringFieldProperties)