# Add-ERPMedia

Cmdlet to create a streamable entity with a given media file.

## Syntax

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

Add-ERPMedia [[-EntitySet] <String>] [[-File] <String>]] [[-Properties] <Object>] [[-ContentType] <String>]] [<CommonParameters>]
```

## Parameters

| Type                 | Name        | Description                                                                                                                                                                                                                       | Optional |
|----------------------|-------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|
| String               | EntitySet   | The EntitySet name where the Media Link Entity is located. </br> It is also possible to specify additional namespaces or the whole url (e.g MaterialService/Materials, <http://localhost:8080/PGS/ERP/MaterialService/Materials>) | no       |
| String               | File        | Path to the file to upload                                                                                                                                                                                                        | no       |
| Hashtable / PSObject | Properties  | The properties for the entity being created. Those are passed as [Slug-Header][] to the server                                                                                                                                    | yes      |
| String               | ContentType | Specifies the content type of the web request. If no content type is provided Add-ERPMedia sets the content type depending on the file extension. (e.g .txt ⇒ 'text/plain', .pdf ⇒ 'application/pdf' …)                           | yes      |

  [Slug-Header]: https://tools.ietf.org/html/rfc5023#page-30


## Return type

[Entity](</code_reference/commandlets/objects/entity>) ← on success\
**empty** ← on failure. Exception/ErrorMessage can be accessed using [\$Error](<https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_automatic_variables?view=powershell-5.1#error>).\
If the cmdlet fails due to error responses returned by the ERP system, the \$Error variable provides a [WebRequestException](</code_reference/net_library/webrequestexception>) .

## Remarks

The Cmdlet is used to create [Media Link Entries (MLEs)](<http://www.odata.org/documentation/odata-version-2-0/operations>) with the request body containing the Media Resource (MR) and the Content-Type header indicating its media type.\
In other words it will create a streamable entity (Media Link Entry) and upload it together with the specified file (Media Resource).

The **ContentType** is used to specify the nature of the file currently being handled. With the appropriate content type the web browser can open the file with the proper extension/plugin.

> - If no content type is set the Cmdlet will determine the content type depending on the file type.
> - If the content type contains text (e.g text/plain, text/html...) as type or json , xml (e.g application/json, application/xml...) as subtype, then the content of the file is uploaded to the server as UTF-8 Encoded text.

The **Properties** are passed as [Slug-Header](<https://tools.ietf.org/html/rfc5023#page-30>) to the server, in the [augmented BNF syntax](<https://tools.ietf.org/html/rfc2616#section-2.1>).\
Please note, that the field-values are passed in JSON-format (depending on the OData-version) to the server. The Slug header is send as defined in [Atom Publishing Protocol](<https://tools.ietf.org/html/rfc5023#page-30>) by encoding the data to UTF-8 and later using percent encoding (for all octets outside the ranges %20-24 and %26-7E)!

:::{note}
All Properties are formatted in **following format**: `Property1='SomeText',Property2=666`\
This format is supported by [SAP](<http://go.sap.com/>) and [powergateserver](<inv:powergateserver#index>). Note that other ERP systems could expect data in different format!
:::

Since OData-Servers can create the Media Link Entry completely without using the Slug-Header, the server will respond with the created Media Link Entry, or at least by passing a link to the created MLE in the Location header.\
In both cases the cmdlet will take care about returning the newly created Media Link Entry.

## Examples

In the following example we are using the public OData Services (<http://services.odata.org>) for demonstration purposes:

**Create Media Link Entry (MLE)**

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

Connect-Erp -Service "http://services.odata.org/V4/OData/(S(du4oaehbpzqh2eznhygi1xkg))/OData.svc"
Add-ERPMedia -EntitySet "Advertisements" -File "C:\Temp\TestMedia.txt"
<#
        ID : 7fb23d89-f6b0-4010-b789-2d6e39b62187
        Name :
        AirDate : 01.01.2000 00:00:00 +00:00
#>
```

In the following examples we are using a custom plugin for the `powergateserver:index`:

**Create Media Link Entry (MLE) with specific properties**

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

Connect-Erp -Service "http://localhost:8080/powerGate.Tests/TestService"
Add-ERPMedia -EntitySet "Files" -Properties @{"Id"=2;"FileName"="SampleFile";"Size"=999} -File "C:\Temp\TestMedia.txt"
<#
        Id : 2
        Created : 01/01/0001 00:00:00
        Size : 999
        Value : {}
        FileName : SampleFile
#>
```

**Error handling, analyze why the Media Link Entry could not be created, by using \$Error**

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

Connect-ERP https://services.odata.org/V3/Northwind/Northwind.svc 
$mediaEntity = Add-ERPMedia -EntitySet Categories -File C:\Temp\CategoryIcon.png

if(-not $mediaEntity){
        $Error[0].Exception #"EntityType Category is not streamable!"
}
```