How to use the API

You can integrate with the Dashboard Service API through custom code, for example using C# or PowerShell to code directly to the web service or using VBA through a proxy assembly. Expand a section below to see examples for that integration method.

There are two ways to call each web service: synchronously or asynchronously. Both methods access the same underlying service, however, if you call the web service asynchronously you need to supply a call back method which will be called once the web service call returns.

  1. Add a Service Reference to your project for the Dashboard Service at https://servername/Dashboard/DashboardService.v.1.0.svc.
  2. Create a DashboardClient object for the web service.
  3. Create a CallingContext object, and add properties to identify the caller. See General API structure for details.
  4. Create an input object. For example, if you were calling SuspendDashboardDevice, you would create a SuspendDashboardDeviceInput object and specify the DeviceId property with the ID of the device you want to suspend.
  5. The next step depends on if you are calling synchronously or asynchronously.
    • Synchronously—Create a result object, for example create a SuspendDashboardDeviceResult object. Execute it with the objects created, for example DashboardService.SuspendDashboardDevice.
    • Asynchronously—Add an event handler that points to your callback function, for example dashboardService.SuspendDashboardDeviceCompleted. This callback will be called after provisioning. Execute it, for example DashboardService.SuspendDashboardDeviceAsync.
  6. Process the object for the results of the creation, for example SuspendDashboardDeviceResult.

Use the following C# example as a guideline for a synchronous call.

Copy

C# code sample

using (DashboardService.DashboardClient client= new DashboardService.DashboardClient ())
{
    callingContext callingContext = new CallingContext();
    callingContext.ContextIdentity = "someUser@someServer.com";
    callingContext.AuthenticationToken = "somePassword";
    callingContext.TokenType = AuthenticationTokenType.Password;

    SuspendDashboardDeviceInput input = new SuspendDashboardDeviceInput();
    // replace the GUID below with a valid DeviceId from your system
    input.DeviceId = Guid.Parse("a12b345c-d6a7-8901-2bcd-a34b5c6789d0");

    SuspendDashboardDeviceResult result = new SuspendDashboardDeviceResult();

    ServiceResponse serviceResponse = client.SuspendDashboardDevice(callingContext, input, out result);

    if ((serviceResponse.Status == ServiceResponseStatus.Completed) && (result.OverallStatus == OverallStatus.Success))
    {
        // operation was successful
        return true;
    }
    else
    {
        // operation failed, handled the error
        return false;
    }
}

 

You can use PowerShell to access the OpenText Core Endpoint Backup WSDL URL. Use the following PowerShell example as a guideline when creating a PowerShell script. See Sample PowerShell scripts for additional sample scripts.

Copy

PowerShell code sample

function SuspendDashboardDevice {
    param (
            [Parameter(Mandatory=$true)] $UserName               # Dashboard username
            ,$Password                                           # Dashboard password will prompt
            ,[Parameter(Mandatory=$true)] $DashboardUrl          # Dashboard URL. Example: https://vault.example.com
            ,[parameter(Mandatory = $true)] [Guid] $DeviceID     # Device ID of the device to suspend
        ) 
            if (!$Password -or ($Password -eq "*")) {
            $Password = [Runtime.InteropServices.Marshal]::PtrToStringAuto([Runtime.InteropServices.Marshal]::SecureStringToBSTR((read-host -assecurestring -Prompt "Enter the password for $UserName")))
        }
    
    # Load the WSDL 
    $proxy = New-WebServiceProxy -Uri "$DashboardUrl/Dashboard/DashboardService.v.1.0.svc?WSDL" -Namespace "DashboardServiceReference" -Class "foo"

    #Create the web service reference
    [DashboardServiceReference.SuspendDashboardDeviceResult] $result = $null
    [DashboardServiceReference.SuspendDashboardDeviceInput] $in = New-Object DashboardServiceReference.SuspendDashboardDeviceInput
    [DashboardServiceReference.CallingContext] $callingContext = New-Object DashboardServiceReference.CallingContext

    #Set up calling credentials
    $callingContext.ContextIdentity = $UserName
    $callingContext.AuthenticationToken = $Password
    $callingContext.TokenType = [DashboardServiceReference.AuthenticationTokenType]::Password
    $callingContext.TokenTypeSpecified = $true

    #Identify the device
    $in.DeviceId = $DeviceID

    # Suspend the device
    [DashboardServiceReference.ServiceResponse] $serviceResponse = $proxy.SuspendDashboardDevice($callingContext, $in, [ref] $result)
    $result
}

 

OpenText Core Endpoint Backup includes an assembly that can be loaded in Microsoft Excel or another Microsoft Office product to automate your device interaction. The assembly is DashboardApiClassLibrary.dll. Contact OpenText if you do not have this file.

Use the following as a guideline on how to access the assembly through Excel.

  1. Copy DashboardAPIClassLibrary.dll to the machine running Excel.
  2. In Excel, start the Visual Basic editor by pressing Alt-F11.
  3. In the Visual Basic editor, open a blank module by clicking Insert, Module.
  4. Add the assembly by clicking Browse, locating DashboardAPIClassLibrary.dll, and then clicking OK.

Use the following Excel script example as a guideline.

Copy

Excel code sample

Sub TestDashboardApi()
  Dim oDashboardProxy As New DashboardApiClassLibrary.Proxies
    
  Dim oServiceResponse As ServiceResponse
  Dim oResult As GetDashboardDeviceInfoResult
  Dim sUrl As String
  Rem replace “yourServer/com” in the URL with your server name
  sUrl = "http://yourServer.com/dashboard/dashboardservice.v.1.0.svc"
  
  Dim oCallingContext As New CallingContext
  Rem replace the user name and password with your user name and password
  oCallingContext.ContextIdentity = "someUserName@yourServer.com"
  oCallingContext.AuthenticationToken = "somePassword"
  oCallingContext.TokenType = AuthenticationTokenType.AuthenticationTokenType_Password
  oCallingContext.TokenTypeSpecified = "true"
  
  Dim oInput As New GetDashboardDeviceInfoInput
  oInput.WhichField = EntityInfoInputFormat.EntityInfoInputFormat_EntityIds
  oInput.WhichFieldSpecified = "true"
  
  Dim sDeviceId(0) As String
  Rem replace the GUID below with your device ID, using a GUID data type
  sDeviceId(0) = "a12b345c-d6a7-8901-2bcd-a34b5c6789d0"
    
  oInput.FieldData = sDeviceId
  
  Rem make the call
  Set oServiceResponse = oDashboardProxy.GetDashboardDeviceInfo(sUrl, oCallingContext, oInput, oResult)
  
  Rem Process the result.  Need to get the DeviceInfo array into a variant, then access the element(s)
  x = oResult.DeviceInfo
  Dim devInfo As DashboardDeviceInfo
  Set devInfo = x(0)
  
  Rem Do what you want with the information passed back.  
  Rem For this sample we just print the Device name in a message box.
  
  MsgBox devInfo.DeviceName, vbOKOnly
    
End Sub