# New-ERPObject

The New-ERPObject cmdlet allows you to create a new and empty instance of the required EntityType.

## Syntax

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

New-ERPObject [[-EntityType] <String>] [[-Properties] <Object>] [<CommonParameters>]
```

## Parameters

| Type                 | Name       | Description                                                                                                                                                      | Optional |
|----------------------|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|
| String               | EntityType | The EntityType of the item that should be created. </br> It is also possible to additionaly specify a part or the whole namespace (e.g NorthwindModel.Territory) | no       |
| Hashtable / PsObject | Properties | The properties will be filled with the specified values.                                                                                                         | 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).

## Remarks

The cmdlet is able to create a new instance of the specified EntityType, by analyzing the \$metadata for required and optional [Properties](/code_reference/commandlets/objects/property) and [NavigationProperties](/code_reference/commandlets/objects/navigationproperty) \
When passing **-Properties**, those property values will be set on the newly created entity. Only existing properties can be passed, and the values are not checked to be valid!\
Otherwise the default value of the properties will be determined as following:
> - the default value that is specified in the \$metadata (see DefaultValue in [property](/code_reference/commandlets/objects/property) )
> - Empty for nullable properties (see IsNullable in [property](/code_reference/commandlets/objects/property) )

Don't forget that [NavigationProperties](/code_reference/commandlets/objects/navigationproperty) with a target [multiplicity](/code_reference/commandlets/objects/multiplicity) of *ZeroOrOne* or *Many* are nullable too!\
For [NavigationProperties](/code_reference/commandlets/objects/navigationproperty) with a target [multiplicity](/code_reference/commandlets/objects/multiplicity) of *One*, the cmdlet is able to create the required target instance too (**recursive on multiple levels**).

```{admonition} Performance
:class: warning

Because the cmdlet has only an -EntityType parameter and no -EntitySet or -Service parameter, the entityType will be searched in all services.\
When some services are permanently not available, you can speed up your process by disconnecting them.\
Please see example {ref}`Disconnect all not available services <code_reference/commandlets/disconnect-erp:examples>`.
```

## Examples

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

**Create a new instance by specifying the EntityType**

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

$territory = New-ERPObject -EntityType 'Territory'

**Create a new instance by specifying the whole EntityType with namespace**
```

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

$shipper= New-ERPObject 'NorthwindModel.Shipper'
```

**Create a new instance and specify specific property values**

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

$region = New-ERPObject 'Region' -Properties @{'RegionID'=1}
$territory = New-ERPObject -EntityType 'Territory' -Properties @{'TerritoryID'='66'; 'Region'=$region}
$region.Territories = @($territory)
```

**Dynamically create new instances for all the EntityTypes of a specific service**

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

$allEntityTypes = Get-ERPEntityTypes -Service 'http://services.odata.org/V3/Northwind/Northwind.svc'
$allEntityTypes | foreach { New-ERPObject ($_.Namespace+'.'+$_.Name) }
```

**Error handling, analyze why no instance of the specified EntityType could be created, by using \$Error**

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

Connect-ERP -Service "http://services.odata.org/V3/Northwind/Northwind.svc"
$entity = New-ERPObject -EntityType "People"

if(-not $entity){
        $Error[0].Exception #"No EntityType found with the given name: People"
}
```