# Get-ERPObject

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

## Syntax

```{code-block} powershell
:linenos: true

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. </br> 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](</code_reference/commandlets/objects/entity>) ← on success\
**empty** ← on failure. Exception/ErrorMessage can be accessed using [\$Error](<https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_automatic_variables?view=powershell-5.1#error>).\
If the cmdlet fails due to error responses returned by the ERP system, the \$Error variable provides a [WebRequestException](</code_reference/net_library/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.


:::{admonition} Error Handling
:class: warning

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](<https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_automatic_variables?view=powershell-5.1#error>) variable remains unchanged and the [\$?](<https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_automatic_variables?view=powershell-5.1#section-1>) 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'**

```{code-block} powershell
:linenos: true

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**

```{code-block} powershell
:linenos: true

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**

```{code-block} powershell
:linenos: true

$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](</code_reference/commandlets/new-erpobject>) **, set the Key and use it to search the entity in the ERP System**

```{code-block} powershell
:linenos: true

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):

```{code-block} powershell
:linenos: true

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** [\$?](<https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_automatic_variables?view=powershell-5.1#section-1>) **and analyze
the** [WebRequestException](</code_reference/net_library/webrequestexception>) **to understand why the object could not be retrieved, by using \$Error:**

```{code-block} powershell
:linenos: true

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'!")
   }
}
```