Invoke-ERPOperation

Cmdlet to invoke an OData action or function exposed by an ERP service.

Syntax

Invoke-ERPOperation [-Name] <string> [[-Service] <string>] [[-EntitySet] <string>] [[-Keys] <Object>] [[-Parameters] <Object>] [[-Property] <string>] [<CommonParameters>]

Parameters

Type	Name	Description	Optional
String	Name	The name of the OData action or function to invoke. Specify the operation name with or without its namespace, for example `GetBestProduct` or `NorthwindModel.GetBestProduct`.	no
Hashtable	Parameters	Additional operation parameters. The keys must match the parameter names defined by the ERP service. Values can be primitive values, collections, hashtables, or ERP entities and complex types created with New-ERPObject. Use nested hashtables for complex values when an ERP object is not required.	yes
String	Service	The ERP service that exposes the operation. It is also possible to specify additional namespaces or the whole service URL.	yes
String	EntitySet	The entity set containing the resource on which to invoke the operation. Do not specify this parameter for an unbound operation.	yes
Hashtable / PSObject	Keys	The reference properties for the entity. This parameter is required when the operation is bound to a specific entity.	yes
String	Property	An additional resource path after the binding resource, for example a navigation property, complex type property, or primitive property. This parameter is available only when -Keys is specified.	yes

Return type

The operation metadata defines whether the action or function returns a value.
It also defines the type of the returned value, such as an entity, complex type, collection, primitive value, or no value.

An empty result can indicate either a successful operation without a return value or a failed operation. Always check $? to distinguish these cases.

Return value	Description
Entity	A single entity or complex type.
Entity[]	An array of entities or complex types.
Primitive data value	The primitive value returned by the ERP operation, for example a Boolean or Int32.
empty	The operation completed successfully without returning a value (`$? -eq $true`). The operation metadata does not define a return value.
empty	The operation failed (`$? -eq $false`). Exception/ErrorMessage can be accessed using $Error. If the cmdlet fails due to an error response returned by the ERP system, the $Error variable provides a WebRequestException.

Remarks

OData actions and functions can be either bound or unbound.

Bound operations are invoked on a resource whose type matches their binding parameter.
The binding parameter can be an entity type, complex type, primitive type, or a collection of any of these types.
Unbound operations are invoked as static operations on the service.
Functions have no observable side effects and are invoked with GET.
Actions may have observable side effects and are invoked with POST.

For more information about the OData protocol, see Actions and functions, invoking an action, and invoking a function.

To see which operations are available in connected services, use Get-ERPServices and inspect the Operations property.

For a bound operation, specify -EntitySet to identify the entity set containing the binding resource. To invoke an operation on one particular entity, also specify -Keys.
The -Property parameter can be used to continue through an additional resource path after the entity identified by -Keys, for example through a navigation property or complex type property.

An operation can define no parameters, one parameter, or multiple parameters. Pass these operation parameters with -Parameters as a hashtable.
The parameter names specified in -Parameters must match the names defined in the service metadata.

Examples

In the following examples we are using the public OData reference services for demonstration purposes:

Invoke an unbound function with parameters

Connect-ERP -Service 'https://services.odata.org/TripPinRESTierService/(S(2i2cpsx2vit2sqryn5mglfc1))/'
$airport = Invoke-ERPOperation -Name 'GetNearestAirport' -Parameters @{ lat = 33; lon = -118 }

Invoke an unbound action

Connect-ERP -Service 'https://services.odata.org/TripPinRESTierService/(S(2i2cpsx2vit2sqryn5mglfc1))/'
Invoke-ERPOperation -Name 'ResetDataSource'

Invoke a bound action with parameters

Connect-ERP -Service 'https://services.odata.org/TripPinRESTierService/(S(2i2cpsx2vit2sqryn5mglfc1))/'
Invoke-ERPOperation -Name 'Trippin.ShareTrip' -EntitySet 'People' -Keys @{ UserName = 'russellwhyte' } Parameters @{ 'userName' = 'scottketchum'; 'tripId' = 0 }

Invoke a bound function reached through a navigation property

Connect-ERP -Service 'https://services.odata.org/TripPinRESTierService/(S(2i2cpsx2vit2sqryn5mglfc1))/'
Invoke-ERPOperation -Name 'Trippin.GetInvolvedPeople' -EntitySet 'People' -Keys @{ UserName = 'russellwhyte' } -Property 'Trips(0)'

<#
AddressInfo     : {@{City=; Address=187 Suffolk Ln.; _Keys=; _Properties=}}
HomeAddress     :
UserName        : russellwhyte
FirstName       : Russell
LastName        : Whyte
MiddleName      :
Gender          : Male
Age             :
Emails          : {Russell@example.com, Russell@contoso.com}
FavoriteFeature : Feature1
Features        : {Feature1, Feature2}

...

AddressInfo     : {@{City=; Address=2817 Milton Dr.; _Keys=; _Properties=}}
HomeAddress     :
UserName        : scottketchum
FirstName       : Scott
LastName        : Ketchum
MiddleName      :
Gender          : Male
Age             :
Emails          : {Scott@example.com}
FavoriteFeature : Feature1
Features        : {}
#>

Pass a complex type as an operation parameter using New-ERPObject

$input = New-ERPObject -EntityType 'NewAirportInput'
$input.Name = 'Innsbruck Airport'
$input.IcaoCode = 'LOWI'
$input.IataCode = 'INN'

$result = Invoke-ERPOperation -Name 'CreateAirportFromInput' -Parameters @{ input = $input }

Error handling: Check if an error appeared by using $? and analyze the WebRequestException to understand why the operation could not be invoked

Connect-ERP -Service 'https://services.odata.org/TripPinRESTierService/(S(2i2cpsx2vit2sqryn5mglfc1))/'
$result = Invoke-ERPOperation -Name 'OperationDoesNotExist'

if(-not $result) {
    if($? -eq $false) {
        $Error[0].Exception.StatusCode #404
        $Error[0].Exception.Message
        $Error[0].Exception.RawResponse
        $Error[0].Exception.Response.ErrorCode
    }
    else {
        Write-Host("The operation returned no result.")
    }
}