# New-ERPObject

Returns a new and by default empty ERP object of the specified ERP type.

Thereby its field values can be passed directly, or alternatively they are determined automatically.\
For Vault entities, for example, based on the mappings configured in the [ERP Integration Settings](<erp_integrations:Configuration>) dialog, or from the $metadata of the ERP system.

## Syntax

Configuration from Vault:
```{code-block} powershell
New-ERPObject [-EntityType] <string> [-VaultEntity] <PSObject> [<CommonParameters>]
<#
PARAMETER
    -EntityType
        Required                true

    -VaultEntity
        Required                true
        Accepts pipeline input: true

    <CommonParameters>
        This cmdlet supports the common parameters: ErrorAction, ErrorVariable
#>
```

Providing field values directly:
```{code-block} powershell
New-ERPObject [-EntityType] <string> [[-Properties] <Hashtable / PSObject>] [<CommonParameters>]
<#
PARAMETER
    -EntityType
        Required                true

    -Properties
        Required                false

    <CommonParameters>
        This cmdlet supports the common parameters: ErrorAction, ErrorVariable
#>
```

## Parameters

| Type                 | Name        | Description    |
|----------------------|-------------|----------------|
| String               | EntityType  | The EntityType of the ERP object that should be returned.</br>It is possible to additionaly specify a part or the whole namespace (e.g 'ErpServices.Services.Entities.Item') |
| Hashtable / PSObject | Properties  | The field values that should be set on the returned ERP object.                        | yes      |
| [powerVault Object](<inv:powervault#code_reference/objects>) | VaultEntity | The Vault entity, from which mapped Properties in the [ERP Integration Settings](<erp_integrations:Configuration>) dialog are set on the corresonding Fields of the ERP object, that is returned.<br>Typically, a powerVault [](<inv:powervault#code_reference/objects/file>), [](<inv:powervault#code_reference/objects/item>), [](<inv:powervault#code_reference/objects/filebomrow>) or [](<inv:powervault#code_reference/objects/itembomrow>) object is passed.|

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

With only an **-EntityType** parameter and no *-EntitySet* or *-Service* parameters, the cmdlet searches for the specified type in all services, considering namespace information.

It analyzes the \$metadata for all ERP [Properties](</code_reference/commandlets/objects/property>) and [NavigationProperties](</code_reference/commandlets/objects/navigationproperty>) to create a new ERP object.\
As a result, the returned field values have the following *default values*:
> - the default field value that is specified in the \$metadata (see  [DefaultValue](</code_reference/commandlets/objects/property>))
> - Empty for nullable properties (see [IsNullable](</code_reference/commandlets/objects/property>)).\
    Note that also [NavigationProperties](</code_reference/commandlets/objects/navigationproperty>) with a target [multiplicity](</code_reference/commandlets/objects/multiplicity>) of *ZeroOrOne* or *Many* are nullable.
> - the required target instance for [NavigationProperties](</code_reference/commandlets/objects/navigationproperty>) with a target [multiplicity](</code_reference/commandlets/objects/multiplicity>) of *One*, even recursively on multiple levels

### Configuration from Vault
A **-VaultEntity** can be passed after calling [`Connect-ERP -UseSettingsFromVault`](<code_reference/commandlets/connect-erp:Configuration from Vault>) (configuration for the currently connected Vault is then provided by the [$ERPSettings](</code_reference/commandlets/objects/settings>) variable).\
The prerequisite is that a type mapping has been set up for the specified Vault- and ERP entity type via the [ERP Integration Settings](<erp_integrations:Configuration>) dialog (e.g. `$vaultFile` and `-EntityType 'Item'`).

Based on the configured [Field Mappings](<code_reference/commandlets/objects/settings:Examples>) the returned ERP object is automatically filled with data.\
For this, the respective ERP fields provide the values of the mapped *Vault Properties* or alternatively the configured *fixed-values*.\
Additional settings are also taken into account, such as special *default values* if the Vault Property is empty, matching ERP values from a *possible value* list, and complex or calculated value determinations.

### Providing field values directly
When **-Properties** are passed, the cmdlet assigns them directly to the fields of the newly created ERP object.\
Note that the parameter only accepts existing properties, and the passed values are not checked for validity!

## 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 ERP object from a Vault file for which mappings are [configured](<erp_integrations:Configuration>)**
```{image} /img/erp_integrations/settings_dialog_entity_type_and_field_mappings.png
   :width: 400px
   :align: left
```
```{code-block} powershell
:linenos: true

Import-Module powerVault
...
$file = Get-VaultFile -Properties @{'File Name'='Pad Lock.iam'}

Connect-ERP -UseSettingsFromVault
$erpObject = $file | New-ERPObject -EntityType 'Item'

$erpObject | Format-List Number,Title,Description,Material,UnitOfMeasure,Weight
<#
Number          : ERP-17425549
Title           : Pad Lock
Description     : PAD LOCK ASSEMBLY
Material        : Steel
UnitOfMeasure   : CM
Weight          : 0.130
#>
```
<br/>
<br/>
<br/>
<br/>

**Create a new ERP object instance with specific field 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 default ERP object is 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"
}
```