Updating References with Vault 2014 API

With Vault 2014 Autodesk introduced some useful utilities to uploading and downloading Files from Vault. AcquireFiles is the function for downloading and checking out files. AddFile and CheckinFile are the functions for uploading files.
These functions also provide extra functionality, including batch downloading, large file transfer, compression and file reference fixing. You can get some useful informations about the AcquireFiles function here: http://justonesandzeros.typepad.com/blog/2013/05/how-to-acquire-files.html

With this post I would like to add some additional informations about the AcquireFiles function. To use the Acquire Files function you have to pass an Object of type AcquireFilesSettings. This Object provides multiple settings, here some examples:

private AcquireFilesResults DownloadFileAndCheckOut(File file)
	#FileIteration Object for the AcquireFile function
	var fileIteration = new FileIteration(_vaultConnection, file);
	#AcquireFileSetting Object to set the download and checkout properties
	var settings = new AcquireFilesSettings(_vaultConnection);
	#The local file will be overwritten.
	settings.OptionsResolution.ForceOverwrite = true;
	#Includes children / dependecy Files to download/Checkout
	settings.OptionsRelationshipGathering.FileRelationshipSettings.IncludeChildren = true;
	settings.OptionsRelationshipGathering.FileRelationshipSettings.RecurseChildren = true;
	#Includes Library Contents to download/Checkoutsettings.OptionsRelationshipGathering.FileRelationshipSettings.IncludeLibraryContents = true;
	#Gathers the latest version of the File
	settings.OptionsRelationshipGathering.FileRelationshipSettings.VersionGatheringOption =Autodesk.DataManagement.Client.Framework.Vault.Currency.VersionGatheringOption.Latest;
	#This sets the comment that will be applied to any files that are Checked Out.settings.CheckoutComment = "Checked Out By"
	#If you want to download AND CheckOut the files use this.
	var acquisitionOption = AcquireFilesSettings.AcquisitionOption.Download | AcquireFilesSettings.AcquisitionOption.Checkout;
	#Adds a file to the list of entities to be acquired.
	settings.AddFileToAcquire(yourFileIteration, acquisitionOption);
	#Returning the AcquireFileResult
	return _vaultService.AcquireFiles(settings);

After facing some problems with the Reference Redirection (https://blog.coolorange.com/2012/09/26/reference-redirection-with-vault/) of the downloaded / checked out files i decided to handle it by myself with the UpdateRefsInLocalFile() function, which is part of the Vault API. In this example i will show how to update the References for the file and all dependedcies:

First of all to use this function you have to get the RefIds from the file Associations:

#In this case i want only the dependent children
var fileAssocs = _vaultService.GetFileAssociationsByIds(new[] { file.Id },
							FileAssociationTypeEnum.None, false,
							FileAssociationTypeEnum.Dependency, false, false, false);

Foreach association we have now to create a FileReference-Object which we have to pass later into the UpdateRefsInLocalFile() function:

#We add the File Reference to a List
var refs = new List<FileReference>();
foreach (FileAssoc fileAssoc in fileAssocs)
	var reference = new FileReference(fileAssoc.RefId, <AbsolutePath object -> Path to your local file>, fileAssoc.Source)

And finally we can Update the references:

_vaultService.UpdateRefsInLocalFile(fileIteration, <AbsolutePath object of your file>, refs);

Here the complete function, in which we have to pass the file to Update and the AcquireFilesResults from our DownloadFileAndCheckOut() function:

public void UpdateRefsInLocalFile(File file, AcquireFilesResults results)
	foreach (FileAcquisitionResult acquireFilesResult in results.FileResults)
		var fileAssocs = _vaultService.GetFileAssociationsByIds(new[] { acquireFilesResult.File.EntityIterationId },
		FileAssociationTypeEnum.None, false,
		FileAssociationTypeEnum.Dependency, false, false, false);

		if (assocs[0].FileAssocs == null)

		var refs = new List<FileReference>();
		foreach (FileAssoc fileAssoc in fileAssocs)
			var fileCld = results.FileResults.FirstOrDefault(f =&gt; f.File.EntityMasterId == fileAssoc.CldFile.MasterId);
			if (fileCld == null)
			var reference = _vaultService.GetFileReference(fileAssoc.RefId, fileCld.LocalPath, fileAssoc.Source);
		_vaultService.UpdateRefsInLocalFile(acquireFilesResult.File, acquireFilesResult.LocalPath, refs);

Here a full C# Code example:

About Manuel Lanthaler

Software Developer
This entry was posted in Vault API. Bookmark the permalink.

16 Responses to Updating References with Vault 2014 API

  1. Xavier Dumont says:


    I try this but I’m unable to fix the files.

    Do you have a c#full sample?

    We have a problem to get an assembly file from Vault through API. The reference are always broken. But if we get this manually through Vault Explorer no broken reference..

    Thanks in advance.

  2. mnav says:

    i am using ur code to update refrences after renaming a file in vault 2014 pro. it runs successfully but when i on the IAM file using Inventor it still ask to resove the renamed file.
    I am using Vault right click Rename functionality for renaming an ipt file.
    any thought or i am doing some thing wrong.


    • Xavier Dumont says:


      We discover after some test that we have to install Subsription Release in order to get files with fixed references. Maybe the last SP2 will fix this too.

  3. Gavin Bath says:

    Thanks so much! This is exactly what I was after! The documentation in the SDK is fairly thin on this subject.

  4. Matt Smith says:

    Regarding, “After facing some problems with the Reference Redirection”. What problems did you encounter?

    • Marco Mirandola says:

      as we played with redirection, it was not clear to us how the values in the Index array were generated. We started with a simple self made assembly, and the valued looked like sequential, however, trying on a larger assembly we figured out “holes/jumps” in the index numbers. Finally we realized that the Index array and the OldPath array goes hand in hand, so first OldPath/Reference has first Index, and so on. Given that we couldn’t find documentation on redirection, it was try&error. So the problem was related to the learning curve, not to function it self. btw, redirection is awesome and saved us a couple of times!!

      • Matt Smith says:

        I see. In this case, why do you do file resolution by hand (calling UpdateRefsInLocalFile). AcquireFiles is supposed to do that for you (unless you pass in false for updateFileReferences in the AcquirefilesSettings constructor).

      • Marco Mirandola says:

        by the time we wrote this post and made our tests, the references were not redirected automatically by the AcquireFiles function, at least not in our tests. That is why we ended up “forcing” the UpdateRefsInLocalFile. We will try again and see wether it’s updating the references or not.

  5. Matt Smith says:

    I see. Okay, let me know how it goes. If it is not properly let us know so that we (Autodesk) can take a look and see what is wrong. Thanks!

  6. Gavin Bath says:

    I have been having exactly the same issue and when I found your post I was very excited. I tried doing a manual Update of the references like you suggested and still have issues. I’m using Subscription Update 1. If I have any “old” data in the local Vault Working Folder and then open a drawing file in a Temporary Working Folder (entire dataset downloaded using AcquireFiles), the drawing in the temporary location STILL references the Working Folder children! Something is broken here. As soon as I delete the old data in the working folder, then the drawing file references the correct files. Weird, weird, weird. I have logged with Autodesk.

  7. Gavin Bath says:

    Check this out:
    I downloaded a dataset to a temporary location using AcquireFiles. As part of the process, I used your sample code to force the File Reference updates to match the temporary location path.
    Without opening the .idw file in Inventor, I opened it in a text editor and then translated the HEX values to text and searched it. Found the following:

    F.u.l.l.P.a.t.h.=.”.c.:.\.T.o.o.l.s.\.P.D.F.O.u.t.\.C.A.D.P.R.O.\.S.t.o.c.k. .I.t.e.m.s.\.6.3.\.…i.d.w.”. ./.>….. . …… . …… . . . …… . . . . . …… . . . . . …… . . . …… . . . …… . .

    The drawing location is correct.
    The new location value for the referenced assembly (043-00043-2800.iam) is correct, yet Inventor STILL opens it from the Old location.


  8. Uwe Handzik says:

    Hello, I’m looking for the reverse function – the references in the Vault update from an assembly file …
    (After checking in a new IAM via the API, the references must be constructed …)

Leave a Reply to Uwe Handzik Cancel 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 )

Google photo

You are commenting using your Google 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 )

Connecting to %s