# Using the powerGate Cmdlets

```{image} img/powergate_console.png
:align: right
:width: 250px
```

## Start the powershell environment

In order to get started either open any powershell IDE and load the powerGate Module by calling `Import-Module powerGate` or open the powerGate Console shortcut in the start menu, which already loads powerGate for you.

## Connect with ERP system

Before you are able to work with your ERP-System you have to connect to [powerGateServer](powergateserver:installation) or directly your ERP system (if it support's an OData interface). This can be done by calling [Connect-Erp](/code_reference/commandlets/connect-erp).

Some public accessible OData-Services for testing can be found [here](http://www.odata.org/odata-services/).

## Get multiple entities from ERP

After you are connected, you want to work with entities. In order to get the entities you have to know the appropriate **EntitySet**.\
The list of available EntitySet's can be retrieved with the [Get-ERPEntitySets](/code_reference/commandlets/get-erpentitysets) commandlet.

```{note}
If you want to get the names of the EntitySet's you can access them via [$entitySet.Name](/code_reference/commandlets/objects/entityset)
```

Now you know the name of the different entitiyTypes, therefore you can finally get some entities with commandlet [Get-ErpObjects](/code_reference/commandlets/get-erpobjects).

```{note}
[Get-ErpObjects](/code_reference/commandlets/get-erpobjects) has many optional parameters like **-Top -Filter -Expand**. See detailed documentation for them.
```

## Get a specific entity from ERP

In order to get a specific entity you have to know their key properties which identifies them.\
At this point you probably don't know the **key properties** of the entity. This might help:

```{code-block} powershell
:linenos:

$allEntityTypes = Get-ERPEntityTypes
$refPropNames = $allEntityTypes[0].Keys
```

First set up the keys for your entity as a Hashtable:

```{code-block} powershell
:linenos:

$keys = @{ Number="100001" Language="DE" }
```

Execute [Get-ErpObject](/code_reference/commandlets/get-erpobject) with the mandatory arguments EntitySet and Keys.

```{code-block} powershell
:linenos:

$entity = Get-ERPObject -EntitySet $entitySet.Name -Keys $keys
```

## Update an existing entity

In case you want to change some values of the entity you can achieve this with the [Udpate-ErpObject](/code_reference/commandlets/update-erpobject) commandlet.\
First setup a Hashtable, with the values you want to update.

```{note}
**Key** properties can **NOT** be modified!
```

```{code-block} powershell
:linenos:

$updatedProperties = @{ Type = "uranium" UnitOfMeasure = "Bq" }
```

Execute the commandlet with the entity-keys and properties and it returns the updated entity.

```{code-block} powershell
:linenos:

$updatedEntity = Update-ERPObject -EntitySet "Materials" -Keys $keys -Properties $updatedProperties
```

## Add an entity to ERP

The [Add-ERPObject](/code_reference/commandlets/add-erpobject) cmdlet allows you to create a new entity in ERP.\
Again setup a Hashtable with the values of the new entity you want to create.

```{code-block} powershell
:linenos:

$newEntity = @{ Number = "100002" Type = "Einsteinium" UnitOfMeasure = "Bq", }
```

Execute the commandlet with the **EntitySet** you want the entity to
create for and your entity hashtable as parameters.

```{code-block} powershell
:linenos:

Add-ERPObject -EntitySet "Materials" -Properties $newEntity
```

## Upload file to ERP

You may want to attach/link a Pdf file to an entity. This operation is called [Add-ErpMedia](/code_reference/commandlets/add-erpmedia).\
It will create the entity on the server side and upload and link the file with the newly created entity.