# 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 according object does not exist. The Cmdlet therefore 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 the 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[]}
#>
```

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