How to Programmatically Set an Element-Type Attribute to Reference Another Element in PI AF Using AFSDK and AF Builder

One of the powerful features of PI Asset Framework (AF) is its ability to reference objects and elements dynamically. In particular, you might have scenario where an AF Element (let’s call it X) has an attribute of type Element (Value Type: Element), and you want that attribute to point to another existing Element (Y). While this is easily configured through PI System Explorer (PSE), it is not scalable when you have a large number of elements to manage. In this article, we’ll explore how to automate this task using the AFSDK and AF Builder scripting.

Why Reference Elements Through Attributes?

Using element-type attributes is a great way to describe relationships, assign configuration templates, or simply reference related objects in your AF model. It allows you to create navigation-friendly hierarchies and enables context-aware analytics and visualization.

Manual Configuration Limitation

In PI System Explorer, setting an attribute of value type Element is usually done by clicking the ... button and manually selecting the reference target. However, this approach quickly becomes unwieldy for hundreds or thousands of elements.

Automating with AFSDK (C#)

Here’s how you can set an attribute of type Element programmatically using AFSDK:

1. Retrieve Your Elements

First, obtain references to both the parent element (X) and the target element (Y). If you have the full path, you can use AFElement.FindElements or navigate directly from the database root:

// Set up your AFDatabase object (assume you already have this)
AFElement elementX = AFElement.FindElement(db, "\\Database\ElementX");
AFElement elementY = AFElement.FindElement(db, "\\Database\ElementY");

// Or use an attribute storing the element path for Y
string yPath = elementX.Attributes["Element Path"].GetValue().Value as string;
AFElement elementY = AFElement.FindElement(db, yPath);

2. Assign the Element Reference

Assuming the attribute is already created on X and is of type Element:

AFAttribute elementAttr = elementX.Attributes["Element"];
elementAttr.SetValue(new AFValue(elementY));

// Save changes
AFDatabase db = elementX.Database; // Assuming you have a reference
AFList<AFNamedCollectionList> changes = db.CheckIn(); // Or db.PISystem.CheckIn();

3. Save Your Changes

Always remember to check-in any pending changes.

Automating with AF Builder

AF Builder scripting allows automated batch creation and updating of AF objects. To set an attribute reference via AF Builder:

• Ensure the attribute column is configured as value type Element.
• Specify the full AF path to the target element as the attribute’s value.
• When you import your spreadsheet/script, AF Builder interprets the path and links the attribute accordingly.

Example Row in AF Builder CSV:

AF Builder will look up \Database\Y and assign that as the value for X’s Element attribute.

When to Use This Pattern

• Modeling relationships between pieces of equipment (e.g., Pumps referencing Controllers).
• Creating navigation links in your AF hierarchy.
• Automating AF deployments at scale, especially in large and dynamic environments.

Conclusion

While setting element-type references is straightforward in PSE, automation with AFSDK and AF Builder dramatically improves scalability and repeatability. By storing element paths as string attributes (if needed), and using those to automate references, you can programmatically manage even the largest AF models efficiently.

---

Have questions or want to share how you use element attributes in your AF models? Share your experience in the comments below!