Sometimes you wish your AF database was reorganized differently

 

I would hope your AF Database models follow a plant heirarchy and be nothing like tags in the Data Archive.  But you might not be so lucky.  Or, when using a PI Connector, AF Assets are created for you and they tend to follow the networking pattern for how the sensors assets are organized.  Often though, there are projects in your organization that would benefit greatly if your asset model were organized differently.  By reorganizing your AF database you could save yourself from expensive lookup queries or worse: traversing complicated parent/child chains using AF SDK or PI Web API.  It can make a lot more sense to get your asset model structured in a way that makes sense for whatever your present needs are.

 

Since AF SDK went public users have taken upon themselves to build AF SDK programs that do this sort of (re) "mapping".

 

AF Transformer helps you accomplish this remapping task without the need to build, compile and test C# code using AF SDK.  By editing an XML configuration file (with a good text editor ;-) and running the tool you can transform one or more AF databases into a new model that can greatly assist your projects and your downstream users who want to see assets in a way they understand.

 

 

Presented April 25, 2018 at PI World

 

Why might I use AF Transformer?

 

  • A downstream application is being built that needs to see/traverse your AF model in a way that would require a large number of lookups.  It might make a lot more sense to produce a new AF model that's pre-sorted to meet the needs of your downstream application--boosting performance and decreasing the amount of time it takes to develop.
  • You need to build a segmented AF model that limits the scope of assets to a particular group of users
  • You need to flatten, expand or pivot an AF model so it makes more sense to the various different business consumers in your organization

 

Getting Started - Let's pivot an AF database based on an attribute value

 

Inside the AF Transformer kit are examples that include two AF databases you can import.  I have an enhanced version of WellsDb.xml attached to this blog post (called WellsDBWithAFTable.xml) that includes an additional AF table of well maintenance contractors who are assigned to a well.  I have also added an attribute to link each well to a contractor and resolve the contractor's name.

 

2018-05-11_14-54-17.png

 

Import WellsDBWithAFTable.xml into a new AF Database in PI System Explorer (under File->Import From File...) I prefer to call it WellsDb, but you can name it whatever you like.

 

Next, create a second empty AF Database.  Let's call it TransformedWells.  This is where we're going to deposit the output from the transform.

 

Now, let's transform this.  Write an XML file with the following sections.  Be careful to update the <DataSource> and <Writers> tags to your correct source and target AF database host name and database names.  (CLSAF is the name of my own AF Server; which is likely not going to be the name of your own AF Server)

 

<?xml version="1.0" encoding="UTF-8"?>
<CASTDataSet xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <LogFilePath>c:\Program Files\PIPC\AFTransformer\AF Transformer Examples\example.log</LogFilePath>
   <StatInfo />
   <ProcessProperties>
      <!-- Default values for process properties are used -->
   </ProcessProperties>
   <Tasks>
      <Task Id="1000">
         <SearchShapes>
            <SearchShape Id="1001" ReaderId="1002" FilterMatchType="Any">
               <DataFilters />
            </SearchShape>
         </SearchShapes>
         <OutputElementShapes>
            <OutputElement Id="1003" />
         </OutputElementShapes>
         <TaskWriters>
            <TaskWriter Id="1004" />
         </TaskWriters>
      </Task>
   </Tasks>
   <DataSources>
      <DataSource MEFClass="AF" HighID="0" ID="1002">
         <Properties>
            <Properties Key="Host" Value="CLSAF" />
            <Properties Key="Database" Value="WellsDb" />
            <Properties Key="UserName" Value="" />
            <Properties Key="Password" Value="" />
            <Properties Key="DefaultPIServer" Value="" />
         </Properties>
      </DataSource>
   </DataSources>
   <Writers>
      <Writer MEFClass="AF" Enabled="true" Encoding="UTF8" ID="1004">
         <Properties>
            <Properties Key="Host" Value="CLSAF" />
            <Properties Key="Database" Value="TransformedWells" />
         </Properties>
      </Writer>
   </Writers>
   <SearchShapes>
      <!-- Specify the elements and attributes of the search pattern that AF Transformer uses to search the source PI AF database -->
      <Shape ID="1001" Required="true" FilterMatchType="Any" ShapeWalkType="TopBottom">
         <ShapeElements>
            <ShapeElement ID="1" Required="true" FilterMatchType="Any" MaxDepthFromParent="1" IsEntryPoint="false">
               <Filters>
                  <ElementFilter Category="" Template="Facility" Name="*" />
               </Filters>
               <Attributes>
                  <ShapeAttribute ID="10" Required="true" FilterMatchType="Any">
                     <Filters>
                        <AttributeFilter Category="" Template="" Name="Contractor Name" />
                     </Filters>
                  </ShapeAttribute>
                  <ShapeAttribute ID="11" Required="true" FilterMatchType="Any">
                     <Filters>
                        <AttributeFilter Category="" Template="" Name="Description" />
                     </Filters>
                  </ShapeAttribute>
               </Attributes>
            </ShapeElement>
         </ShapeElements>
      </Shape>
   </SearchShapes>
   <OutputElementShapes>
      <!-- Create and populate the asset model in the destination database -->
      <OutputElementShape ID="1003">
         <Elements>
            <!--Here is where the new AF Database model begins-->
            <Element Name="Injection Wells by Contractor" Guid="" ReadOnly="false" Template="">
               <Elements>
                  <Element Name="[10.Value]" Guid="" Description="Contractor" ReadOnly="false" Template="">
                     <Elements>
                        <Element Name="[1.Name]">
                           <Attributes>
                              <Attribute Name="Description" Value="[11.Value]" />
                           </Attributes>
                        </Element>
                     </Elements>
                  </Element>
               </Elements>
            </Element>
         </Elements>
      </OutputElementShape>
   </OutputElementShapes>
</CASTDataSet>

 

Now, let's run this.

 

In a command prompt window, call the utility directly with the /configxml="{path to your xml transform file here}" option.

 

2018-05-11_16-08-49.png

 

Go check your output

 

Take a look at the console output.  Make sure the AF Reader and the AF Writer in the console output both report that they've found their respective AF databases.  If so, the remaining part of the orchestration will complete and transpose the AF Objects.  Let's check the TransformedWells AF database to be sure.

 

2018-05-11_16-10-59.png

 

Yup, they're there.

 

This is the simplest example of AF Transformer working so that you grasp how to do grouping.  In Part 2, we will build off this example and convert the Line Pressure and Tubing Pressure AF Elements into Attributes that report directly on these transformed well elements.