powergate:code_reference:commandlets:new-erpobject

New-ERPObject

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

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

TypeNameDescriptionOptional
StringEntityTypeThe EntityType of the item that should be created.
It is also possible to additionaly specify a part or the whole namespace (e.g NorthwindModel.Territory)
no
Hashtable / PsObjectPropertiesThe properties will be filled with the specified values.yes

Entity ← on success
empty ← on failure

The cmdlet is able to create a new instance of the specified EntityType, by analyzing the $metadata for required and optional Properties and NavigationProperties.
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)
  • Empty for nullable properties (see IsNullable in Property)

Don't forget that NavigationProperties with a target Multiplicity of ZeroOrOne or Many are nullable too!
For NavigationProperties with a target Multiplicity of One, the cmdlet is able to create the required target instance too (recursive on multiple levels).

Performance

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 Disconnect all not available services.

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 instance and specify specific property 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) }