PowerShell Scripts

Abstract

• Where to Store the Powershell scripts?
• JSON Object that eLegere Provides to the PowerShell
• JSON Object with Response's Data
  • Return Codes
• How to Add Additional Parameters
• Action Type and eLegere Behavior

The PowerShell Scripts section explains:

• In which directory to store the PowerShell Scripts
• What JSON Object eLegere supplies to the PowerShell Script and its structure.
• What's the structure of the JSON Object with the PowerShell's results.
• How to specify additional parameters and values.
• Differences in PowerShell scripts behavior according to the usage context.

Tutorials

This document explains how eLegere handles the PowerShell Scripts and their execution.

Tutorials in PowerShell section shows what you can do with PowerShell in eLegere: they are step-by-step use cases that you can customize for your own needs.

• Generate Scheduled Email: The tutorial teaches how to create a scheduled weekly email summarizing the latest application's rows.

Where to Store the Powershell scripts?

eLegere stores all the PowerShell scripts in a folder that the installation's administrator has configured.

Contact your eLegere administrator to store your PowerShell script in the dedicated folder on the machine.

JSON Object that eLegere Provides to the PowerShell

Learn how to use the JSON Object containing the row's fields in a PowerShell script and how it's structured.

Your PowerShell script must have the $actionContext parameter to receive a JSON Object from eLegere.

$actionContext receives a String containing the JSON Data converted to string. So, you can use it to retrieve and read all the values you might need to manipulate or record.

Consider the case where you retrieve the row and pass a field's value to an executable. You can through the stringified JSON that eLegere provides:

<# Parameters Definition

  The PowerShell requires the static parameter $actionContext. 
  $actionContext is a String encoding the JSON.

  Add further parameters AFTER $actionContext, for example: 
  param([string] $actionContext, [int]$category) #>

param([string] $actionContext)

<# $actionContext receives the JSON in String format.
   It's easier to access the values if the script converts the string into an object.
   ConvertFrom-JSON takes the $actionContext value and reverts it to JSON Object.#>

$actionContextObj = $actionContext | ConvertFrom-Json

<# The JSON contains an "Items" key listing all the rows and fields' values.
   "Items" contains each row identified through their Storage IDs as keys.

   If there are no Detail tables, "Items" contains only the Master row's Storage Id.
   Retrieve its Storage's Id through `psobject.properties.name`. 
   `psobject.properties.name` retrieves the object's keys.

   If the application has Detail tables, "Items" contains multiple rows identified
   by their Storage's Id, Master row included. In such case, provide the 
   Storage's Id (either Master or Detail storage) manually through a variable
   to access the row instead of `psobject.properties.name`; for example:

   $storageId = "1658b291-59b7-4593-b7e3-2685b7104511" #>

$storageId = $actionContextObj.Items.psobject.properties.name 

<# The script identifies the row through its Storage's Id in "Items".
   Once you have the Storage's Id, you can retrieve the row's fields
   and their values by filtering "Items" in the JSON object using the Storage's Id.

   The "NewItem" key inside the row's object in "Items" (identified by the Storage Id)
   contains all the fields' keys and values. 

   Items > Storage Id (e.g. "1658b291-59b7...")> NewItem > fields keys.

   `psobject.properties[$storageId].Value.NewItem` lists all the values 
   contained in NewItem. #>

$item = $actionContextObj.Items.psobject.properties[$storageId].Value.NewItem

<# The `$item` variable contains the object with all the row's fields and values.
  Refer to a field as property of $items (`$item.fieldName`). Pass the field's 
  value to an executable to perform actions through the following command:

  `Start-Process -FilePath "[Insert path to the executable]" -ArgumentList $item.fieldName` #>

Start-Process -FilePath "C:\Program Files\exec\app.exe" -ArgumentList $item.fieldName

eLegere reads and supplies the rows as strings encoding JSON Objects. If you convert the string to JSON, the object has the following structure:

{
  "Items": {
    "956cdabb-b752-4dea-9dc7-317bc45e202e": {
      "NewItem": {},
      "OldItem": {} | null
    },
    "e6eeb3ac-91c6-43dc-a1f2-58705ecbe06e": {
      "NewItem": {},
      "OldItem": {} | null
    }
  },
  "UserId": "j.doe@vesenda.com",
  "TimezoneMsOffset": 7200000.0
}

Follows an explanation of the JSON object's keys:

• Items key lists all the rows' objects to be recorded or modified on the database.
• "956cdabb-b752-4dea..." The row's Storage Id. This object contains in turn two other objects.
  • NewItem key is the JSON object containing the row with the latest changes.
  • OldItem key is the JSON object containing the row's information before the changes.
• UserId key is the logon's username.
• TimezoneMsOffset key stands for the time difference between the UTC and the local client executing the action. The value is expressed in milliseconds.

JSON Object with Response's Data

Follows an explanation of the object containing the message's info and operation's result that you can encode in your PowerShell script.

Your PowerShell script can optionally return information to the user about the action. eLegere displays in the client a certain message and result according to the keys' values (if added to the PowerShell Script).

{
  "Message": "",
  "ReturnCode": ""
}

• Message: A String containing the message to display in the client to the user.
• ReturnCode: The key value specifies how eLegere must behave after the PowerShell execution and what result reports. If not specified and left empty, the value passed is 000200 (corresponding to a successful result of the action). See Return Codes for the list of behaviors.

Return Codes

Each code specifies a different result to communicate to the user.

Code	Name	Behavior
000500	Failed	eLegere blocks the whole database transaction and restores the previous table's status. Displays an error message.
000200	Success	eLegere displays a "Success" (This is the Default value for the ReturnCode parameter.)

How to Add Additional Parameters

Learn how to add additional parameters to a PowerShell in eLegere.

Info

See How to Embed PowerShell Scripts in Your Application from the Designer Guide to learn how to create a Custom Action in eLegere. Choose the Invoke PowerShell from the drop-down list.

You can specify additional parameters and keys for a PowerShell. Click the New in the Custom Action's Parameters settings. The action enables to add a new couple of parameters and values.

Action Type and eLegere Behavior

Learn what values the PowerShell script receives through the JSON Object from eLegere according to the action:

• Custom Action with Event Trigger: The JSON Object passed by eLegere has the Items values with the row's information.
• Custom Action with Manual Trigger: The JSON Object passed by eLegere has the Items value with the row's information.
• Scheduled Job: The PowerShell script runs outside an application, so the Items key has no value.

Action	Items Parameter
Custom Action with Event Trigger
Custom Action with Manual Trigger
Scheduled Job

PowerShell Version and Action Type

Note what PowerShell version runs for each type of eLegere Action when you write a script:

• If you write a PowerShell script for the Scheduler, the script will run using a self-hosted version of PowerShell 7.
• If you write a PowerShell script for the Custom Actions, the script will run using the PowerShell version installed with your eLegere installation.