Get-ERPObject

Cmdlet to retrieve a specific entity from the ERP-System.

Syntax

Get-ERPObject [[-EntitySet] <String>] [[-Keys] <Object>] [[-Expand] <String[]>] [[-Select] <String[]>] [<CommonParameters>]

Parameters

Type	Name	Description	Optional
String	EntitySet	The EntitySet name where the item is located. It is also possible to specify additional namespaces or the whole url (e.g MaterialService/Materials, http://localhost:8080/PGS/ERP/MaterialService/Materials)	no
Hashtable / PSObject	Keys	The reference properties for the searching item	no
String[]	Expand	The name/s of the Navigation Property which should be expanded	yes
String[]	Select	The name/s of the Property or Navigation Property which should explicitly be requested and returned	yes

Return type

Entity ← on success
empty ← on failure. Exception/ErrorMessage can be accessed using $Error.
If the cmdlet fails due to error responses returned by the ERP system, the $Error variable provides a WebRequestException .

Remarks

This Cmdlet is used to retrieve one specific object from ERP.

Per default navigation properties will not be returned unless explicitly specified by using the -Expand parameter with the name of the property as argument.
The -Select argument lets you receive only those properties or navigation properties which you want to have in the result.

Error Handling

It is a common use case to utilize this Cmdlet to verify the existence of an object in the ERP system. Therefore it is not expected that the Cmdlet fails (e.g. throws an error) when the requested object does not exist and handles responses of type ‘404 Resource not found’ not as errors.

As a result, no warnings or errors will be logged, the $Error variable remains unchanged and the $? Automatic Variable returns $true.

Examples

In the following examples we are using public OData Services (http://services.odata.org) for demonstration purposes:

Request the Category with Id ‘1’

Connect-Erp -Service "http://services.odata.org/V4/Northwind/Northwind.svc/"
Get-ERPObject -EntitySet "Categories" -Keys @{ "CategoryID" = 1 }
<#
        CategoryID   : 1
        CategoryName : Beverages
        Description  : Soft drinks, coffees, teas, beers, and ales
        Picture      : {21, 28, 47, 0...}
        _Keys        : @{CategoryID=1}
        _Properties  : @{CategoryName=Beverages; Description=Soft drinks, coffees, teas, beers, and ales; Picture=System.Byte[]}
#>

Request a Category with its Navigation Property Products

Connect-Erp -Service "http://services.odata.org/V4/Northwind/Northwind.svc/"
Get-ERPObject -EntitySet "Categories" -Keys @{"CategoryID"=1} -Expand "Products"
<#
        Products     : {Chai, Chang, Guaraná Fantástica, Sasquatch Ale...}
        CategoryID   : 1
        CategoryName : Beverages
        Description  : Soft drinks, coffees, teas, beers, and ales
        Picture      : {21, 28, 47, 0...}
        _Keys        : @{CategoryID=1}
        _Properties  : @{Products=powerGate.Erp.Cmdlets.Cmdlets.Results.PsEntity[]; CategoryName=Beverages; Description=Soft drinks, coffees, teas, beers, and ales; Picture=System.Byte[]}
#>

Request only the ‘CategoryID’ of a Category

$result = Connect-ERP -Service "http://services.odata.org/V4/Northwind/Northwind.svc"
Get-ERPObject -EntitySet "Categories" -Keys @{"CategoryID"=1} -Select "CategoryID"
<#
        CategoryID : 1
#>

Create an empty entity with New-ERPObject , set the Key and use it to search the entity in the ERP System

Connect-ERP -Service "http://services.odata.org/V4/Northwind/Northwind.svc"
$category = New-ERPObject -EntityType "Category"
$category.CategoryID = 1

Get-ERPObject -EntitySet "Categories" -Keys $category._Keys
<#
CategoryID   : 1
CategoryName : Beverages
Description  : Soft drinks, coffees, teas, beers, and ales
Picture      : {21, 28, 47, 0...}
_Keys        : @{CategoryID=1}
_Properties  : @{CategoryName=Beverages; Description=Soft drinks, coffees, teas, beers, and ales; Picture=System.Byte[]}
#>

Check whether an SAP Material does not exist or if another 400 error response occurred (only for older SAP Gateway integrations):

Connect-ERP -Service 'https://sap_environment/sap/opu/odata/arcona6/MATERIAL_SRV' -OnConnect $global:sapConnect

$materialReallyDoesNotExist = $false
$material = Get-ERPObject -EntitySet 'MaterialContextCollection' -Keys @{ Material = '000000000200314159'; Plant = '1001'; ValuationArea=''; ValuationType=''} -Expand @('Description','PlantData','BasicData') -ErrorAction SilentlyContinue

if($? -and $material -eq $null){
   # For older SAP Gateway interfaces this code block is never executed because unfortunately 400 instead of 404 responses are mistakenly returned when materials doe not exist
   $materialReallyDoesNotExist = $true
}

# That's why the response message must be checked. Attention to different languages!
if($? -eq $false){
   if($Error[0].Exception.StatusCode -eq 400) {
      $sapResponse = $Error[0].Exception.RawResponse | ConvertFrom-Json
      $sapResponse.error.code #SY/530

      if($sapResponse.error.message.lang -eq 'de' -and $sapResponse.error.message.value -eq 'Das Material 200314159 ist nicht vorhanden oder nicht aktiviert') {
         $materialReallyDoesNotExist = $true
      }
      else {
         Write-Message "A real error response was returned from SAP: $($sapResponse.error.message.value)"
      }
   }
   else {
      Write-Message "Also in this case, SAP replied with an error: $($Error[0])"
   }
}

if($materialReallyDoesNotExist) {
   # create a new material
}

Error handling: Check if an error appeared by using $? and analyze the WebRequestException to understand why the object could not be retrieved, by using $Error:

Connect-ERP -Service "https://services.odata.org/V4/(S(zhhrvnffwxy1zfd0uy2aeye0))/TripPinServiceRW/"
$entity = Get-ERPObject -EntitySet "People" -Keys @{"UserName"="scottketchum"} -Expand "Trips" -Select "Friends"

if(-not $entity) {
   if($? -eq $false) {
      $Error[0].Exception.StatusCode #500
      $Error[0].Exception.Message
      <#
        The entity instance value of type 'Microsoft.OData.SampleService.Models.TripPin.Person' doesn't have a value for property 'UserName'.
         To compute an entity's metadata, its key and concurrency-token property values must be provided.
      #>
      $Error[0].Exception.Response.ErrorCode #"InternalServerError"
   } else {
      Write-Host("No object found with keys `UserName = scottketchum'!")
   }
}