Get-ERPObject

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

Syntax

1
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

Name/s of navigation properties which should be included.
Navigation properties nested inside a complex type property can also be expanded by specifying the full path (e.g. ComplexTypeProperty/NavigationProperty).

yes

String[]

Select

Name/s of any properties 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 retrieves a single Entity-object from the ERP system, including all its properties.

Alternatively, you can use the -Select parameter to return only the properties which you want to have in the result.

Depending on the entity model in the ERP system, entities may contain multiple hierarchical levels.
Unlike complex type properties, the navigation properties are not returned by default. To include them in the result, explicitly specify them using the -Expand parameter.
Complex type properties themselves cannot be expanded and do not need to be, since they are always returned by default together with the entity’s other properties.
However, a complex type property may itself contain a navigation property. In that case, the navigation property can still be expanded by specifying the path through the complex type property (e.g. -Expand "ComplexTypeProperty/NavigationProperty").

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’

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
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[]}
#>

Requesting a Category including navigation property details

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
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[]}
#>

Retrieving only specific properties from ERP

1
2
3
4
5
6
Get-ERPObject -EntitySet 'BusinessPartners' -Keys @{ CardCode = 'C20000' } -Select 'CardCode','Address/City','Classifications/MaterialGroup' # note: here we specify the path to the properties of complex types or navigation properties
<#
        CardCode : 'C20000'
        Address : @{City=Sample City}
        Classifications : @(@{MaterialGroup='Sample Group'})
#>

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
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):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
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'!")
   }
}