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.
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:
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.
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>
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
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
<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.
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#.
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,
\wsdl etc sub-directories in the install location.
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.
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.
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
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.
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:
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:
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
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.
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.
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.
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.
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.
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 (
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:
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:
Also included are the open-source class library packages:
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:
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
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: