# Get-ERPObjects

Cmdlet to search for specific entities depending on the passed arguments.

## Syntax

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

Get-ERPObjects [[-EntitySet] <String>] [[-Top] <int>] [[-OrderBy] <Object>] [[-Filter] <String>] [[-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       |
| Integer                            | Top       | The amount of how many items should be shown                                                                                                                                                                         | yes      |
| String                             | Filter    | Query what should be executed as a filter                                                                                                                                                                            | yes      |
| String / Hashtable / Hashtable\[\] | OrderBy   | Items getting ordered by passed property name and/or direction                                                                                                                                                       | yes      |
| String\[\]                         | Expand    | Name/s of the related Navigation Properties which should be included                                                                                                                                                 | yes      |
| String\[\]                         | Select    | Name/s of the properties or Navigation Properties which should explicitly be requested and returned                                                                                                                  | yes      |


## Return type

[Entity](</code_reference/commandlets/objects/entity>) **\[\]** ← on success\
**empty array** ← 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 search for specific entities from the ERP.\
The **Filter** argument allows you to specify a filter with OData syntax. More informations about the OData Filter syntax can be found [here](<http://www.odata.org/documentation/odata-version-3-0/odata-version-3-0-core-protocol/>).\
The **OderBy** argument can be specified as String, as hashtable or as an array of hashtables.
> - If the argument is specified as String then the entities are orderd ascending by the passed property name.
> - If the argument is specified as hashtable then the entities are orderd by the passed property name and direction ('Ascending' or 'Descending')
> - If the argument is specified as array of hashtables, the entities can be orderd by multiple properties, in the specified direction (See example below)

The **Expand** allows you to expand multiple navigation properties. As default if the expand argument is **not** specified then the entity will be returned without navigation properties.\
The **Select** argument lets you receive only those properties or navigation properties which you want to have in the result.

## Examples

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

**Search for customers from the company 'Alfreds Futterkiste':**

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

Connect-Erp -Service "http://services.odata.org/V4/Northwind/Northwind.svc/"
$entity = Get-ERPObjects -EntitySet "Customers" -Filter "CompanyName eq 'Alfreds Futterkiste'"
```

**Search for customers with a companyName starting with 'A':**

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

Connect-Erp -Service "http://services.odata.org/V3/Northwind/Northwind.svc/"
Get-ERPObjects -EntitySet "Customers" -Filter "startswith(CompanyName,'A')"
```

**Get categories:**

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

Connect-Erp -Service "http://services.odata.org/V4/Northwind/Northwind.svc/"
$entity = Get-ERPObjects -EntitySet "Categories"
```

**Get first 3 Products:**

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

Connect-Erp -Service "http://services.odata.org/V4/Northwind/Northwind.svc/"
Get-ERPObjects -EntitySet "Products" -Top 3
```

**Get objects ordered by Name:**

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

Connect-Erp -Service "http://services.odata.org/V4/Northwind/Northwind.svc/"
Get-ERPObjects -EntitySet "Products" -OrderBy 'Name'
```

**Get objects ordered by the ProductName \<Descending>:**

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

Connect-Erp -Service "http://services.odata.org/V4/Northwind/Northwind.svc/"
Get-ERPObjects -EntitySet "Products" -OrderBy @{'ProductName'='Descending'}
```

**Get objects ordered by the ProductName \<Descending> and then the CategoryId \<Ascending>:**

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

Connect-Erp -Service "http://services.odata.org/V4/Northwind/Northwind.svc/"
Get-ERPObjects -EntitySet "Products" -OrderBy @(@{'ProductName'='Descending'},@{'CategoryID'='Ascending'} )
```

**Get objects ordered by the ProductName \<Ascending> and then the CategoryId \<Descending>:**

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

Connect-Erp -Service "http://services.odata.org/V4/Northwind/Northwind.svc/"
Get-ERPObjects -EntitySet "Products" -OrderBy @('ProductName',@{'CategoryID'='Descending'} )
```

**Get all OrderID's of the available 'Orders':**

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

Connect-ERP -Service "http://services.odata.org/V4/Northwind/Northwind.svc"
Get-ERPObjects -EntitySet "Orders" -Select "OrderID"
```

**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 error occurred, by using \$Error:**

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

Connect-ERP -Service "https://services.odata.org/V4/Northwind/Northwind.svc/"
$filter = "startswith(CustomerID,1234567)"
$entities = Get-ERPObjects -EntitySet "Invoices" -Filter $filter

if(-not $entities){
if($? -eq $false){
   $Error[0].Exception.StatusCode #400
   $Error[0].Exception.Message
   <#
     No function signature for the function with name 'startswith' matches the specified arguments.
     The function signatures considered are: startswith(Edm.String Nullable=true, Edm.String Nullable=true).
   #>
   $Error[0].Exception.Response.InnerError.StackTrace
   <#
     at Microsoft.OData.Core.UriParser.Parsers.FunctionCallBinder.MatchSignatureToBuiltInFunction(String functionName, SingleValueNode[] argumentNodes, FunctionSignatureWithReturnType[] signatures)
     ...
     at Microsoft.OData.Service.Parsing.RequestExpressionParser.ParseFilter()
   #>
   }
   else{
     Write-Host("No objects found for the `$filter '$filter'!")
   }
}
```