|
This section contains sample ATConfig files that you can edit to suit your needs.
Consider installing Notepad++, a free text editor with great XML editing capabilities.
|
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
Example - APM 12 - Custom to Native.atconfig
Example - APM12 - Native to Native.atconfig
We don't support publishing to APM 12 extended fields.
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.
ATConfig files are large and complex. To manage field mappings, you only need to concern yourself with a few major sections:
ATConfig section | Description |
---|---|
<CustomFields> | Not necessarily specific to DFP, this section defines the custom fields that will be available in AT. If you're mapping from an AT custom field to a repository field, then you will need to define a custom field to map from. If you're not mapping from any custom fields, then DFP doesn't care about this section. |
<HandlerFieldDefinitions> | Similar with custom fields, this section defines the handler fields that are available for a given handler. If you're mapping from an AT handler field to a repository field that doesn't already exist, then you will need to define a new handler field to map from. If you're not mapping from any custom fields, then DFP doesn't care about this section. Prior to DFP, handler fields were hard-coded, but DFP allows you to "hang a new handler field from a handler". |
<FieldPublishingMaps> | This section defines the actual mapping between the AT field and the repository field. |
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:
ca_owned_resource
serial_number | processor_speed | processor_speed_unit |
---|---|---|
S00123 | 1.5 | 11 |
S00999 | 2.04 | 11 |
ca_processor_speed_unit
id | name |
---|---|
3 | Kbps |
4 | MHz |
11 | GHz |
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><Apm12Mapping xmlns="http://assettrack.assetmgi.com/"><ApmTypeName>asset</ApmTypeName><ApmPropertyName>processorspeedunitskey</ApmPropertyName><ApmForeignKeyType>processorspeedunits</ApmForeignKeyType><ApmForeignKeyIdProperty>id</ApmForeignKeyIdProperty><ApmForeignKeyValueProperty>value</ApmForeignKeyValueProperty></Apm12Mapping></MappingXml> <!-- The type of field map ... vs APM11FieldMap / ServiceDeskFieldMap --> <TypeName>Apm12FieldMap</TypeName> </ATFieldPublishingMap> |
If you want a deeper understanding for how things work, the information below is explains how the files are authored.
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:
Element name | Description |
---|---|
FixedName | The AssetTrack GUID for the field ... in this example, Asset.Cost |
HandlerId | The AssetTrack static GUID for the specific handler this mapping is for
|
Id | A unique ID for this FieldPublishingMap row in the DB ... Guid.NewGuid |
MappingXml | The type-specific serialized XML blob describing the mapping, XML characters escaped |
TypeName | The statically-defined value describing the type of serialized object type in the MappingXml value
|
Below are specific examples for configuring a Dynamic Field Mapping for the following types of AssetTrack fields:
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.
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><Apm11Mapping xmlns="http://assettrack.assetmgi.com/"><ApmTypeName>Asset</ApmTypeName><ApmPropertyName>Capacity</ApmPropertyName><PublishNullEmpty>false</PublishNullEmpty></Apm11Mapping></MappingXml> <!-- The type of field map ... "APM11FieldMap" / "APM12FieldMap" / "ServiceDeskFieldMap" --> <TypeName>Apm11FieldMap</TypeName> </ATFieldPublishingMap> </FieldPublishingMaps> |
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><Apm11Mapping xmlns="http://assettrack.assetmgi.com/"><ApmTypeName>Asset</ApmTypeName><ApmPropertyName>AuditDate</ApmPropertyName><PublishNullEmpty>false</PublishNullEmpty></Apm11Mapping></MappingXml> <TypeName>Apm11FieldMap</TypeName> </ATFieldPublishingMap> </FieldPublishingMaps> |
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:
Element name | Description |
---|---|
FixedName | The fixed name for the field |
HandlerId | The AssetTrack static GUID for the specific handler this handler field is for
|
Id | A unique ID for this HandlerFieldDefinition row in the DB ... Guid.NewGuid |
PropertiesXml | Serialized HandlerFieldProperties containing resultant value type and specific field type's properties (e.g. StringFieldProperties)/ See PropertiesXml Examples below |
<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><HandlerFieldProperties xmlns="http://assettrack.assetmgi.com/"><ItemType>String</ItemType><FieldProperties d2p1:type="StringFieldProperties" xmlns:d2p1="http://www.w3.org/2001/XMLSchema-instance"><FieldDisplayName>Deployment Status</FieldDisplayName><RequiredForNewAssets>false</RequiredForNewAssets><ScanPatterns /><ScanPrefixes /><MaxLength>200</MaxLength><PickList><Elements><PickListItem><DisplayValue>Backup</DisplayValue><Index>0</Index><Value>Backup</Value></PickListItem><PickListItem><DisplayValue>Development</DisplayValue><Index>1</Index><Value>Development</Value></PickListItem><PickListItem><DisplayValue>Disaster Recovery</DisplayValue><Index>2</Index><Value>Disaster Recovery</Value></PickListItem><PickListItem><DisplayValue>Production</DisplayValue><Index>3</Index><Value>Production</Value></PickListItem><PickListItem><DisplayValue>QA</DisplayValue><Index>4</Index><Value>QA</Value></PickListItem><PickListItem><DisplayValue>Test</DisplayValue><Index>5</Index><Value>Test</Value></PickListItem></Elements><SortOrder>ByIndex</SortOrder></PickList></FieldProperties></HandlerFieldProperties></PropertiesXml>
</ATHandlerFieldDefinition>
</HandlerFieldDefinitions>
<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>
<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>
<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>
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
UAPM Handler | C2BA244F-90A3-4cae-A8A6-0C3FBB4F815C |
ITAM Handler | 3528688B-170C-4f10-8D7C-7919D8AC83B7 |
Service Desk Handler | 5A22F1D6-5FFF-11DC-8314-0800200C9A66 |
AssetId | 03fdc220-e1b4-4e91-8fb7-55a1c2a159e7 |
AlternateId | 37404d68-17b4-4fdb-a9d8-3200198072df |
SeatId | cb70cc3f-2fbe-4e07-9364-274017ba3c9e |
ProductId | a29d6514-6ed1-45d0-b0e2-1e6ad7abffaa |
SerialNumber | 8290ebc9-b118-441c-a021-254913ba7828 |
Cost | fa61b96e-6162-4565-9bcb-1ee950ed1481 |
LeaseEndDate | f7696565-6c22-4668-b952-21a73c4c6259 |
WarrantyEndDate | 86abc1c5-756d-4bb3-8633-71a320651805 |
VendorId | 066980b9-506e-40df-b9ea-4b6bff948d09 |
LocationId | 0eb53314-ba6b-4ca2-8fff-9c16d195bc64 |
OrganizationId | 432b5ab0-2949-4136-9bc1-a63e12be5e66 |
AssigneeId | f4f40f82-14a0-42bb-b37c-918ef17d83f3 |
PONumber | 81baba10-d11b-11d8-9669-0800200c9a66 |
DateCreated | 76384930-8f6f-4b47-aedb-573f8787d578 |
DateModified | 64c15338-cb91-4b2b-87a3-c931a6b88a5e |
AcquisitionDate | 22b02dfd-2347-46dc-a70c-31de4d59859c |
Status | c6e045e8-8fa5-49f8-8fbe-f794e6f21f08 |
Description | 64dda56e-dda4-4c23-873e-97c77c1e7939 |
SystemStatus | 3e9dd59f-50f8-4807-9add-15131a3eb46c |
DateSystemStatusModified | 9007b077-6cd8-4943-b81e-ae0ea1005106 |
ExternalId | c9dd1032-8865-4ee8-a7c1-4fe4ab205faa |
MacAddress | 6c7d1429-62ab-4a42-83e8-9184f074c994 |
ServiceStatus | 73e4f3f3-15d7-11de-8c30-0800200c9a66 |
StockroomId | 5e5f18f4-ec72-4e22-a5b7-0c36c2cdc57c |
CustomKey1 | 6767a87e-96ed-4f11-83e1-7c0875325453 |
CustomKey2 | a5c6182c-9e40-4d2a-9839-b6b158953a46 |
CostCenterId | 4f053f62-b273-4682-85c4-1935b3b5e569 |
LineItemNumber | 048d325f-df57-4be4-b511-ca74d38f7fff |
AssetName | 96c6f110-d5fc-11e0-9572-0800200c9a66 |
HostName | a8b98400-d5fc-11e0-9572-0800200c9a66 |
CAFloorLocation | 39AFABEE-9D93-488c-990C-C8FFDD4D0E4B |
CARoomLocation | 14FE68EE-3886-4711-AF99-2FA50ACB45FD |
CACabinetLocation | 542528FA-DEE2-4a0e-9B60-C87B168ED6F3 |
CAShelfLocation | 82E67791-CC3B-439b-879F-92A1C0A6AF28 |
CASlotLocation | A82605FD-5135-4770-AB3C-EE3E527749DC |
CustomEntity1 | 62B38457-1FDC-4c3c-A469-59931333F2A2 |
CustomEntity2 | 826865B8-6CD3-480d-95E4-45EE63FDE65C |
CustomEntity3 | 654B87CA-5F2A-47cb-A2A3-32F216C7196E |
CustomEntity4 | 83215B45-790F-4ba7-8F32-1316522EE91B |
hostname [string]
Serialized HandlerFieldProperties containing resultant value type and specific field type's properties (e.g. StringFieldProperties)