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 dialog, or from the $metadata of the ERP system.

Syntax

Configuration from Vault:

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:

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. 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.
powerVault Object	VaultEntity	The Vault entity, from which mapped Properties in the ERP Integration Settings dialog are set on the corresonding Fields of the ERP object, that is returned. Typically, a powerVault File, Item, FileBomRow or ItemBomRow object is passed.

Return type

Entity ← on success
empty ← on failure. Exception/ErrorMessage can be accessed using $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 and NavigationProperties 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)

• Empty for nullable properties (see IsNullable).
  Note that also NavigationProperties with a target multiplicity of ZeroOrOne or Many are nullable.

• the required target instance for NavigationProperties with a target multiplicity of One, even recursively on multiple levels

Configuration from Vault

A -VaultEntity can be passed after calling Connect-ERP -UseSettingsFromVault (configuration for the currently connected Vault is then provided by the $ERPSettings 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 dialog (e.g. $vaultFile and -EntityType 'Item').

Based on the configured Field Mappings 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 for demonstration purposes:

Create a new instance by specifying the EntityType

$territory = New-ERPObject -EntityType 'Territory'

Create a new instance by specifying the whole EntityType with namespace

$shipper= New-ERPObject 'NorthwindModel.Shipper'

Create a new ERP object from a Vault file for which mappings are configured

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

Create a new ERP object instance with specific field values

$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

$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

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"
}