Manual for module “Webservice”

In this article:

Warning

This article is under construction! Please DO NOT use any of the instructions below, yet! You may cause damage to your system. This article will be finished soon.

Authentication

Depending on the setting of the IIS application there are two possible authentication methods

  1. Windows Authentication (recommended)
  2. Authentication via firewall exception in IP base

Concept

../../_images/AutomationServiceConcept.png

The Webservice module consists of two main function: /queue and /query. Everything is accessable through a web api based on JSON format.

Queue For triggering and getting infos from (such as status) actions the /queue namespace have to be used.

All actions are created as planned actions in the SQL database table “queue”. The “Action Evaluator” asks for planned actions. If an action is found, the Wrapper.ps1 is started with the information from definition XML and passes this data to the corresponding plugin PS1.

Query For retreiving dynamic data lists /query have to be used.

Queue

Adding a queue element for executing a powershell addon script

Creating Queue element via powershell

param(
[string]$definition,
[string]$url
)

Invoke-RestMethod -Uri "$url/api/queue?definition=$definition"

Creating a plugin

For creating plugins there are several rules:

  1. Every plugin must consist of a main function (with specific parameters) which will be executed by the wrapper.ps1
  2. Every plugin must return a specific class, which will be created by GenerateResult
. "$PSScriptRoot\..\..\WrapperLib.ps1"


function RunPlugin()
{
PARAM(
[XML]$Definition,
$ctx
)
    
    Try
    {

        #Place here general plugin functions


        #Generate a plugin result:
        $result = GenerateResult -ObjectID "None" -Message "Some return description for queue result..." -Successful $TRUE

    }
    Catch
    {
    
        $ErrorMessage = $_.Exception.Message
        $result = GenerateResult -ObjectID "None" -Message "Unhandled exception thrown while running plugin: $ErrorMessage" -Successful $FALSE
   
    }

    return $result

}

For development the wrapper behaviour can be simulated by commenting out the function part, and adding the XML string directly. Once the Powershell ISE run the XML variable declaration, the XML schema is avaiable through code completion:

../../_images/CreatePlugin1.png 
. "$PSScriptRoot\..\..\WrapperLib.ps1"

#Comment out function part for development

#function RunPlugin()
#{
#PARAM(
#[XML]$Definition,
#$ctx
#)

#Add $Definition for testing purpose

$Definition = [XML]"<Definition><Plugin>TestPlugin</Plugin><Data><ExampleString>MyString</ExampleString></Data></Definition>"

$ExampleString = $Definition.Definition.Data.ExampleString

$ExampleString >> "C:\SIMTestPlugin.txt" 

$result = GenerateResult -ObjectID "None" -Message "To file C:\SIMTestPlugin.txt was written '$ExampleString'" -Successful $TRUE

return $result

#Comment out function part for development
#}

Query

Getting information from the web service.

To get data from the web service, simply the web service has the be called by GET with an URL like the following: http://SERVERNAME/APP_NAME/api/query?uniquename=TestQuery

As a result, the configured query TestQuery is executed within the web service and is returned as a JSON array:

../../_images/APITestQuery1.png

To create queries, the table [QueryLib] has to be extended by a new entry:

INSERT INTO [dbo].[QueryLib]
           ([Query]
           ,[UniqueName])
     VALUES
           ('select ''mynewqueryvar'' as var1'
           ,'mynewquery')

the query will be available by the supplied [UniqueName] value:

../../_images/QueryLibConcept.png