How to Import XML into a Specific Path in PI AF Using AFSDK

Importing XML into a precise location within your OSIsoft PI Asset Framework (AF) hierarchy is a common requirement for AF administrators and developers who manage complex models. However, the nuances of the ImportXml method, XML structure, and headers can cause XML to end up at the root level or result in failed imports. This post addresses best practices and common pitfalls when importing XML fragments directly into a named AF Element using AFSDK.

Key Considerations

1. Targeting the Insertion Point with ImportXml

The first parameter of the ImportXml method specifies the AF object into which the XML will be imported. This is critical! If you pass the AFDatabase or PISystem, elements are imported at the root. To insert under a specific element, pass the .Elements collection of that element.

Example (C#):

PISystems myPISystems = new PISystems();
PISystem myPISystem = myPISystems["PISERVER"];
AFDatabase myDb = myPISystem.Databases["MyDatabase"];
AFElement elementWhereToInsert = myDb.Elements["Element1"].Elements["Element2"];

// Import as children of Element2
myPISystem.ImportXml(elementWhereToInsert.Elements, PIImportMode.AllowCreate | PIImportMode.AllowUpdate | PIImportMode.AutoCheckIn, "C:\Element3.xml");

2. XML File Structure: Elements Only

The XML for import should usually contain only <AFElement> objects–not the <AFDatabase> root. Including a database-level export header means the import will only target the database’s root.

Minimal Example:

<AF xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="OSIsoft.AF.xsd" SchemaVersion="2.0">
  <AFElement>
    <Name>Fuel System2</Name>
    <AFElement ReferenceType="Parent-Child">
      <Name>PowerBoard3</Name>
      <Description>Module</Description>
      <AFAttribute>
        <Name>description</Name>
        <Type>String</Type>
        <Value type="String">25K power board</Value>
      </AFAttribute>
    </AFElement>
  </AFElement>
</AF>

3. The Importance of XML Header

An incorrect (or overly complete) XML header–usually included in full AF exports–may specify properties like PIPersist, ExportedType, or Identity, restricting import to the AF root. For element insertions, use concise headers as shown above and avoid properties that bind the XML to the database level.

4. Troubleshooting Tips

• No Errors, No Import: If import completes with no error but no elements are added, check your header and ensure you're targetting a valid .Elements collection.
• Test in PSE First: You can reliably derive a working XML by exporting child elements using PI System Explorer (PSE) and then re-importing at the desired location via the Child Elements tab.
• Check XML Structure: Nested <AFElement ReferenceType="Parent-Child">...</AFElement> blocks are required to build hierarchies.

Putting It All Together

To import XML under a specific AF path, follow these steps:

1. Navigate to the Insertion Point
   • Use AFSDK to find the parent element:

   AFElement targetElement = ... // however you look it up
   

2. Prepare XML
   • Export the relevant elements from PSE or hand-craft as shown above.
3. Use the Correct Import Statement

   myPISystem.ImportXml(targetElement.Elements, PIImportMode.AllowCreate | PIImportMode.AutoCheckIn, "C:\YourXmlFile.xml");
   

4. Verify Results
   • Refresh your model in PSE and ensure the new elements appear in the expected location.

Final Thoughts

Correctly targeting XML imports in PI AF saves time and avoids tedious rework. Remember to review the structure of your XML and always pass the correct AF objects into ImportXml. When in doubt, export/import with PSE as a baseline, then automate it with AFSDK as needed!