Thursday, November 17, 2011

Easy XBRL Scripting with Gepsio and PowerShell

Microsoft’s PowerShell scripting environment provides full support for using .NET objects, which makes it an ideal scripting language for use with Gepsio. PowerShell and Gepsio can work together to make working with XBRL data very easy.

Here is a simple PowerShell script that pulls an XBRL document from the SEC site and displays some simple information about the document:

Add-Type -Path "C:\GepsioPath\JeffFerguson.Gepsio.dll"

$XbrlDoc = New-Object -TypeName JeffFerguson.Gepsio.XbrlDocument

$DocumentLocation = "http://www.sec.gov/Archives/edgar/data/21344/000104746911006790/ko-20110701.xml"
Write-Host "Loading and validating" $DocumentLocation"..."
$XbrlDoc.Load($DocumentLocation)

foreach($CurrentFragment in $XbrlDoc.XbrlFragments)
{
Write-Host $CurrentFragment.Facts.Count "facts in fragment."
Write-Host $CurrentFragment.Units.Count "units in fragment."
Write-Host $CurrentFragment.Contexts.Count "contexts in fragment."
}



This script gives the following output:

Loading and validating http://www.sec.gov/Archives/edgar/data/21344/000104746911006790/ko-20110701.xml...
1081 facts in fragment.
4 units in fragment.
281 contexts in fragment.



Let’s take a look at the script in more detail. It begins by adding the Gepsio runtime into the PowerShell environment with a call to the Add-Type command:

Add-Type -Path "C:\GepsioPath\JeffFerguson.Gepsio.dll"



Every PowerShell script that uses Gepsio will need to use this command so that the Gepsio runtime can be used by the PowerShell script.


Once Gepsio is loaded, a new Gepsio XbrlDocument object is created and saved in a variable:

$XbrlDoc = New-Object -TypeName JeffFerguson.Gepsio.XbrlDocument



This statement states that a new .NET object of type JeffFerguson.Gepsio.XbrlDocument, which is the Gepsio type that represents an XBRL document, should be created and be made available in a PowerShell script variable called $XbrlDoc.


One the new XbrlDocument object is created, another PowerShell variable is created to describe the address of the document to be loaded:

$DocumentLocation = "http://www.sec.gov/Archives/edgar/data/21344/000104746911006790/ko-20110701.xml"



This statement creates a new PowerShell script variable called $DocumentLocation and assigns it a string of “http://www.sec.gov/Archives/edgar/data/21344/000104746911006790/ko-20110701.xml”. This is the address of the XBRL document that the script should load.


Once the address of the XBRL document is made available, it is loaded into the Gepsio XbrlDocument object through a call to the XbrlDocument.Load() method:

$XbrlDoc.Load($DocumentLocation)



Gepsio treats an XbrlDocument as a collection of XbrlFragment objects. Each XBRL fragment is XML data having the <xbrl> tag as its root. Generally, an XBRL document will have only one XbrlFragment, although Gepsio supports documents that may have more than one fragment. The script iterates through each fragment in the document and examines the Xbrlfragment object’s three main collections: Facts, Units and Contexts. Each collection has a property called Count, and each of these counts are displayed as script output:

foreach($CurrentFragment in $XbrlDoc.XbrlFragments)
{
Write-Host $CurrentFragment.Facts.Count "facts in fragment."
Write-Host $CurrentFragment.Units.Count "units in fragment."
Write-Host $CurrentFragment.Contexts.Count "contexts in fragment."
}



Future blog posts will explore PowerShell’s access to the Gepsio runtime in more detail.

4 comments:

  1. I have a question about the GetFact(FactId) method of XbrlFragment.
    I am trying to return an instance of an item for a SalesRevenueNet fact.
    This method is documented as taking a FactId as a parameter but I can find no such member for any class in a search of the documentation. When I try to use "SalesRevenueNet", the fact name, as the parameter, I get a nil result. What is meant by a FactId?

    ReplyDelete
    Replies
    1. A fact ID is the value of a fact's "ID" attribute. If, during parsing, Gepsio finds an "ID" attribute on a fact element, its value is captured and stored in the Fact object's ID property.

      When you call GetFact(factID) you are asking Gepsio to find the fact that has an "ID" attribute whose value matches the value you supply. The string you supply as the parameter to GetFact() is an attribute value. If Gepsio cannot find a fact with an "ID" attribute with a value you supply, then a null value will be returned.

      If this isn't useful to you, please email me and let me know how I can build in a method that does what you need. I want to be sure that Gepsio meets the needs of its users.

      Thanks for using Gepsio!

      Delete
    2. Well, in the meantime I kind of figured out a work around. A fact only has an Id when it is returned as a single object of type Item. If there is more than one Item in the fact, then the fact is returned as an array list. So one must test the fact for its type and iterate through the array list for the id of each Item if the fact is actually a group of items.

      Correct?

      Delete
    3. If I understand you correctly, then -- yes. that's a valid workaround.

      With that said, I'm interested in making Gepsio better so that you don't have to implement a workaround. I'd be happy to improve Gepsio so that your scenario is easier to code. If you can email me privately [jeffrey.ferguson at gmail dot com] with your XBRL instance, any supporting schema and linkbase files, as well as a description of what you're currently doing to find the fact in which you're interested, I would be happy to work with you to come up with a better solution that better meets your needs.

      Thanks for using Gepsio!

      Delete