New-ERPObject

Returns a new, by default empty ERP object of the specified 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 [-Type] <string> [-VaultEntity] <PSObject> [<CommonParameters>]
<#
PARAMETER
    -Type
        Required                true

    -VaultEntity
        Required                true
        Accepts pipeline input: true

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

Providing field values directly:

New-ERPObject [-Type] <string> [[-Properties] <Hashtable / PSObject>] [<CommonParameters>]
<#
PARAMETER
    -Type
        Required                true

    -Properties
        Required                false

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

Parameters

Type

Name

Description

String

Type

The name of the EntityType or ComplexType to 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

The cmdlet searches for the specified -Type in all connected services, considering namespace information.

To create a new instance of the specified entity type (or complex type), it takes its $metadata into account.
As a result, the returned fields have the following default-values:

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 of the specified entity type

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
New-ERPObject -Type 'SalesOrder'

<#
        OrderID : 0
        ShipVia : 6                 <- default value from metadata
        Freight : 0
        OrderDate : 0001-01-01T00:00:00
        RequiredDate : 0001-01-01T00:00:00
        ShippedDate : 0001-01-01T00:00:00
        Address : 
        Customer : @{CustomerID=0}  <- navigation property to another entity, which is created recursively (because multiplicity is One)
        Characteristics : {}        <- also collections of complex types can be not-nullable
        _Keys : @{OrderID=0}
        _Properties : @{Address=$null; Characteristics=Entity[]; Customer=@{CustomerID=0; Name=$null} ; OrderDate=0001-01-01T00:00:00; RequiredDate=0001-01-01T00:00:00; ShippedDate=0001-01-01T00:00:00; ShipVia=6}
#>

Dynamically create new instances for all the entity types of a specific service (using full entity type name with namespace)

1
2
3
4
$allEntityTypes = Get-ERPEntityTypes -Service 'http://services.odata.org/V3/Northwind/Northwind.svc'
$allEntityTypes | foreach {
        New-ERPObject ($_.Namespace+'.'+$_.Name) #example: NorthwindModel.Shipper
}

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

../../../_images/settings_dialog_entity_type_and_field_mappings.png 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
...
$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
#>





Instantiate a new ERP entity with specific field values

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
$order = New-ERPObject -Type 'SalesOrder' -Properties @{
    'OrderID' = 1001
    'OrderDate' = (Get-Date).AddDays(-1)

    # complex type property:
    'Address' = @{
        'Street' = 'Industriestrasse 1'
        'ZipCode' = '4020'
        'City' = 'Linz'
        'Country' = 'AT'
    }
}

$order.BusinessPartners = @(Get-ERPObject -EntitySet 'Partners' -Keys @{'TenantID'=66}) # add existing entity to collection of navigation properties
$order.BusinessPartners += New-ERPObject -Type 'Partner' -Properties @{'TenantID' = 67
    'Region' = New-ERPObject 'Address' -Properties @{'Country'='DE';'City'='Berlin'} # complex type property
}

Error handling, analyze why no default ERP object is created, by using $Error

1
2
3
4
5
6
Connect-ERP -Service "http://services.odata.org/V3/Northwind/Northwind.svc"
$entity = New-ERPObject -Type "People"

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