# Using the powerGate Cmdlets

```{image} /img/getting_started/powergate_console.png
   :width: 450px
   :class: float-right
```

## 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](<inv: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>) Cmdlet.

:::{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 Cmdlet [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.\
The metadata information for the **key properties** of the entity can be retrieved using following:

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

$itemsEntityType = Get-ERPEntityTypes -EntitySet $entitySet.Name
$keyProperties = $itemsEntityType.Keys
```

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

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

$keys = @{ 'Number'='100001' }
```

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 [Update-ErpObject](</code_reference/commandlets/update-erpobject>) Cmdlet.\
First setup a Hashtable, with the values you want to update.

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

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

$updatedProperties = @{ 'Material'='uranium'; 'UnitOfMeasure'='Bq' }
```

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

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

$updatedEntity = Update-ERPObject -EntitySet $entitySet.Name -Keys $keys -Properties $updatedProperties
```

## Add an entity to ERP

The [](</code_reference/commandlets/new-erpobject>) cmdlet allows you to create a new and empty instance of the required EntityType and pre-fill it with data that can be passed to the [Add-ERPObject](</code_reference/commandlets/add-erpobject>) to create a new entity in ERP.


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

$newEntityProperties = New-ERPObject -EntityType $itemsEntityType.Name -Properties @{'Number'='100002'; 'Material'='Einsteinium'; 'UnitOfMeasure' = "Bq"}
Add-ERPObject -EntitySet $entitySet.Name -Properties $newEntityProperties
```

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