Deploying Apps to Industrial Edge Devices¶

This document highlights different use cases to deploy and manage an application to Industrial Edge Devices using APIs offered by Industrial Edge Management. For a very basic app deployment using the IEM APIs, you need to send four HTTP requests related api documentation:

a POST request with your username and password and receive a lightweight token that will enable you as a user to authenticate future requests.
a GET request to receive the ID of the application that you would like to install.
a GET request to receive the ID of the Edge device that you would like to install the application on.
a POST request to deploy the desired application to the chosen Edge device.

More complex installation methods are variations of these four basic requests.

Basic deployment¶

Get authentication token for IEM API¶

See Authentication guide.

Get Industrial Edge Application ID¶

For deploying an Industrial Edge application to target Edge Devices, you require an application ID as an unique identifier of the application.

You can list all available applications including the application ID by using this request:

curl -H "Authorization:<your-authorization-token>" -H "Content-Type:application/json" --insecure 'https://<your-iem-url>/portal/api/v1/applications'

Get Target Industrial Edge Device ID¶

You can deploy an Industrial Edge application to one or multiple target Industrial Edge Devices, you require device IDs as unique identifier of the target devices. You can list all available Industrial Edge Devices including the device ID by using this request:

curl -H "Authorization:<your-authorization-token>" -H "Content-Type:application/json" --insecure 'https://<your-iem-url>/portal/api/v1/devices'

Deploy An Application Without Any Configuration¶

If you want to deploy an application to a specific Edge Device, you need to submit a batch job to the IEM. This job contains all the information required to install the application on the Industrial Edge Device.

You can create a batch job by using a multipart request, which can contain additional metadata and configuration depending on your use case.

In the simplest way, you can deploy an application without any configuration to one or many Edge Devices. You require the application ID as unique identifier of the Industrial Edge application as well as the device IDs as unique identifiers for the target Industrial Edge Devices.

Use this request, tO deploy an app without any configuration:

curl -i -X POST -H "Authorization:<your-authorization-token>" -H "Content-Type:multipart/form-data" -F "infoMap= {\"devices\":[\"<your-device-id>\"]}" --insecure 'https://<your-iem-url>/portal/api/v1/batches?appid=<your-app-id>&operation=installApplication'

Complex deployment¶

Generally, you can list all available configurations by using this API.

Versioned Configuration¶

If the end user does not want to change the default configuration, an Industrial Edge application can be deployed using the versioned configuration type. Therefore, it is required to have a configuration ID as a unique identifier of the configuration.

Use the following request with cURL to deploy an Industrial Edge application to one or multiple Industrial Edge Devices:

    curl -i -X POST \
    -H "Authorization:<your-authorization-token>" \
    -H "Content-Type:multipart/form-data" \
    -F "infoMap={\"configs\":[{\"configId\":\"<your-configuration-id>\",\"versionId\":\"<your-configuration-version-id>\"}] \
    ,\"devices\":[\"<your-device-id>\"]}" \
    'https://<your-iem-url>/portal/api/v1/batches?appid=<your-app-id>&operation=installApplication'

Templated Configuration¶

If the end user should adapt your default configuration, you can deploy an app using the configuration type templated. Again, it is required to have a configuration ID as a unique identifier of the configuration.

Use this request to deploy an application to one or multiple Edge Devices:

    curl -i -X POST \
    -H "Authorization:<your-authorization-token>" \
    -H "Content-Type:multipart/form-data" \
    -F "infoMap={\"configs\":[{\"configId\":\"<your-configuration-id>\",\"templateId\":\"<your-template-id>\", \
    "editedTemplateText\":\"{\n\t\\"tab1\\":\\"##$hello$##\\"\n}\n\"}"}
    ],\"devices\":[\"<your-device-id>\"]}" \
    'https://<your-iem-url>/portal/api/v1/batches?appid=<your-app-id>&operation=installApplication'

Unversioned Configuration¶

If the end user would like to use his own configuration, you can deploy an app using the configuration type unversioned. Again, it is required to have a configuration ID as a unique identifier of the configuration.

Use this request to deploy an application to one or multiple Edge Devices:

    curl -i -X POST \
    -H "Authorization:<your-authorization-token>" \
    -H "Content-Type:multipart/form-data" \
    -F "infoMap= {\"configs\":[{\"configId\":\"<your-configuration-id>\",\"fileId\":\"<unique-file-id>\"}], \
    \"devices\":[\"<your-device-id>\"]}" \
    -F "<unique-file-id>=@\"/home/Desktop/temp/example.txt\";filename=\"example.txt\"" \
    'https://<your-iem-url>/portal/api/v1/batches?appid=<your-app-id>&operation=installApplication'

Mixed Configuration¶

You can also combine all previous mentioned configuration types in a single request:

    curl -i -X POST \
    -H "Authorization:<your-authorization-token>" \
    -H "Content-Type:multipart/form-data" \
    -F "infoMap= {\"configs\":[{\"configId\":\"<your-first-configuration-id>\",\"templateId\":\"<your-first-template-id>\"}, \
    {\"configId\":\"<your-second-configuration-id>\",\"templateId\":\"<your-second-template-id>\", \
    \"editedTemplateText\":\"{\n\t\\"tab1\\":\\"##$hello$##\\"\n}\"},{\"configId\":\"<your-third-configuration-id>\", \
    \"versionId\":\"<your-configuration-version-id>\"}, \
    {\"configId\":\"<your-fourth-configuration-id>\",\"fileId\":\"<unique-file-id>\"}],\"devices\":[\"<your-device-id>\"]}" \
    -F "<unique-file-id>=@\"/home/Desktop/temp/example.txt\";filename=\"example.txt\"" \
    'https://<your-iem-url>/portal/api/v1/batches?appid=<your-app-id>&operation=installApplication'

Deployment Scheduling¶

Furthermore, you can schedule the deployment of an Industrial Edge application at a certain time, for this you require the schedule parameter and provide an epoch timestamp in milliseconds.

Use the following request as an example:

    curl -i -X POST \
    -H "Authorization:<your-authorization-token>" \
    -H "Content-Type:multipart/form-data" \
    -F "infoMap= {\"devices\":[\"<your-device-id>\"]}" \
    'https://<your-iem-url>/portal/api/v1/batches?\
    appid=<your-app-id>&operation=installApplication&schedule=<epoch timestamp in milliseconds>'

Update Configurations¶

You can update a running application with a new configuration by using this request:

    curl -i -X POST \
    -H "Authorization:<your-authorization-token>" \
    -H "Content-Type:multipart/form-data" \
    -F "infoMap={\"configs\":[{\"configId\":\"<your-configuration-id>\",\"versionId\":\"<your-configuration-version-id>\"}], \
    \"actions\":{\"OPERATION\":\"restart\"},\"devices\":[\"<your-device-id>\"]}" \
    'https://<your-iem-url>/portal/api/v1/batches?appid=<your-app-id>&operation=updateAppConfig'

Perform Operational Tasks on An Industrial Edge Application¶

You can use following values as operation query parameter to perform a desired task:

startApplication
stopApplication
restartApplication
uninstallApplication

    curl -i -X POST \
    -H "Authorization:<your-authorization-token>" \
    -H "Content-Type:multipart/form-data" \
    -F "infoMap={\"devices\":[\"<your-device-id>\"]}" \
    'https://<your-iem-url>/portal/api/v1/batches?appid=<your-app-id>&operation=startApplication'

List App Configurations¶

You can also list all configurations for a specific application. You require an application ID as unique identifier of the Industrial Edge application.

Use this request to list the configurations:

    curl -i -X GET \
    -H "Authorization:<your-authorization-token>" \
    'https://<your-iem-url>/portal/api/v1/applications/<your-application-id>/configs'

List App Details¶

You can also get all details for a specific application. You require an application ID as unique identifier of the Industrial Edge application.

Use this request to list the configurations:

    curl -i -X GET \
    -H "Authorization:<your-authorization-token>" \
    'https://<your-iem-url>/portal/api/v1/applications/<your-application-id>'

A successful response looks like this:

{
    "id": "hI5FOxrLcRCQ7doCpoQTDLXTki8al5sI",
    "projectId": "d4f9b1e0f2a2429a9d44eb9c872845ea",
    "icon": "https://localhost:443/pp/PortalCache/app/hI5FOxrLcRCQ7doCpoQTDLXTki8al5sI/appicon.png",
    "title": "test",
    "description": "test",
    "appStatus": "PUBLISHED",
    "appVersions": [
        {
            "versionId": "MyVXdONT5Mq5JBRxFl56thmZwowl6tYk",
            "versionNumber": "0.0.5"
        }
    ]
}