Altium Vault SDK

Parent page: Applications and Services for Vaults

The Altium Vault Software Development Kit (SDK) provides all the resources needed to build applications that can access services hosted on the Altium Vault Server platform, such as the Altium Vault itself. The Vault and its associated services (Identity, Event, Data Acquisition and so on) can be accessed as Web Services.

The collection of Vault web services are exposed at a network level through comprehensive Application Programming Interfaces (APIs), which define an XML-based request-response message format that’s passed using HTTP as a transport mechanism. All the service functions, data and notifications are available via the APIs, allowing the Vault Server to freely communicate and interact with other systems over conventional networks.

The Vault SDK allows developers to harness this capability by building custom software applications using Microsoft C# and the SDK’s resources, class assemblies and example projects. While the service API’s message protocols are independent of application development languages (programmatically neutral), the SDK has been implemented for Microsoft’s C# language and .NET Framework to streamline and simplify the development of web service applications.

Ultimately, the Vault SDK is ideal for developing applications and interfaces that enable interactive communication between the server's hosted services and existing enterprise systems. For example the Vault’s advanced content management system and its inherent association with Altium Designer can be hooked in to company systems at any level, and potentially, at any remote location.

Vault as a Web Service

The core service hosted on the Vault Server platform is the Altium Vault. This server-based software application is typically installed to be accessible via a company's LAN, where it remotely stores and manages electronic design data, from components through to loaded circuit board modules. It provides high-integrity storage, formal revision management and configurable lifecycle management. With its associated Identity service the Vault provides full control over user authentication, and is designed for providing data management and collaboration to design, procurement and production teams.

When implemented, the Vault service provides authenticated (but limited) Java-based access to a standard web browser, and full interactive access to Altium Designer over the network via HTTP. In essence, these full capabilities are also exposed via the Vault API to enable the Vault as a Web Service at a defined network address.

When subsequently exposed to the broader network, the Vault and its associated services are available to any authorized system that can communicate using the defined protocols. Using applications or interfaces developed using the Altium Vault SDK, this could be any company system - from a simple part catalog database, right through to enterprise PLM, ERP and MRP systems.

To allow this high level of interaction the Vault host platform (the Vault Server) exposes APIs, with their respective request-response messages, for a range of advanced services such as:

• The IDS (Identity) service - for managing user identity authentication
• The Vault service - the main access to the Vault repository and its functions
• The Part Catalog service - for interfacing with Vault’s associated Part Catalog
• The EDS (Event Dispatch) service - for monitoring and configuring Vault event notifications
• The Data Acquisition service - for transferring, or acquiring, Vault Items from another Vault
• ...plus many more.

Message protocols

At a functional level the Vault Server web services communicate with connected systems using HTTP (the venerable TCP/IP-based Internet protocol) as a transport layer, and the XML-based Simple Object Access Protocol (SOAP) message format.

Interaction between the Vault Server (hosting the Vault services) and a remote
application is through existing network paths, using standard HTTP methods.

SOAP Requests

The Vault Server service APIs, such as that of the Vault, define request and expected response messages in the human-readable SOAP format. In simple terms, a Web Service takes a SOAP request formatted as XML, performs a particular function, and then returns a response to the requester as a SOAP XML message. Messages are typically instigated using a standard HTTP POST or GET method.

For example, the following is a simple SOAP request that tests the connection to the Altium Vault:

<s:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/xmlns:tem="http://tempuri.org/"">
   <s:header>
      <apiversion>2.0</apiversion>
   </s:header>
   <s:body>
      <tem:testconnection>
      </tem:testconnection>
   </s:body>
</s:envelope>

The Vault API response message confirms the connection by returning the current server time:

<!--?xml version="1.0" encoding="utf-8"?-->
<soap-env:envelope xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soap-env:body xmlns="http://tempuri.org/">
      <testconnectionresponse>
         <servertime>2013-08-11T16:59:23.421Z</servertime>
      </testconnectionresponse>
   </soap-env:body>
</soap-env:envelope>

HTTP Headers

Web service SOAP messages are preceded by a corresponding HTTP header message, as generated by the transmitting application or service that binds to the message target.

For the above TestConnection request, when using an application developed with the Vault SDK, this header would typically be:

POST http://localhost:9780/ids/?cls=soap HTTP/1.1
Content-Type: text/xml; charset=utf-8
SOAPAction: "TestConnection"
Host: localhost:9780
Content-Length: 274
Expect: 100-continue
Connection: Keep-Alive

The response header returned by the Vault service would be:

HTTP/1.0 200 OK
Last-Modified: Tue, 13 Aug 2013 01:16:38 GMT
Cache-Control: no-store
Allow: Post
Content-Type: text/xml
Content: 
Content-Length: 455

A quick DIY

In the very simplest sense, a basic (but valid) SOAP request can be sent to the Vault service using just a few lines of JavaScript code.

Since recent browsers (IE7+, Firefox, Chrome, Safari, Opera etc) have a built-in XMLHttpRequest object, a simple HTTP POST method statement will send included SOAP data to the designated URL. In the case shown below, the Vault Identity service (at the localhost address) will receive the XML SOAP string held in the postData variable.

<script>
var postData = "<s:Envelope xmlns:soapenv=\"http://schemas.xmlsoap.org/soap/envelope/\" xmlns:tem=\"http://tempuri.org/\"><s:Header><APIVersion>1.0.0</APIVersion></s:Header><s:Body><tem:TestConnection/></s:Body></s:Envelope>";
var requ = new XMLHttpRequest();
requ.open('POST', "http://localhost:9780/ids/?cls=soap", true);
requ.send(postData);
</script>

For the above script the browser will automatically generate a suitable header to precede the SOAP request message. The Vault IDS will regard the transmission as a valid request, and respond accordingly with a SOAP response containing the server time - see below. This test script is functionally equivalent to the SOAP Requests example outlined above.

Note that this simple JavaScript example makes no attempt to capture and read the response returned by the Vault, but this could be easily observed using a HTTP debugger application.

Below is the response captured by Fiddler, shown in Raw text format:

<?xml version="1.0" encoding="utf-8"?>
   <SOAP-ENV:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
      <SOAP-ENV:Body xmlns="http://tempuri.org/">
         <TestConnectionResponse>
            <ServerTime>2014-08-19T05:04:14.654Z</ServerTime>
         </TestConnectionResponse>
      </SOAP-ENV:Body>
   </SOAP-ENV:Envelope>

Rather than being restrained by a script language for the task however, the Vault Server SDK targets Microsoft™ C# (C sharp) as the development language of choice by providing suitable assembly classes and working examples in C#.

Developing applications with the SDK

The Vault Server SDK installs from a small executable  (Altium Vault SDK <VersionNumber>.exe) that will install the SDK into a directory or your choice - the default is \Program Files (x86)\Altium\Altium Vault\SDK. The SDK is implemented as a set of development resources in a directory structure that delineates the individual resources - namely, \examples, \bin, \wsdl etc sub-directories in the install location.

Visual Studio IDE

For creating applications and services using C# and the Vault Server SDK, the recommended integrated development environment (IDE) is Microsoft Visual Studio™ 2010 or newer. Visual Studio applies the C# language, the .NET Framework and external class libraries in a singular development environment for creating applications that can access the Vault Server's hosted Web Services.

Microsoft’s .NET Framework, installed in conjunction with Visual Studio, includes a set of standard class libraries with each organized in a hierarchy of namespaces. Along with base classes, the Framework includes an extended set of libraries such as Windows Forms, ASP.NET (targeted at server-side web development), and Windows Communication Foundation (WCF), amongst others.

The WCF set of classes is particularly suited to developing web services with the Vault SDK. WCF can be applied to easily implement SOAP-based Web services (SOAP over HTTP) that include cross-platform security, reliability, transactions, etc. Inherent capabilities include a set of predefined bindings (such as BasicHttpBinding), XML optimization, XML serialization / de-serialization (for processing XML-based SOAP messages), endpoints (service URIs) and much more.

A Vault Server SDK example project open in the Visual Studio IDE.

Using the SDK examples

With Visual Studio installed, a good place to start with developing SDK applications is to load, examine and build the supplied C # examples, available in the \Altium Vault\SDK\examples directory or the equivalent custom location.

Ensure that the Altium Vault is installed and configured, note its host address (usually http://localhost:9780 or equivalent) then open an example project in Visual Studio. The examples can be compiled (using the Build menu) to create a Windows executable application in the \Altium Vault\SDK\examples\xxx\bin\Debug directory, where xxx is the example project directory.

Assuming a successful build, run the example executable to see how it interacts with the Vault services.

Resolving system issues

In the event of an example project build error there are a couple of initial considerations to pursue. The most likely issue preventing a successful build will be the configuration of your operating system’s file and folder write permissions. When building a project, Visual Studio will update a number of files in the source directory and attempt to create the project executable in the appropriate sub-folder - this may well violate your system's permission constraints.

A typical Windows 7 install, for example, will default to preventing unauthorized (or unconfirmed) changes to most system or program folders. This could be resolved by reducing the system notification level setting in Windows' User Account Control (UAC), but this arguably imposes a system-wide security risk.

In practice, the best way to prevent a Visual Studio build error due to folder write permission failures is to host the Vault SDK in an accessible directory, such as C:\Users\<ProfileName>\Documents.

Additionally, you may need to run Visual Studio with elevated privileges to guarantee a successful build. For Windows 7 or later operating systems, run Visual Studio as an administrator by right clicking on its entry (in the Start menu or programs listing) and selecting Run as Administrator.

To always launch Visual Studio as an administrator, create a shortcut, open its properties (accessed by right clicking) and check the Run this program as an administrator check box under the Compatibility tab.

Monitor and Debug HTTP traffic

To examine how an application is interacting with a web service at a live HTTP level, the ability to view the bidirectional exchange of SOAP messages can be invaluable. As the transactions occurring over HTTP exist outside an application developed with the SDK, they are largely invisible to normal software debugging/examination methods.

Web debugging software fills that void by implementing a proxy server to capture and log the traffic through a nominated network path. Normally configured to redirect HTTP transactions (such as those between a web service and a client application) through its own proxy server, a web debugger exposes the nuts and bolts of a web service SOAP request/response communications. You can log and browse through HTTP messages, and even save sessions for later examination.

To try a low cost (or free) web debugger, take a look at:

• Fiddler web debugging proxy
• Charles web debugging proxy

Monitoring messages for existing applications, such as the interaction between Altium Designer (or the example projects) and the Vault services can be very helpful when developing your own web service applications. Note that SOAP messages follow a standard format that involves:

• an outer envelope that identifies the XML as a SOAP message
• a body section that contains the main payload
• a header section for additional information about the message or transaction (optional).

For messages sent to the Vault Server and its services, the header typically contains an API Version string. Information passed in the header section is not necessarily an operative part of the message.

The body is the active part of the message and is based on a requested operation name (such as Login or AddFolder) that matches the server-side method name being called. The children of this operation name are elements whose own names match the parameters of the requested operation: (GUID and HRID identifiers, a creation date, access rights, and so on).

For all but initial Login and Test messages, a Vault service request message will include a SessionHandle GUID string that identifies the currently connected session - this is normally established at Login, and then resent as session validation during subsequent requests to the server.

Altium Vault structure

The highest level structure in the Vault service is folders and sub-folders in the conventional sense. These are typically organized in logical zones that reflect the intended content and its purpose, such as Components , Templates, or Projects, and form a hierarchical tree structure. A number of predefined folder types are available, but any folder structure and naming convention can be used.

In turn, each folder and sub-folder contains Items. Items are a key element in the Vault's data management structure, and are in effect containers for a range of data that defines that Item. Items are released into the Vault (typically from the design domain; Altium Designer) as named revisions of design data. Each has a unique name and Item ID, and are stored as a sequence of incremental revisions as new updates are released to the Vault.

Being design entities, Items would typically fall into the type categories such as Models, Components, Managed Schematic Sheets, and Design Projects. However the type definition of an Item is in fact open-ended, so custom types can be created for specialized data that may not be directly related to electronics design.

Revisions and Lifecycle

Vault Items have a rich set of properties that fall under a set of defined, but configurable, conventions. Revisions for example can be predefined with a simple through to complex naming scheme (implemented as revision name suffixes), adding increasing levels of depth to the possible revision levels. An item's Revision Naming Scheme is locked to the setting that was defined when the Item was first created - this applies to a particular Item and its subsequent series of revisions, whereas newly created Items can take on any naming scheme.

Item Revisions are also lifecycle managed, allowing the maturity (and therefore usability) of the design data to be defined over time. Revision lifecycles typically move through Stages (such as Design, Prototype and Production) and have specific lifecycle States, such as New From Design, For Prototype, Deprecated, Abandoned etc. The possible Stages and individual States are both determined by the Item's Lifecycle Definition, as are the possible transitions between Stages. Lifecycle Definitions can be configured to simple or advanced levels of detail, and again, are locked when the Item is first defined.

Note that when developing SDK applications to access the Vault web service, reading the Revision Schemes and Lifecycle Definitions for a Vault Item is an essential preliminary to managing its Revisions or changing a Revision's lifecycle state. The Schemes and Definitions ultimately determine what changes are possible and how they are defined.

Access permissions

One of the advantages of grouping Vault content structure in a relatively straightforward folder tree arrangement is that specific zones, and therefore content type, can be selectively shared with others through folder permissions. An authorized administrator can share individual folders and Items at a series of permission levels that govern read/write access and visibility.

At a full (enterprise style) level, only those users that have been expressly granted access to a folder or Item have the ability to see (read) its content, but not write into it. Moving down the scale, definable permissions can be set for read/write access by roles, and finally, for full public visibility. In terms of the Vault API, permissions are expressed as integers and boolean levels.

Other Vault services

Along with the Vault service itself, SDK-developed applications can also access the diverse range of Altium services hosted by the Vault Server. For more information on these function-specific services, see the Altium Vault documentation.

SDK examples

The C# example projects included in the Altium Vault SDK provide helpful reference information for developing your own web service applications. They can be found in the \Altium Vault\SDK\examples directory and can be loaded directly into Visual Studio by opening each example's project file (*.csproj).

One of the first things you will probably notice about the Vault SDK examples is the relatively simple structure of the elements that make up each example. This basically involves:

• a main Program file (including the required main() class)
• form files (defining Windows dialogs and their actions) if the example has a user interface (UI).
• a range of loaded Class Assemblies (class libraries) under References in the Solution Explorer tree.

Most of the loaded Class Assemblies are from the .NET Framework class library, and predominantly from System namespace. The .NET Framework is a natural fit for developing SOAP XML-based web services, and its class assemblies take the hard work out of tasks like handling XML schema and providing runtime serialization.

Some of the notable class libraries, loaded as assemblies, are:

• System.XML namespace - support for processing XML, XML namespaces and schema
• System.XML.Linq namespace - load and manipulate XML files
• System.Runtime.Serialization - serialize and de-serialize objects

Also included are the open-source class library packages:

• Ionic.Zip.Reduced.dll - for building compressed binary XLM file streams, from DotNetZip
• INIFileParser.dll - a file parser for reading, editing and creating INI files

DXP Services class assembly

When it comes to developing applications for the Vault and its associated services hosted on the Vault Server, the key class assembly is the compiled DxpServerSDK assembly.

The DxpServerSDK assembly includes these accessible namespaces:

• Altium.Sdk.DxpAppServer
• Altium.Sdk.DxpAppServer.AppRegistryServiceProxy
• Altium.Sdk.DxpAppServer.CloudVcsServiceProxy
• Altium.Sdk.DxpAppServer.CommentsServiceProxy
• Altium.Sdk.DxpAppServer.DataAcquisitionServiceProxy
• Altium.Sdk.DxpAppServer.DataStorageServiceProxy
• Altium.Sdk.DxpAppServer.EDSServiceProxy
• Altium.Sdk.DxpAppServer.IdsNtlmServiceProxy
• Altium.Sdk.DxpAppServer.IDSServiceProxy
• Altium.Sdk.DxpAppServer.LMServiceProxy
• Altium.Sdk.DxpAppServer.NisServiceProxy
• Altium.Sdk.DxpAppServer.NotificationsServiceProxy
• Altium.Sdk.DxpAppServer.PartCatalog2ServiceProxy
• Altium.Sdk.DxpAppServer.PartCatalogServiceProxy
• Altium.Sdk.DxpAppServer.PlmSyncServiceProxy
• Altium.Sdk.DxpAppServer.ProjectsProxy
• Altium.Sdk.DxpAppServer.PushNotificationsProxy
• Altium.Sdk.DxpAppServer.SearchServiceProxy
• Altium.Sdk.DxpAppServer.SearchTemplatesServiceProxy
• Altium.Sdk.DxpAppServer.SecurityServiceProxy
• Altium.Sdk.DxpAppServer.SettingsServiceProxy
• Altium.Sdk.DxpAppServer.ServiceDiscoveryProxy
• Altium.Sdk.DxpAppServer.SLSServiceProxy
• Altium.Sdk.DxpAppServer.TasksServiceProxy
• Altium.Sdk.DxpAppServer.TC2ServiceProxy
• Altium.Sdk.DxpAppServer.VaultServiceProxy
• Altium.Sdk.DxpAppServer.VcsServiceProxy

The namespaces correspond to the fundamental Vault services hosted on the Vault Server. They contain hundreds of member classes, interfaces and structures, but are arranged with a high degree of class inheritance to simplify operations.

Ultimately, the DxpServerSDK assembly is the go-to resource for creating applications and interfaces for the Vault web services. It’s loaded as a resource in all example projects and can be found in each example project's bin\Debug directory (DxpServerSDK.dll), along with any required libraries that are not included in the .NET Framework. These are also included in the install's \Altium Vault\SDK\bin directory.

Example projects

The Vault SDK installation contains a selection of example projects that can be examined, compiled and run as Windows executables.

The current collection of examples include C# projects that demonstrate a number of key capabilities of the Vault Server and its hosted services, such as:

• Implementing specialized content types, such as a Bridge-Item
• Enabling and configuring Vault Event Notifications
• Instigating a Item Lifecycle change from an external event