Vault webservice trace

In many applications like MS Word or the like, you have the ability to record macros. This simplifies a lot the development of own code, as you can see the code generated by the application, and you can derive from that the code you like to write. Wouldn’t it be nice to trace the Vault API calls, in order to understand which functions and which arguments are required, so that you can then write your own code without starting from scratch? Well, Vault does not offer macro recording, but you can activate the webservice trace, which records all the API calls from the client to the server. This article explains you how to activate the trace and how to filter the huge amount of data via few lines of PowerShell.

The trace can be activated on the client side or server side. The difference is obvious: the client side trace will only trace the calls from the specific Vault client, while the server trace will trace calls from every client. The server trace might be interesting if you like to trace non Vault clients, like CAD applications or custom applications. However, the log file will become big and it slows down the system.

In our case we activate the client trace. The file we will modify is called Connectivity.VaultPro.exe.config, while VaultPro changes based on your Vault flavor. The file is located usually under c:\Program Files\Autodesk\Vault <Flavor> <Version>\Explorer. A simple notepad will be fine for editing, but as this file is an XML file, a XML Notepad would be better. Look for this section


<microsoft.web.services3>
  <messaging>
    <maxMessageLength value="51200"></maxMessageLength>
    <mtom clientMode="On" />
  </messaging>
  <security>
    <!-- Specifies the time buffer used by WSE to determine when a SOAP message is valid. <em id="__mceDel"> set to the max of 24hr in seconds -->
    <timeToleranceInSeconds value="86400" />
  </security>
  <diagnostics>
    <!-- this only works if AutodeskVault user has write permission to the "Web\Services" directory. After an install, the
 AutodeskVault user only has read access. -->
  <trace enabled="true" input="c:\temp\traceServerIn.log" output="c:\temp\traceServerOut.log" />
  </diagnostics>
</microsoft.web.services3>

The interesting section is <trace … />. This section is probably missing in your file, so just add it as described above. Set the enable attribute to true and define at the input and output attributes the location and name for the log file. Save the file and restart your Vault client. You will then see such files been created and growing.

Click around your Vault and you will trace the API calls. Now, the output file is the file that describes the API calls that goes out from Vault with according arguments, while the server response with according objects are in the input file. If you open the output file, you will notice a lot of inputMessage elements and each of them has processingStep elements. Each last processingStep contains a soap:Envelope and a soap:Body. The next child element is the API call with the arguments as children. Every inputMessage has a messageId which describes the unique ID of this message. In the input file, you’ll find a similar structure and the response has in the soap:Headerwsa:MessageID that will have the same message ID as the command that has been sent. So, via this ID you can see the answer to the according call.

The following PowerShell script reads the input file, searches for each processingStep that has the attribute description=’Processed message’ and picks the element child of soap:Body. As we work here with XML file, we use a quite powerful technique called XPath. It allows us to filter the XML for specific element with certain criteria. A good introduction to XPath can be found here.

For each API call we find, we take the message ID and look for the according response in the input file. The PowerShell script prints out all the API calls with according arguments and the response from the server.

[xml]$xmlOut = Get-Content -LiteralPath c:\Temp\traceServerOut.log
[xml]$xmlIn = Get-Content -LiteralPath c:\Temp\traceServerIn.log
$bodies = Select-Xml -XPath "//processingStep[@description='Processed message']//soap:Body/*" -Xml $xmlOut -Namespace @{"soap" = "http://schemas.xmlsoap.org/soap/envelope/"}
foreach ($body in $bodies)
{
 $messageId = $body.Node.ParentNode.ParentNode.ParentNode.ParentNode.messageId
 $body.Node.Name
 foreach ($child in $body.Node.ChildNodes) { " "+$child.Name+"="+$child.InnerText }
 $response = Select-Xml -XPath "//soap:Header[wsa:RelatesTo='$messageId']/../soap:Body/*" -Xml $xmlIn -Namespace @{"soap" = "http://schemas.xmlsoap.org/soap/envelope/";"wsa" = "http://schemas.xmlsoap.org/ws/2004/08/addressing"}
 " Response:"+$response.Node.Name
 foreach ($child in $response.Node.FirstChild.ChildNodes) { " "+$child.Name+"="+$child.InnerText }
}

Some functions have simple arguments like a string or number, but other have arrays or objects, which in the XML notation they would generate a structure with several levels. The script above just reads the first level of the structure. So you may see that arguments for some functions are not complete. But the script is short enough and still powerful enough to give you a fast view of the functions called.

Just adapt the path to your trace files and let the script run. You will see in the output window the summary of the API calls, those arguments and server response. With this information you can now create your code, taking advantage of the calls made by Vault. For instance, if you like to figure out how to find the files associated to an item, you could start the trace, navigate to your item, and see the item tab with the linked files. In order to show this information, Vault called several commands, which are in the trace and you can pick the commands of interest.

I hope this helps you when you create your next Vault extension.

This entry was posted in PowerShell, Vault API. Bookmark the permalink.

3 Responses to Vault webservice trace

  1. Doug Redmond says:

    I don’t recommend editing the config file for tracing. Fiddler (http://www.fiddler2.com/) provides a much better way. Fiddler shows more information, allows you to start and stop as needed, and doesn’t have a bulky trace file slowing everything down.
    Just download Filler and start it up while running a Vault client. It will pick up all network traffic. Make sure to connect to Vault using the server name and not ‘localhost’.

  2. jdkriek says:

    Fiddler can filter “the noise of the XML data” as well ;)

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s