These API are primarily for integration with Shopping.

You can extend AppClarity to interact with external systems with these APIs. The APIs are REST-based HTTP services implemented with .NET Framework Windows Communication Foundation (WCF). To test that integration services is enabled, type the URL for the API into a browser – by default, the response will be returned as XML.

Using C# and linking to the API dll

You can use C# to link to the API dll to integrate with the service. This will enable you to write code against the API similar to calling a native method – no XML parsing or HTTP code is required.

For example, you can call the WCF service to read XML elements. The most important part in the code is the creation of the channel factory.

var factory = new ChannelFactory<ISoftwareReclaimerService>(binding, AppclarityServiceUri);
factory.Endpoint.Behaviors.Add(new WebHttpBehavior());
var proxy = factory.CreateChannel();

The proxy object gives access to the methods provided by the ISoftwareReclaimerService interface. In the example, the items in the policy history are read:

var history = proxy.GetMachinePolicyHistoryUninstalled(machineHistoryStartDate.ToString("s"));

The machineHistoryStartDate variable indicates the start date from which on the history is collected. The call returns a collection of all history items after the start date which must be formatted as (YYYY-MM-DD'T'HH.MM.SS). This example iterates over these items and and prints the values to the console.

To compile the program, you must reference the API dll. There is already an import for this DLL in the code that points to its location. This must be included as reference in the project.

using N1E.AppClarity.Api.SoftwareReclaimer; //find this in %Program Files (x86)%\1E\AppClarity\Coordinator\N1E.AppClarity.Api.dll

Using VBScript to call the APIs

You can also use VBScript and MSXML to retrieve the software reclaim history.

For example, here is some abbreviated code:

Set xmlDoc = CreateObject( "Microsoft.XMLDOM" )
xmlDoc.Async = "False"

If xmlDoc.Load ("http://localhost:8335/appclarity/services/integration/softwarereclaimer/history/uninstalled?completedOnOrAfter=2012-08-01T00:00:00") Then
Dim nodeList
    Set nodeList = xmlDoc.SelectNodes("MachinePolicyHistory/HistoryItems/MachinePolicyHistoryItem")
    Dim node
    For Each node In nodeList
        ' Print out CompletedDate, etc
        CompletedDate = node.selectSingleNode("CompletedDate").text
        WScript.Echo CompletedDate
End If

Integration services

For security, integration services can only be by AppClarity users. It uses Windows authentication and users must be granted permissions to use it. Integration APIs protect integration code from implementation changes between versions of AppClarity. In summary, for a user to access integration services:

The user must be a a valid Windows user who can be authenticated in the domain in which the AppClarity service is running

The user must have permission to use integration services. You can grant permission to use this feature in the Permissions tab on the User screen in the Console by checking the User can access Integration Services checkbox.

If authentication fails, the service returns a 403 (Forbidden) response.

Enabling third party integration

To enable third party integration AppClarity provides the following libraries: