IanRich

CAPA 4.3.2 - Passing complex variables to PowerShell scripts!

Blog Post created by IanRich on Jun 22, 2017

Hi Everyone,

 

Since I have now started to play with CAPA 4.3.2 REST APIs, I decided it was time to try and tackle one of the issues that has always proven to be a painful thorn in my backside...  

 

Passing complex variables to my PowerShell scripts

 

Passing non-standard variables (i.e. arrays, ValueMaps) to a PowerShell script has always been a painful combination of escaping characters, hyphens, and string parsing.

 

Now thanks to the CAPA 4.3.2 REST API, there is a really easy way to access all your process variables from within your PowerShell script in just a few simple lines of code.

 

The RESTful API allows you to directly read the process' dataset, by passing only the instance ID, and returns you a nicely JSON formatted reply that is really easy to convert into a PowerShell object.

 

Below you will find an example PowerShell function that I created to read my process's dataset into a PowerShell object. 

 

$CAPA_DataSet_Criteria by default is set to a *, so this will return all values from the dataset, you can limit what is returned in the PS Object by adding some additional criteria such as *CAPA* would only return variables with CAPA in the name.

 

Once you have read your dataset into the PowerShell object, you can easily access any of the variables like so:

 

Variable TypeExample to access the value
Root Variables

$test.CallerUser

$test.ServerName

ValueMap Values

$test.'Environment.Project_Specific.Value'

$test.'Environment.Common.SHA1_Hash'

Array Values

$test.'email_details[0]'

$test.'email_details[1]'

$test.'email_details[2]'

 

 

Hopefully this helps someone out,

Ian

 

 

 

### START OF CODE ###

$CAPA_Username = "username"
$CAPA_Password = "password"
$CAPA_ServerName = "capa_server_url:port"
$CAPA_InstanceID = "example_instance_id"
$CAPA_DataSet_Criteria = "*" #(Used to limit what is returned in the PS Object)


#############################################################################################
# Start Function: GetCAPA_DataSet #
#############################################################################################
function GetCAPA_DataSet ($CAPA_DataSet_Criteria)
{
try
{
$PWord = ConvertTo-SecureString –String $CAPA_Password –AsPlainText -Force;
$CAPA_Credential = New-Object –TypeName System.Management.Automation.PSCredential –ArgumentList $CAPA_Username, $PWord;

$CAPA_URL = "https://$($CAPA_ServerName)/api/rest/v1/processinstances/$($CAPA_InstanceID)/processdataset"
$dataset_result = Invoke-RestMethod -Uri $CAPA_URL -Credential $CAPA_Credential -UseBasicParsing
$local_dataset = $dataset_result.Response.Details.ProcessDataset.Parameters.Param | Where-Object Name -Like $CAPA_DataSet_Criteria

if($local_dataset.length -le 0)
{
$Result_Value = New-Object PSObject
$Result_Value | add-member Noteproperty status "failure"
$Result_Value | add-member Noteproperty message "Criteria returned 0 matches"
return $Result_Value
}

$Result_Value = New-Object PSObject
$Result_Value | add-member Noteproperty status "success"
$local_dataset | ForEach { $Result_Value | add-member Noteproperty $_.Name $_.Value }
return $Result_Value
}
catch
{
$Result_Value = New-Object PSObject
$Result_Value | add-member Noteproperty status "failure"
$ex = $_.Exception
$Result_Output += $ex.Message
$Result_Value | add-member Noteproperty message $Result_Output
return $Result_Value
}
}
#############################################################################################
# End Function #
#############################################################################################

 

$test = GetCAPA_DataSet $CAPA_DataSet_Criteria
$test

### END OF CODE ###

Outcomes