Entwicklung eines ACMP Connectors für die ISS

In diesem Best Practice möchten wir Ihnen anhand der Entwicklung eines ACMP Connectors aufzeigen, wie Sie PowerShell-Microservices für Ihre eigenen Projekte entwickeln und nutzen können. Als Beispiel-Projekt wird zur Veranschaulichung ein Connector entwickelt, mit dem die aktuellen Informationen zur Internationalen Raumstation (ISS) aus der öffentlichen REST API [[https:~~/~~/wheretheiss.at>>url:https://wheretheiss.at/]] abgerufen und über die ACMP Public API als Asset im ACMP angelegt bzw. aktualisiert werden. Ziel ist es, die Positions- und Statusdaten der ISS regelmäßig zu synchronisieren und damit immer auf die aktuellen Informationen im System zugreifen zu können.

4

5

6

Am Ende des Best Practice finden Sie das Verzeichnis ISSACMPConnector.zip mit allen Dateien dieses ACMP Connectors zum Herunterladen.

7

8

9

= Entwicklungsumgebung =

10

11

Als Entwicklungsumgebung für die Umsetzung dieses Beispiel-Projekts benötigen Sie:

12

13

* Eine aktuelle Version von Visual Studio Code

14

* Eine installierte PowerShell-Erweiterung in Visual Studio Code

15

* Eine installierte AESB Shell

16

* Eine erreichbare AESB Console

17

18

== Entwicklungsumgebung einrichten ==

19

20

Sofern Sie Visual Studio Code mit der PowerShell-Erweiterung noch nicht installiert haben, befolgen Sie zunächst [[die Installationsanleitung von Microsoft>>https://learn.microsoft.com/de-de/powershell/scripting/dev-cross-plat/vscode/using-vscode?view=powershell-7.4#install-vs-code-and-the-powershell-extension]].

21

22

Wenn Sie Visual Studio Code mit der PowerShell-Erweiterung installiert haben, können Sie die AESB Shell in Visual Studio Code einrichten:

23

24

1. Legen Sie einen neuen Ordner mit dem Namen //ISSACMPConnector// im Datei-Explorer an.

25

1. Klicken Sie mit einem Rechtsklick auf den neuen Ordner, um das Kontextmenü zu öffnen.

26

1. Wählen Sie im Kontextmenü den Eintrag //Mit Code öffnen //aus, damit direkt das richtige Verzeichnis geöffnet wird.

27

1. Erstellen Sie eine neue Datei mit der Endung **//.psm1 //**(z.B. Modul.psm1). Bei dieser Datei handelt es sich um ein PowerShell-Modul, in dem nun die Businesslogik implementiert werden kann.{{aagon.infobox}}Das Erstellen dieser Datei ist notwendig, damit eine PowerShell-Session mit dem Terminal in Visual Studio Code geöffnet wird.{{/aagon.infobox}}

28

1. Geben Sie im Terminal den Befehl //{{code language="PowerShell"}}code $profile{{/code}} //ein und bestätigen Sie mit der Eingabetaste. Nun öffnet sich die Datei //Microsoft.VSCode_profile.ps1//,// //mit der Sie das verwendete PowerShell-Profil anpassen können.

29

1. Fügen Sie den nachfolgenden Code in die Datei //Microsoft.VSCode_profile.ps1// ein. Beachten Sie, dass der angegebene Pfad für die AESB Shell korrekt ist.

30

1. Drücken Sie Strg + S, um die Datei zu speichern.

31

1. Starten Sie Visual Studio Code anschließend neu.

32

33

{{code language="PowerShell" layout="LINENUMBERS" title="**Code für Microsoft.VSCode_profile.ps1**"}}

34

try {

35

$aesbShellPath = "C:\Program Files (x86)\Aagon\AESB Shell"

36

[System.Environment]::CurrentDirectory = $aesbShellPath

37

Import-Module "$aesbShellPath\Aagon.Shell.Core.dll", "$aesbShellPath\Aagon.Sis.Sics.Powershell.Cmdlets.dll" -Prefix AESB -Force -Global

New-AESBShell

}

catch {

Write-Error "No AESBShell installed!"

}

[[AESB Shell in Visual Studio Code einrichten>>image:Visual Studio Code einrichten.png||alt="AESB Shell in Visual Studio Code einrichten"]]

46

47

Als Ergebnis wird in Visual Studio Code im Terminal-Bereich nun direkt die AESB Shell geladen. So können Sie ab jetzt einfach und effektiv neue Module entwickeln, um diese später in den Microservices zu nutzen.

48

49

[[Geladene AESB Shell in Visual Studio Code>>image:Visual Studio Code_AESB Shell.png||alt="Geladene AESB Shell in Visual Studio Code"]]

= Aufgabenteilung =

Das Ziel der Aufgabenteilung ist es, die Hauptaufgabe auf kleinere Services aufzuteilen und damit zu modularisieren. Jeder Service soll dabei nur eine spezifische Funktion übernehmen. Somit wird gewährleistet, dass die verschiedenen Services unabhängig voneinander laufen.

55

56

Die Hauptaufgabe des ACMP Connector für die ISS ist es, die aktuellen Informationen zur Internationalen Raumstation (ISS) aus der öffentlichen REST API [[https:~~/~~/wheretheiss.at>>url:https://wheretheiss.at/]] abzurufen und über die ACMP Public API als Asset in dem ACMP anzulegen bzw. zu aktualisieren. Anhand dieser kurzen Projektdefinition lässt sich in diesem Beispiel erkennen, dass es zwei Teilaufgaben gibt: Erstens das Abrufen der Daten von der REST API und zweitens die Integration der bereitgestellten Daten in ACMP. Für jede Teilaufgabe wird ein eigener Service bzw. Microservice definiert:

57

58

1. **Microservice 1: Datenabruf von der REST API **

59

Der erste Service ruft die ISS-Daten (z.B. Position, Höhe, Geschwindigkeit) von der API ab und sendet diese an den zweiten Microservice.

60

1. **Microservice 2: Integration in ACMP**

61

Der zweite Service liest die vom ersten Service bereitgestellten Daten und überträgt sie mithilfe der Public API an den ACMP. Dabei wird entweder ein neues Asset für die ISS erstellt oder ein bestehendes Asset aktualisiert.

62

63

[[Schematische Darstellung der aufgeteilten Services für den ACMP Connector für ISS-Daten>>image:Schema_ISS Connector_Microservices.png||alt="Schematische Darstellung der aufgeteilten Services für den ACMP Connector für ISS-Daten" data-xwiki-image-style-alignment="center" height="360" width="800"]]

= Vorbereitungen =

Nachdem die Hauptaufgabe aufgeteilt und die modularen Microservices für die einzelnen Aufgaben definiert wurden, ist es ggf. notwendig, das bestehende System vorzubereiten. In diesem Beispiel müssen für ACMP als das bestehende System, in das die Daten integriert werden sollen, einige Ressourcen neu angelegt werden. Das ist notwendig, damit Sie bei der anschließenden Entwicklung der Microservices direkt auf die Ressourcen zugreifen können.

68

69

Die Daten für die ISS sollen in ACMP im Asset Management einem Asset hinzugefügt werden. Da es bislang allerdings keinen Assettypen für eine Raumstation gibt, muss dieser erst angelegt werden. Außerdem werden für die Daten der Raumstation neue benutzerdefinierte Felder benötigt, die ebenfalls erst angelegt werden müssen. So können Sie die Datenfelder dann direkt bei der Erstellung des neuen Assettypen hinzufügen.

70

71

== Benutzerdefinierte Felder erstellen ==

72

73

Für die Erfassung von den Daten der Raumstation werden vier neue benutzerdefinierte Felder benötigt: //Latitude, Longitude, Altitude// und //Velocity//. Gehen Sie folgendermaßen vor, um das benutzerdefinierte Feld //Latitude// anzulegen:

74

75

1. Öffnen Sie die ACMP Console und navigieren Sie zur Solution //System > Einstellungen > Benutzerdefinierte Felder > Assets.//

76

1. Klicken Sie mit einem Rechtsklick auf den Ordner //Custom Fields //und wählen Sie den Eintrag //Tabelle hinzufügen// aus (Umschalt+Alt+N).

77

1. Ändern Sie den Namen der neuen Tabelle zu //Spacestation //und bestätigen Sie die Erstellung mit dem Button //Fertig//.

78

1. Klicken Sie mit einem Rechtsklick auf die Tabelle //Spacestation// und wählen Sie den Eintrag //Feld hinzufügen// aus (Strg+N).

79

1. Ändern Sie den Namen in //Latitude //und klicken Sie auf den Button //Weiter.//

80

1. Legen Sie als Feldtyp die Option //Text// fest und ändern Sie den Wert der Feldgröße auf 50.

81

1. Bestätigen Sie die Erstellung des Feldes mit dem Button //Fertig.//

82

1. Wiederholen Sie Schritt 4 bis Schritt 7 für die weiteren Datenfelder.

83

1. Klicken Sie abschließend in der Ribbonleiste auf den Button //Speichern.//

84

85

[[Benutzerdefinierte Felder für die ISS-Daten>>image:Benutzerdefinierte Felder_ISS Connector.png||alt="Benutzerdefinierte Felder für die ISS-Daten"]]

86

87

== Assettypen erstellen ==

88

89

Nun können Sie den benötigten Assettypen erstellen:

90

91

1. Navigieren Sie in der ACMP Console zur Solution //Asset Management > Hardware Assets.//

92

1. Klicken Sie in der Ribbonleiste auf den Button //Assettypen.//

93

1. Klicken Sie im Dialogfenster auf den Button //Assettypen hinzufügen.//

94

1. Wählen Sie im Dialogfenster als Zielordner //Hauptebene// aus und ändern Sie den Namen in //Spacestation.//

95

1. Klicken Sie zwei Mal auf den Button //Weiter//, um Schritt 3 //Benutzerdefinierte Felder //zu öffnen.

96

1. Öffnen Sie den Ordner //Custom Fields// und ziehen Sie die Tabelle //Spacestation// per Drag-and-Drop in das rechte Fenster.

97

1. Klicken Sie auf den Button //Fertig//.

98

99

Der Assettyp //Spacestation //ist nun in der Liste verfügbar und hat die entsprechenden benutzerdefinierten Felder.

100

101

[[Neuer Assettyp mit benutzerdefinierten Feldern für die ISS-Daten>>image:Assettyp_ISS Connector.png]]

102

103

== IDs der benutzerdefinierten Felder abfragen ==

104

105

Für die spätere Konfiguration der Microservices benötigen Sie die IDs des Assettyps und der benutzerdefinierten Felder.

106

107

= Entwicklung der Microservices =

108

109

Die Entwicklung der PowerShell-Microservices stellt den umfangreichsten Teil bei der Entwicklung dieses ACMP Connectors dar. Für die Entwicklung wird die eingangs beschriebene [[Entwicklungsumgebung >>doc:||anchor="HEntwicklungsumgebung"]]benötigt. Zur Sicherstellung eine sauberen, modularen und effizienten Umsetzung, wird für die Entwicklung von PowerShell-Microservices folgende Vorgehensweise empfohlen:

110

111

1. Erstellen der PowerShell-Module

112

1. Testen der PowerShell-Module

113

1. Erstellen der PowerShell-Microservices in AESB

114

1. Integrieren der PowerShell-Module in die PowerShell-Microservices

115

116

== PowerShell-Module erstellen ==

117

118

Zu Beginn werden die einzelnen PowerShell-Module entwickelt, welche die benötigte Logik für die Microservices enthalten. Für den ACMP Connector in diesem Beispiel werden folgende Module benötigt:

119

120

* ISSRestConnector - Modul zum Abfragen der ISS-Daten

121

* ISSAssetImporter - Modul zum Speichern des Assets und der zugehörigen Custom Fields

122

123

=== **ISSRestConnector** ===

124

125

Das Modul zum Abfragen der ISS-Daten besteht aus einer einfachen Funktion, welche die REST API aufruft und das Ergebnis in ein PSCustomObject konvertiert.

126

127

1. Klicken Sie mit einem Rechtsklick auf den Ordner //ISS_ACMP_Connector//, um das Kontextmenü zu öffnen.

128

1. Wählen Sie im Kontextmenü den Eintrag //Mit Code öffnen //aus, damit direkt das richtige Verzeichnis geöffnet wird.

129

1. Erstellen Sie einen neuen Unterordner mit dem Namen //Modules.//

130

1. Erstellen Sie im Unterordner //Modules //eine neue Datei mit dem Namen //ISSRestConnector.psm1//. Alternativ können Sie auch die anfangs erstellte, leere Datei //Modul.psm1// umbenennen und in den Ordner verschieben.

131

1. Fügen Sie den nachfolgenden Code in die Datei ein.

132

1. Drücken Sie Strg + S, um die Datei zu speichern.

133

134

{{code language="PowerShell" layout="LINENUMBERS" title="**ISSRestConnector.psm1**"}}

135

function Get-ISSData {

136

<#

137

.SYNOPSIS

138

Queries the "Where the ISS at?" API to retrieve satellite data.

139

140

.DESCRIPTION

141

This function fetches the data for the International Space Station (ISS) from the REST API endpoint

142

https://api.wheretheiss.at/v1/satellites/25544 and returns the parsed response.

143

144

.OUTPUTS

145

[PSCustomObject] - A custom object containing the ISS data.

.EXAMPLE

Get-ISSData

# Retrieves the current data for the ISS.

#>

param (

[string]$ApiUrl = "https://api.wheretheiss.at/v1/satellites/25544"

)

try {

# Perform the API request

158

$response = Invoke-RestMethod -Uri $ApiUrl -Method Get

159

160

# Convert the response into a PowerShell object

161

$result = [PSCustomObject]@{

162

Name = $response.name

163

Latitude = $response.latitude.ToString()

164

Longitude = $response.longitude.ToString()

165

Altitude = $response.altitude.ToString()

166

Velocity = $response.velocity.ToString()

}

return $result

} catch {

Write-Error "Failed to fetch ISS data: $_"

}

}

=== **ISSAssetImporter** ===

177

178

Das Modul zum Speichern des Assets und der zugehörigen Custom Fields erstellt das Asset für die ISS, falls es noch nicht vorhanden ist. Außerdem konvertiert es das PSCustomObject zurück in ein integrierbares Datenformat.

179

180

1. Erstellen Sie im Unterordner //Modules //eine neue Datei mit dem Namen //ISSAssetImporter.psm1//.

181

1. Fügen Sie den nachfolgenden Code in die Datei ein.

182

1. Drücken Sie Strg + S, um die Datei zu speichern.

183

184

{{code language="PowerShell" layout="LINENUMBERS" title="**ISSAssetImporter.psm1**"}}

185

function Get-AssetTypeId {

186

param (

187

[string] $AssetTypeName

188

)

189

$assetTypesResult = Acmp-GetAssetTypeList_V1

190

if ($assetTypesResult.ResultCode -ne 0) {

191

Throw "Error while fetching asset types: $($assetTypesResult.ResultMessage)"

192

}

193

$assetType = $assetTypesResult.AssetTypes | Where-Object { $_.Name -eq $assetTypeName }

194

$id = [guid]::Parse($assetType.Id).ToString()

Write-Output $id

}

function New-ISSAsset {

199

param (

200

[PSCustomObject] $Data,

201

[string] $AssetTypeId,

202

[string] $AssetTypeName,

203

[string] $AssetStateId

204

)

205

$newAsset = New-TAsset_V4

206

$newAsset.Id = [guid]::NewGuid().ToString()

207

$newAsset.Name = $Data.Name

208

$newAsset.AssetType = $AssetTypeName

209

$newAsset.AssetTypeId = $AssetTypeId

210

$newAsset.AssetStateId = $AssetStateId

211

212

Write-Output $newAsset

213

}

214

215

function Get-ISSAsset {

216

param(

217

[string] $AssetTypeId,

218

[string] $AssetTypeName,

219

[string] $AssetStateId,

220

$ISS

221

)

222

$assetListResult = Acmp-GetAssetList_V3 -AssetTypeId $AssetTypeId -FilterText "iss"

223

if ($assetListResult.ResultCode -ne 0) {

224

Throw "Error while fetching the asset: $($assetListResult.ResultMessage)"

225

}

226

$assetInfo = $assetListResult.Assets | Where-Object { $_.Name -eq $ISS.Name }

227

if ($null -eq $assetInfo) {

228

$asset = New-ISSAsset -Data $ISS -AssetTypeName $AssetTypeName -AssetTypeId $AssetTypeId -AssetStateId $AssetStateId

229

}

230

else {

231

$assetResult = Acmp-GetAsset_V4 -Id $assetInfo.Id

232

if ($assetResult.ResultCode -ne 0) {

233

Throw "Error while fetching the asset: $($assetResult.ResultMessage)"

234

}

235

$asset = $assetResult.Asset

}

Write-Output $asset

}

function New-CustomField {

param (

[string] $Id,

[string] $Value

)

$customfield = New-TCustomFieldValue_V1

246

$customfield.FieldId = $Id

247

$customfield.Value = $Value

248

249

Write-Output $customfield

250

}

251

252

function Save-CustomFieldList {

param (

$AssetId,

$CustomFieldList

)

$customFieldResult = Acmp-SaveSingleCustomFieldValues_V1 -QueryBase AssetManagement -ObjectId $AssetId -FieldValues $CustomFieldList

258

if ($customFieldResult.ResultCode -ne 0) {

259

Throw "Error while fetching the asset: $($customFieldResult.ResultMessage)"

260

}

261

Write-Host "Success!"

262

}

263

264

function ConvertTo-AssetV1 {

265

param (

266

[PSCustomObject] $AssetV4

267

)

268

$assetv1 = New-TAsset_V1

269

$assetv1.Id = $AssetV4.Id

270

$assetv1.Name = $AssetV4.Name

271

$assetv1.AssetType = $AssetV4.AssetType

272

$assetv1.AssetTypeId = $AssetV4.AssetTypeId

273

$assetv1.AssetStateId = $AssetV4.AssetStateId

274

275

Write-Output $assetv1

276

}

277

278

function Save-ISSAsset {

279

param(

280

[PSCustomObject] $ISSAsset

281

)

282

$convertedAsset = ConvertTo-AssetV1 -AssetV4 $ISSAsset

283

$saveAssetResult = Acmp-SaveAssets_V1 -Assets $convertedAsset

284

if ($saveAssetResult.ResultCode -ne 0) {

285

Throw "Error while saving the asset: $($saveAssetResult.ResultMessage)"

286

}

287

Write-Host "Success!"

}

== PowerShell-Module testen ==

292

293

Die Funktionalität des erstellten Moduls können Sie mithilfe von Pester (dem Standard-Framework für Unit-Testing in PowerShell) oder eines dedizierten PowerShell Scripts verifizieren. So stellen Sie sicher, dass die Logik fehlerfrei und robust ist. In diesem Beispiel wird das Modul //ISSRestConnector.psm1// mit Pester 5.5.0 getestet.

294

295

296

Beachten Sie, dass Sie Pester für diesen Test ggf. vorher installieren oder updaten müssen. Weitere Informationen dazu finden Sie in der __[[Dokumentation von Pester>>https://pester.dev/docs/introduction/installation||rel="noopener noreferrer" target="_blank"]]__.

297

298

299

Sie können das PowerShell-Modul folgendermaßen testen:

300

301

1. Erstellen Sie im Unterordner //Modules //einen neuen Unterordner mit dem Namen //Tests.//

302

1. Erstellen Sie im Unterordner //Tests// eine neue Datei mit dem Namen //ISSRestConnectorTests.ps1//.

303

1. Fügen Sie den nachfolgenden Code in die Datei ein.

304

1. Drücken Sie Strg + S, um die Datei zu speichern.

305

1. Führen Sie das Script aus

306

307

{{code language="PowerShell" layout="LINENUMBERS" title="**ISSRestConnectorTest.ps1**"}}

308

Import-Module -Name Pester -MinimumVersion 5.5.0

309

Remove-Module ".\Modules\ISSRestConnector.psm1" -Force -ErrorAction SilentlyContinue

310

Import-Module -Name ".\Modules\ISSRestConnector.psm1" -Force

311

312

Describe "Get-ISSData Function Tests" {

313

BeforeAll {

314

# Mock the API response

315

$global:MockApiResponse = @{

Name = "iss"

Id = 25544

Latitude = 12.34

Longitude = 56.78

Altitude = 408.5

Velocity = 27600

Visibility = "daylight"

323

Timestamp = [datetime]::Now.ToUniversalTime().Subtract([datetime]::UnixEpoch).TotalSeconds

}

}

Context "When the API responds successfully" {

328

BeforeEach {

329

# Mock the API call

330

Mock -CommandName Invoke-RestMethod -ParameterFilter { $Method -eq 'GET' } -MockWith {

331

return $global:MockApiResponse

332

} -ModuleName "ISSRestConnector"

333

}

334

335

It "Should return a PSCustomObject with expected properties" {

336

$result = Get-ISSData

337

$result | Should -BeOfType PSCustomObject

338

$result.Name | Should -Not -BeNullOrEmpty

339

$result.Latitude | Should -Not -BeNullOrEmpty

340

$result.Longitude | Should -Not -BeNullOrEmpty

341

$result.Altitude | Should -Not -BeNullOrEmpty

342

$result.Velocity | Should -Not -BeNullOrEmpty

343

}

344

345

It "Should correctly map the API response to the output object" {

346

$result = Get-ISSData

347

$result.Name | Should -Be "iss"

348

$result.Latitude | Should -Be "12,34"

349

$result.Longitude | Should -Be "56,78"

350

$result.Altitude | Should -Be "408,5"

351

$result.Velocity | Should -Be "27600"

}

}

Context "When the API fails" {

356

357

It "Should log an error when the API fails" {

358

# Mock a failure in the API call

359

Mock -CommandName Invoke-RestMethod -ParameterFilter { $Method -eq 'GET' } -MockWith {

360

throw "API error"

361

} -ModuleName "ISSRestConnector"

362

363

$error.Clear() # Clear any pre-existing errors

364

Get-ISSData

365

$error[1].Exception.Message | Should -Contain "API error"

}

}

}

(% class="wikigeneratedid" %)

372

Da in diesem Test kein Abruf der tatsächlichen API stattfindet, sondern die API-Daten simuliert werden, wird Ihnen als Ergebnis der beabsichtigte Error //Failed to fetch ISS data: API error //angezeigt. Darüber hinaus sollten die drei Tests erfolgreich gewesen sein.

373

374

(% class="wikigeneratedid" %)

375

[[image:Output_Pester Testing.png||alt="Ergebnis des Modul-Tests mit Pester" data-xwiki-image-style-alignment="center"]]

376

377

== PowerShell-Microservices erstellen ==

378

379

Da die benötigten PowerShell-Module nun erstellt und getestet sind, kann mit der Erstellung der Microservices begonnen werden.

380

381

1. Öffnen Sie die AESB Console und navigieren Sie zum Workspace //Creator - PowerShell//.

382

1. Klicken Sie in der Ribbonleiste im Bereich //Ordner //auf den Button //Hinzufügen// und erstellen Sie den Ordner// ISS ACMP Connector.//

383

1. Wählen Sie den Ordner aus und klicken Sie in der Ribbonleiste im Bereich //PowerShell-Vorlagen //auf den Button //Hinzufügen.//

384

1. Erstellen Sie die Vorlage// ISSRestConnector. //Klicken Sie in der Ribbonleiste auf den Button //Speichern.//

385

1. Wiederholen Sie Schritt 3 und Schritt 4 für die Erstellung der Vorlage //ISSAssetImporter//.

386

387

== PowerShell-Module implementieren ==

388

389

Die Implementierung der Module in die PowerShell-Microservices erfolgt an zwei Stellen: In der Modul-Verwaltung und im Skript-Editor.

390

391

=== PowerShell-Module in der Modul-Verwaltung hochladen ===

392

393

Zunächst müssen Sie den einzelnen PowerShell-Vorlagen die jeweiligen Module zuweisen:

394

395

1. Wählen Sie die PowerShell-Vorlage //ISSRestConnector //aus und klicken Sie in der Ribbonleiste auf den Button //Module//.

396

1. Klicken Sie auf //DLL-/PSM1-/Public API-Module hinzufügen //und geben Sie bei //Dateipfad //den Pfad der Modul-Datei //ISSRestConnector.psm1// an, indem Sie die Datei im Datei-Explorer öffnen.{{aagon.infobox}}Bei korrekter Ordnerstruktur, sollte der Pfad 0000 angegeben werden.{{/aagon.infobox}}

397

1. Klicken Sie auf den Button //Hinzufügen//, um das Modul hochzuladen und klicken Sie in der Modul-Verwaltung auf //OK//, um die Modul-Verwaltung zu schließen.

398

1. Wiederholen Sie die Schritte für den Microservice ISSAssetImporter mit den Modulen //ISSAssetImporter.psm1 //und //ACMP Public API// (Änderung des Modul-Typs erforderlich).

399

400

[[PowerShell-Modul implementieren>>image:PowerShell-Modul implementeren.png||alt="PowerShell-Modul implementieren" data-xwiki-image-style-alignment="center" height="355" width="800"]]

401

402

=== PowerShell-Module in Microservice-Skripten aufrufen ===

403

404

Die PowerShell-Module sind nun in der Modul-Verwaltung hochgeladen und können aus Microservice-Skripten heraus aufgerufen werden. Dafür werden nun die Skripte im Skript-Editor angepasst.

405

406

407

In diesem Beispiel werden nur die Event-Skripte angepasst, bei denen für dieses Beispiel eine Anpassung notwendig ist. Die nicht erwähnten Event-Skripte bleiben unverändert. Für allgemeine Informationen zu den Event-Skripten, lesen Sie den Abschnitt [[Aufbau des Skript-Editors>>doc:AESB.110.Workspaces.Powershell.Skript-Editor.WebHome]].

408

409

410

(% class="wikigeneratedid" %)

411

**ISSRestConnector - Skript**

412

413

(% class="wikigeneratedid" %)

414

Der ISSRestConnector soll zu einstellbaren Zeiten die Daten von der Rest API holen. Dafür werden die Skript-Events //.OnStart// und //.OnExecute //entsprechend angepasst.

415

416

1. Wählen Sie den Microservice //ISSRestConnector //aus und klicken Sie in der Ribbonleiste auf den Button //Skript//.

417

1. Wechseln Sie in den Skript-Tab //OnStart //und fügen Sie den nachfolgenden Code in die Datei ein.

418

1. Wechseln Sie in den Skript-Tab //OnExecute //und fügen Sie den nachfolgenden Code in die Datei ein.

419

1. Drücken Sie Strg + S, um die Datei zu speichern.

420

1. Schließen Sie den Skript-Editor.

421

422

{{code language="PowerShell" layout="LINENUMBERS" title="**ISSRestConnector.OnStart**"}}

423

#

424

# This gets executed once the Microservice has started.

425

#

426

427

$message = "Starting ISS2ACMP.REST"

428

429

Write-Host $message

430

Write-BusinessLog $message

431

432

# Registering Alias

433

Set-AESBSelfAsAlias -Alias $configuration.Alias -RemoveExistingAlias

434

435

436

{{code language="PowerShell" layout="LINENUMBERS" title="**ISSRestConnector.OnExecute**"}}

437

#

438

# This gets executed perpetually by the scheduler. Main business logic should go here.

#

try {

# Trying to fetch new data

443

Write-Host "Fetching new data from the api."

444

$result = Get-ISSData -ApiUrl $configuration.ApiUrl

445

446

# Converting the data to icql

447

$icql = ConvertTo-AESBIcql $result

448

449

# Sending the data to the next microserice

450

Publish-AESBMessage -Alias $configuration.Target -Message $icql

}

catch {

Write-Error $_

}

(% class="wikigeneratedid" %)

458

**ISSAssetImporter - Skript**

459

460

(% class="wikigeneratedid" %)

461

Der ISSAssetImporter soll eingehende Nachrichten des ISSRestConnectors in ein gültiges Asset umwandeln und dieses mit den definierten Custom Fields in das Asset Management von ACMP eintragen. Dafür werden die Skript-Events //.OnStart// und //.OnMessage //entsprechend angepasst.

462

463

1. Wählen Sie den Microservice //ISSAssetImporter //aus und klicken Sie in der Ribbonleiste auf den Button //Skript//.

464

1. Wechseln Sie in den Skript-Tab //OnStart //und fügen Sie den nachfolgenden Code in die Datei ein.

465

1. Wechseln Sie in den Skript-Tab //OnMessage //und fügen Sie den nachfolgenden Code in die Datei ein.

466

1. Drücken Sie Strg + S, um die Datei zu speichern.

467

1. Schließen Sie den Skript-Editor.

468

469

{{code language="PowerShell" layout="LINENUMBERS" title="**ISSAssetImporter.OnStart**"}}

470

#

471

# This gets executed once the Microservice has started.

472

#

473

474

$message = "Starting ISS2ACMP.ACMPImporter"

475

476

Write-Host $message

477

Write-BusinessLog $message

478

479

# Registering Alias

480

Set-AESBSelfAsAlias -Alias $configuration.Alias -RemoveExistingAlias

481

482

483

{{code language="PowerShell" layout="LINENUMBERS" title="**ISSAssetImporter.OnMessage**"}}

484

#

485

# This gets executed when a message is received.

486

#

487

# The received message can be accessed via $msg

488

# To retrieve only the body from the message use $body

#

# Getting msg data

$msg = New-Message -Args $args

493

$body = New-MessageBody -Args $args

494

495

# Converting from icql to PSCustomObject

496

$data = ConvertFrom-AESBIcql -Icql $body

497

Write-Host $data

498

499

# Getting the AssetTypeId

500

$assetTypeId = Get-AssetTypeId -AssetTypeName $configuration.Acmp.AssetTypeName

501

502

# Trying to get the asset if it is already present in acmp

503

$asset = Get-ISSAsset -AssetTypeId $assetTypeId -AssetTypeName $configuration.Acmp.AssetTypeName -AssetStateId $configuration.Acmp.AssetStateId -ISS $data

504

505

# Saving the asset

506

Save-ISSAsset -ISSAsset $asset

507

508

# Creating the custom fields

509

$customFieldList = @()

510

$customFieldList += New-CustomField -Id $configuration.Acmp.CustomFields.Latitude -Value $data.Latitude

511

$customFieldList += New-CustomField -Id $configuration.Acmp.CustomFields.Longitude -Value $data.Longitude

512

$customFieldList += New-CustomField -Id $configuration.Acmp.CustomFields.Altitude -Value $data.Altitude

513

$customFieldList += New-CustomField -Id $configuration.Acmp.CustomFields.Velocity -Value $data.Velocity

514

515

# Saving the custom fields

516

Save-CustomFieldList -AssetId $asset.Id -CustomFieldList $customFieldList

517

518

519

== Microservice-Schema erstellen ==

520

521

Nachdem die Microservice-Skripte nun angepasst wurden und die benötigten Funktionalitäten enthalten, müssen für die Möglichkeit der Konfiguration noch die Schemas für die Microservices erstellt werden. Dazu wird der Schema-Designer verwendet.

522

523

524

Mit dem Schema-Designer haben Sie die Möglichkeit, die Eingabe-Felder anzulegen, welche für die Konfiguration benötigt werden. Alternativ ist es auch möglich, die benötigte Konfiguration statisch im Microservice-Skript zu integrieren.

525

526

527

(% class="wikigeneratedid" %)

528

**ISSRestConnector - Schema**

529

530

(% class="wikigeneratedid" %)

531

Für den ISSRestConnector müssen drei Datenfelder angelegt werden.

532

533

1. Wählen Sie den Microservice //ISSRestConnector //aus und klicken Sie in der Ribbonleiste auf den Button //Schema//.

534

1. Klicken Sie im Schema-Designer auf //Hinzufügen, //um den SchemaString //Alias// anzulegen.

535

1. Konfigurieren Sie den Schemaknoten //Alias //entsprechend den Daten in der nachfolgenden Tabelle.

536

1. Wiederholen Sie die Schritte 1 bis 3 für die weiteren SchemaStrings //ApiUrl //und //Target//.

537

1. Klicken Sie im Schema-Designer auf //Speichern//, um das Schema zu speichern.

538

1. Schließen Sie den Schema-Designer.

539

540

|=(% style="width: 225px;" %)Datenfeld/Schemaknoten|=(% style="width: 430px;" %)Alias|=(% style="width: 415px;" %)ApiUrl|=(% style="width: 370px;" %)Target

541

|=(% style="width: 225px;" %)Anzeigename|(% style="width:430px" %)Alias|(% style="width:415px" %)API Url|(% style="width:370px" %)Target

542

|=(% style="width: 225px;" %)Beschreibung|(% style="width:430px" %)Der Alias des Microservice.|(% style="width:415px" %)Die URL der Rest API der ISS(https:~/~/wheretheiss.at/w/developer).|(% style="width:370px" %)Der Ziel-Microservice

543

|=(% style="width: 225px;" %)Erforderlich|(% style="width:430px" %)Ja|(% style="width:415px" %)Ja|(% style="width:370px" %)Ja

544

|=(% style="width: 225px;" %)Initialwert|(% style="width:430px" %)ISS2ACMP.ISSRestConnector|(% style="width:415px" %)https:~/~/api.wheretheiss.at/v1/satellites/25544|(% style="width:370px" %)ISS2ACMP.ISSAcmpAssetImporter

545

546

[[Schema mit Datenfeldern für den ISSRestConnector>>image:Schema_ISSRestConnector.png||alt="Schema mit Datenfeldern für den ISSRestConnector"]]

547

548

**ISSAssetImporter - Schema**

549

550

(% class="wikigeneratedid" %)

551

Für den ISSAssetImporter müssen zwei Schema-Objekte und insgesamt sieben Datenfelder angelegt werden

552

553

1. Wählen Sie den Microservice //ISSAssetImporter //aus und klicken Sie in der Ribbonleiste auf den Button //Schema//.

554

1. Klicken Sie im Schema-Designer auf //Hinzufügen, //um den SchemaString //Alias //anzulegen.

555

1. Konfigurieren Sie den Schemaknoten //Alias //entsprechend den Daten in der nachfolgenden Tabelle.

556

557

__Acmp: SchemaObject__

558

559

Nun wird das erste SchemaObject erstellt. Alle weiteren SchemaStrings und auch das zweite SchemaObject werden unter dem SchemaObject //Acmp// untergliedert.

560

561

1. Klicken Sie im Schema-Designer auf //Hinzufügen, //um das SchemaObject //Acmp// anzulegen.

562

1. Wählen Sie das angelegte SchemaObject //Acmp //aus und legen Sie alle weiteren Schemaknoten innerhalb dieses SchemaObjects an.

563

1. Klicken Sie im Schema-Designer auf //Hinzufügen //und legen Sie nacheinander die SchemaStrings //AssetTypeName //und //AssetStateId// an.

564

1. Klicken Sie im Schema-Designer auf //Hinzufügen //und legen Sie das SchemaObject //CustomFields //an.

565

1. Klicken Sie im Schema-Designer auf //Hinzufügen //und legen Sie nacheinander die SchemaStrings //Latitude, Longitude, Altitude //und //Velocity //an.

566

1. Konfigurieren Sie alle SchemaStrings// //entsprechend den Daten in der nachfolgenden Tabelle.

567

1. Klicken Sie in der Ribbonleiste des Schema-Designers auf //Speichern//, um das Schema zu speichern.

568

1. Schließen Sie den Schema-Designer.

|=(% style="width: 224px;" %)Beschreibung|(% style="width:214px" %)- |(% style="width:173px" %)Name des Assettypes, welcher für die ISS verwendet werden soll.|(% style="width:154px" %)-|(% style="width:125px" %)ID des Custom Fields|(% style="width:114px" %)ID des Custom Fields|(% style="width:169px" %)ID des Custom Fields|(% style="width:177px" %)ID des Custom Fields

573

574

|=(% style="width: 224px;" %)Initialwert|(% style="width:214px" %)ISS2ACMP.ISSAcmpAssetImporter|(% style="width:173px" %)Spacestation|(% style="width:154px" %){7BDAC345-C25E-44C9-B220-CBA3CCCD19A7}|(% style="width:114px" %)[[//{ID des benutzerdefinierten Feldes}//>>doc:||anchor="IDsderbenutzerdefiniertenFelderabfragen"]]|(% style="width:114px" %)[[//{ID des benutzerdefinierten Feldes}//>>doc:||anchor="IDsderbenutzerdefiniertenFelderabfragen"]]|(% style="width:169px" %)[[//{ID des benutzerdefinierten Feldes}//>>doc:||anchor="IDsderbenutzerdefiniertenFelderabfragen"]]|(% style="width:177px" %)[[//{ID des benutzerdefinierten Feldes}//>>doc:||anchor="IDsderbenutzerdefiniertenFelderabfragen"]]

575

576

[[Schema mit Datenfeldern für den ISSRestConnector>>image:Schema_ISSAssetImporter.png||alt="Schema mit Datenfeldern für den ISSRestConnector"]]

= Fehlerbehandlung =

Die Fehlerbehandlung unterscheidet sich je nach System, in welches die Daten integriert werden sollen. Abhängig vom Zeitpunkt der Entwicklung, an dem ein Fehler auftritt, gibt es in diesem Beispiel mehrere Ansätze zur Fehlerbehandlung. Außerdem ist es immer hilfreich, die Informationen aus dem Logging der AESB Console zu beachten.

581

582

|=(% style="width: 715px;" %)Fehler|=(% style="width: 724px;" %)Ansätze zur Fehlerbehandlung

583

|(% style="width:715px" %)Die AESB Shell lässt sich nicht in Visual Studio Code einrichten.|(% style="width:724px" %)Überprüfen Sie die Korrektheit des Pfads der AESB Shell, der in der Datei //Microsoft.VSCode_profile.ps1 //angegeben ist.

584

|(% style="width:715px" %)Der Test der PowerShell-Module schlägt fehl.|(% style="width:724px" %)Beachten Sie den Fehlercode in Visual Studio Code. Überprüfen Sie ggf. die eingestellte Sprache in Visual Studio Code, da bei falscher Spracheinstellung möglicherweise Syntaxfehler auftreten können.

585

|(% style="width:715px" %)Die Verbindung zur ACMP Console kann nicht hergestellt werden.|(% style="width:724px" %)Überprüfen und testen Sie die [[Konfiguration der SICS-Verbindung und die Zugriffsberechtigung in ACMP>>doc:AESB.110.AESB installieren, konfigurieren und aktualisieren.SICS-Verbindung konfigurieren.WebHome]]. Prüfen Sie außerdem, ob die SICS-Verbindung möglicherweise ausgefallen ist.

586

|(% style="width:715px" %)Die Werte wurden nicht in die benutzerdefinierten Felder importiert.|(% style="width:724px" %)Überprüfen Sie das Logging in der AESB Console. Möglicherweise wurden die benutzerdefinierten Felder nicht gefunden, da sie fehlerhaft angelegt wurden.

= Orchestrierung =

= Datei-Download =

Das komplette Dateiverzeichnis mit allen Dateien, die Sie in diesem Best Practice selbstständig erstellt haben, finden Sie ebenfalls zum Herunterladen in unserer Community.

Wiki source code of Entwicklung eines ACMP Connectors für die ISS

Navigation