### Example Filename Pattern

Source: https://industrial-assets.io/developers/asset-schema/how-to

Illustrates the naming convention for example YAML files used in schema development. The pattern ensures clarity by including the class name and an index.

```text
<class>-xyz.yaml
For example: Device-001.yaml
```

--------------------------------

### Execute Setup Script for WSL and Asset Gateway on Windows

Source: https://industrial-assets.io/developers/getting-started/iah-compose-stack/index

This PowerShell command executes the local setup script for the Windows Subsystem for Linux (WSL) and the Asset Gateway. It bypasses execution policy for the current user and runs the script. Ensure your execution policy is adapted if necessary.

```powershell
Set-ExecutionPolicy Bypass -Scope CurrentUser; .\run-local.ps1
```

--------------------------------

### Run Local Asset Links with Docker Compose

Source: https://industrial-assets.io/developers/getting-started/iah-compose-stack/index

This command starts local Asset links using the provided Docker Compose stack. It takes a comma-separated list of Asset link names to initiate.

```bash
./run-local.bash dummy,snmp

```

--------------------------------

### Asset Identifiers Examples

Source: https://industrial-assets.io/developers/asset-schema/asset_identifiers

Demonstrates various ways to represent asset identifiers, including structured data for nameplates and product IDs, UUIDs, MAC addresses, and device certificates. These examples illustrate the flexibility and richness of the asset_identifiers attribute.

```yaml
name: asset_identifiers
description: 'An asset identifier is an asset attribute that provides enough information
  to unequivocally identify the represented object.

  In some cases the ID attribute acts simultaneously as a reference for the asset
  instance and as identifier for the represented object, otherwise at least one asset
  identifier is needed.

  There can be multiple asset_identifiers with different goals. For example, the information
  of a metal nameplate can be used by a human-being to identify a device represented
  by an asset instance, but a software certificate provided by a device might help
  a software component identify the device in the network,...

  An asset identifier might have an identifier_type, that defines its format and possibly
  even semantics.'
title: asset identifiers
examples:
- value: '''Nameplate'': { ''vendor id'': ''siemens'', ''product id'': ''1FN3050-1ND00-0EA3'',
    ''serial number'': ''0011223344'' }
  description: Object that provides a set of values that unequivocally identify a
    Siemens device.
- value: '''Product ID'': { ''Vendor'': ''Rexroth'', ''Type Code'': ''VDP16.3DBN-D1-NN-NN'',
    ''Type Name'': ''IndraControl VPB 40.4, Control Cabinet PC''}, ''Instance ID'':
    { ''Serial Number'': ''SN:008595411'' }
  description: Object that provides a set of values that unequivocally identify a
    Rexroth device.
- value: 123e4567-e89b-12d3-a456-426655440000
  description: Universal Unique ID (UUID AKA GUID) that identifies an asset instance.
- value: 123e4567-e89b-12d3-a456-426655440000
  description: Universal Unique ID (UUID AKA GUID) that identifies an asset instance.
- value: 'MAC-Address: 00:11:22:33:44'
  description: Identify a device by its MAC-Address, assuming that it cannot be changed.
- value: '''Device Certificate'': { ''Certificate ID'': ''1wlkq3'', ''Certificate
    PubKey'': ''xxxxxxxxxxxx'' }
  description: Information needed to challenge the certificate of a device with its
    public key.
from_schema: https://common-device-management.code.siemens.io/documentation/asset-modeling/base-schema/v0.12.0/iah-base.jsonld
rank: 1000
alias: asset_identifiers
domain_of:
- Asset
range: AssetIdentifier
recommended: true
multivalued: true
inlined: true
inlined_as_list: true

```

--------------------------------

### Asset Identifiers - Examples

Source: https://industrial-assets.io/developers/asset-schema/AssetLink

Demonstrates various formats for asset identifiers, including structured vendor-specific data, UUIDs, MAC addresses, and certificate information. These identifiers are crucial for unequivocally identifying an asset instance.

```json
{
  "Nameplate": {
    "vendor id": "siemens",
    "product id": "1FN3050-1ND00-0EA3",
    "serial number": "0011223344"
  }
}
```

```json
{
  "Product ID": {
    "Vendor": "Rexroth",
    "Type Code": "VDP16.3DBN-D1-NN-NN",
    "Type Name": "IndraControl VPB 40.4, Control Cabinet PC"
  },
  "Instance ID": {
    "Serial Number": "SN:008595411"
  }
}
```

```json
"123e4567-e89b-12d3-a456-426655440000"
```

```json
"MAC-Address: 00:11:22:33:44"
```

```json
{
  "Device Certificate": {
    "Certificate ID": "1wlkq3",
    "Certificate PubKey": "xxxxxxxxxxxx"
  }
}
```

--------------------------------

### GetVersionInfoResponse Message Definition

Source: https://industrial-assets.io/developers/device-builder/conn-suite-drv-info

Defines the response message for GetVersionInfo, containing VersionInfo.

```protobuf
message GetVersionInfoResponse {
  VersionInfo version = 1;
}
```

--------------------------------

### VersionInfo Message Definition

Source: https://industrial-assets.io/developers/device-builder/conn-suite-drv-info

Defines the structure for version information, including major, minor, patch, suffix, vendor name, product name, description, documentation URL, and feedback URL.

```protobuf
message VersionInfo {
  uint32 major = 1;
  uint32 minor = 2;
  uint32 patch = 3;
  string suffix = 4;
  string vendor_name = 5;
  string product_name = 6;
  string product_description = 7;
  string docu_url = 8;
  string feedback_url = 9;
}
```

--------------------------------

### Device Class Definition (LinkML)

Source: https://industrial-assets.io/developers/asset-schema/Device

This snippet defines the Device class using LinkML, outlining its description, examples, inheritance, and slot usage. It specifies required and recommended attributes for managing devices.

```yaml
name: Device
description: A device is a special type of asset that can be managed with some
  asset
  management system. In order to be manageable, it requires at least one connection
  point for the asset management to communicate with the device and software capable
  of interacting with the asset management.
examples:
- value: Industrial PC
- value: PLC
- value: Virtual Machine
in_subset:
- MostRelevant
from_schema: https://common-device-management.code.siemens.io/documentation/asset-modeling/base-schema/v0.12.0/iah-base.jsonld
close_mappings:
- sietechas:Device
rank: 10
is_a: Asset
slot_usage:
  software_components:
    name: software_components
    required: true
  reachability_state:
    name: reachability_state
    required: true
  connection_points:
    name: connection_points
    recommended: true

```

--------------------------------

### Driver Info API - GetConfigSchema

Source: https://industrial-assets.io/developers/device-builder/conn-suite-drv-info

Retrieves the configuration schema for the driver. This allows clients to understand the expected configuration parameters.

```APIDOC
## POST /DriverInfo/GetConfigSchema

### Description
Retrieves the configuration schema for the driver. This allows clients to understand the expected configuration parameters.

### Method
POST

### Endpoint
/DriverInfo/GetConfigSchema

### Parameters
#### Request Body
- **void** (void) - Required - No request body is expected for this call.

### Request Example
```json
{
  "example": "No request body"
}
```

### Response
#### Success Response (200)
- **schemas** (repeated ConfigSchema) - A list of configuration schemas.

#### Response Example
```json
{
  "schemas": [
    {
      "uri": "http://example.com/schema/v1",
      "schema": "{\"type\": \"object\", \"properties\": {\"param1\": {\"type\": \"string\"}}}"
    }
  ]
}
```

#### Error Response (FAILED_PRECONDITION)
- **message** (string) - Indicates that no local configuration is available or accessible.

#### Error Response Example (FAILED_PRECONDITION)
```json
{
  "message": "No local configuration available."
}
```
```

--------------------------------

### Driver Info API - GetVersionInfo

Source: https://industrial-assets.io/developers/device-builder/conn-suite-drv-info

Retrieves version information about the driver. This is a fundamental call to understand the driver's current version and compatibility.

```APIDOC
## POST /DriverInfo/GetVersionInfo

### Description
Retrieves version information about the driver. This is a fundamental call to understand the driver's current version and compatibility.

### Method
POST

### Endpoint
/DriverInfo/GetVersionInfo

### Parameters
#### Request Body
- **void** (void) - Required - No request body is expected for this call.

### Request Example
```json
{
  "example": "No request body"
}
```

### Response
#### Success Response (200)
- **version** (VersionInfo) - Version information of the driver.

#### Response Example
```json
{
  "version": {
    "major": 1,
    "minor": 0,
    "patch": 0,
    "suffix": "-0",
    "vendor_name": "Siemens AG",
    "product_name": "SIMATIC S7+ Connector",
    "product_description": "Connector for SIMATIC S7-1200 and S7-1500 PLCs using S7+ protocol",
    "docu_url": "https://example.com/docs",
    "feedback_url": "https://example.com/feedback"
  }
}
```
```

--------------------------------

### Software Components

Source: https://industrial-assets.io/developers/asset-schema/iah-base.schema

Lists the software components hosted by an asset, which can range from firmware versions to a full Software Bill of Materials (SBOM).

```APIDOC
## GET /assets/{assetId}/software-components

### Description
Retrieves a list of software components associated with a specific asset.

### Method
GET

### Endpoint
/assets/{assetId}/software-components

### Parameters
#### Path Parameters
- **assetId** (string) - Required - The unique identifier of the asset.

### Response
#### Success Response (200)
- **software_components** (array) - An array of software component objects.

#### Response Example
```json
{
  "software_components": [
    {
      "type": "SoftwareAsset",
      "name": "Example Firmware",
      "version": "1.2.3"
    },
    {
      "type": "SoftwareArtifact",
      "name": "Security Patch",
      "sha256": "a1b2c3d4..."
    }
  ]
}
```
```

--------------------------------

### Responsible User/Client

Source: https://industrial-assets.io/developers/asset-schema/iah-base.schema

Provides the ID of the user or client that onboarded the asset.

```APIDOC
## GET /assets/{assetId}/responsible

### Description
Retrieves the identifier of the user or client responsible for onboarding the asset.

### Method
GET

### Endpoint
/assets/{assetId}/responsible

### Parameters
#### Path Parameters
- **assetId** (string) - Required - The unique identifier of the asset.

### Response
#### Success Response (200)
- **responsible** (string) - The ID of the user or client.

#### Response Example
```json
{
  "responsible": "user-12345"
}
```
```

--------------------------------

### GW Onboarding API

Source: https://industrial-assets.io/developers/programing-interface/programing-interface

API for onboarding new gateways into Industrial Asset Hub (IAH). This API facilitates the process of integrating gateways into the platform.

```APIDOC
## Gateway Onboarding API

### Description
Documentation of the API used to onboard new gateways into IAH. Industrial Asset Hub Service Desk - Website

### Servers
- /onboarding/v1-earlyaccess/gateway

### gateway onboarding
API methods implemented on gateway onboarding service.

#### POST /initialize
**Description**: Start gateway onboarding.
**Method**: POST
**Endpoint**: /initialize

#### POST /initialize/{assetId}
**Description**: Onboard existing gateway.
**Method**: POST
**Endpoint**: /initialize/{assetId}

#### GET /initialize/{assetId}
**Description**: Gateway configuration for given asset id.
**Method**: GET
**Endpoint**: /initialize/{assetId}

#### PATCH /initialize/{assetId}
**Description**: Restart gateway onboarding.
**Method**: PATCH
**Endpoint**: /initialize/{assetId}

#### GET /initialize/status
**Description**: Get an expiry information for gateways.
**Method**: GET
**Endpoint**: /initialize/status

#### POST /establish
**Description**: Establish gateway connection.
**Method**: POST
**Endpoint**: /establish

#### DELETE /offboard/{assetId}
**Description**: Offboard gateway.
**Method**: DELETE
**Endpoint**: /offboard/{assetId}

#### Schemas
- Filter
- GatewayOnboarding
- CertificateBody
- ProblemDetails
```

--------------------------------

### GetVersionInfoRequest Message Definition

Source: https://industrial-assets.io/developers/device-builder/conn-suite-drv-info

Defines the request message for GetVersionInfo, which is an empty message.

```protobuf
message GetVersionInfoRequest {}
```

--------------------------------

### Asset Running Software API

Source: https://industrial-assets.io/developers/asset-schema/iah-base.schema

This section describes the software artifact from which the running software of an asset has been instantiated. Note that the combination of multiple software artifacts into a single running software is not natively supported and requires the use of instance annotations.

```APIDOC
## GET /assets/{assetId}/running-software

### Description
Retrieves information about the running software instance of a specific industrial asset.

### Method
GET

### Endpoint
/assets/{assetId}/running-software

### Parameters
#### Path Parameters
- **assetId** (string) - Required - The unique identifier of the asset.

#### Query Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **description** (string) - A reference to the software artifact.
- **custom_running_software_type** (string) - A custom type for the running software.

#### Response Example
```json
{
  "description": "Reference to the software artifact which the running software has been instantiated from.",
  "custom_running_software_type": "CustomFirmware_v2.1"
}
```
```

--------------------------------

### GetConfigSchemaRequest Message Definition

Source: https://industrial-assets.io/developers/device-builder/conn-suite-drv-info

Defines the request message for GetConfigSchema, which is an empty message.

```protobuf
message GetConfigSchemaRequest {}
```

--------------------------------

### AssetOperation LinkML Definition

Source: https://industrial-assets.io/developers/asset-schema/AssetOperation

Defines the AssetOperation class using LinkML, specifying its name, description, examples, and associated slots.

```yaml
name: AssetOperation
description: Operations that can be performed on the asset
title: Asset Operation
examples:
- value: Firmware Update
- value: Factory Reset
- value: Program Update
- value: Memory Reset
- value: Backup
in_subset:
- MostRelevant
from_schema: https://common-device-management.code.siemens.io/documentation/asset-modeling/base-schema/v0.12.0/iah-base.jsonld
rank: 1000
slots:
- operation_name
- activation_flag

```

--------------------------------

### Asset API - Asset Management

Source: https://industrial-assets.io/developers/programing-interface/programing-interface

This section covers the API methods for creating, reading, updating, and deleting Asset Models. Asset Models represent the core assets within the system, with Devices being a specialized subtype.

```APIDOC
## GET /assets

### Description
Retrieve the Asset Models of all managed assets in a list.

### Method
GET

### Endpoint
/assets

### Parameters
#### Query Parameters
* **malformedOrUnknownQueryParams** (any) - Ignored - Malformed or unknown query parameters will be ignored.

### Response
#### Success Response (200)
* **assetModels** (array) - A list of Asset Models.

#### Response Example
{
  "assetModels": [
    {
      "id": "string",
      "name": "string",
      "type": "string"
    }
  ]
}

## POST /assets

### Description
Create or Update new Asset Models with system-generated ID.

### Method
POST

### Endpoint
/assets

### Parameters
#### Request Body
* **assetModel** (object) - Required - The Asset Model to create or update.
  * **name** (string) - Required - The name of the asset.
  * **type** (string) - Required - The type of the asset.

### Request Example
{
  "assetModel": {
    "name": "Example Asset",
    "type": "Device"
  }
}

### Response
#### Success Response (200)
* **id** (string) - The system-generated ID of the created or updated Asset Model.

#### Response Example
{
  "id": "generated-asset-id"
}

## PATCH /assets/{id}

### Description
Patch an existing Asset Model.

### Method
PATCH

### Endpoint
/assets/{id}

### Parameters
#### Path Parameters
* **id** (string) - Required - The ID of the Asset Model to patch.

#### Request Body
* **updates** (object) - Required - An object containing the fields to update.

### Request Example
{
  "updates": {
    "name": "Updated Asset Name"
  }
}

### Response
#### Success Response (200)
* **message** (string) - Confirmation message of the update.

#### Response Example
{
  "message": "Asset Model updated successfully."
}

## GET /assets/{id}

### Description
Retrieve a specific Asset Model by its ID.

### Method
GET

### Endpoint
/assets/{id}

### Parameters
#### Path Parameters
* **id** (string) - Required - The ID of the Asset Model to retrieve.

### Response
#### Success Response (200)
* **assetModel** (object) - The requested Asset Model.

#### Response Example
{
  "id": "asset-id",
  "name": "Example Asset",
  "type": "Device"
}

## DELETE /assets/{id}

### Description
Delete an Asset Model by its ID.

### Method
DELETE

### Endpoint
/assets/{id}

### Parameters
#### Path Parameters
* **id** (string) - Required - The ID of the Asset Model to delete.

### Response
#### Success Response (200)
* **message** (string) - Confirmation message of the deletion.

#### Response Example
{
  "message": "Asset Model deleted successfully."
}

## PATCH /assets/{id}/reachability-state

### Description
Update the reachability state of an Asset Model.

### Method
PATCH

### Endpoint
/assets/{id}/reachability-state

### Parameters
#### Path Parameters
* **id** (string) - Required - The ID of the Asset Model.

#### Request Body
* **state** (string) - Required - The new reachability state (e.g., "Reachable", "Unreachable").

### Request Example
{
  "state": "Reachable"
}

### Response
#### Success Response (200)
* **message** (string) - Confirmation message of the update.

#### Response Example
{
  "message": "Reachability state updated successfully."
}

## PATCH /assets/{id}/responsible/{responsibleId}

### Description
Update the responsible user of an Asset Model.

### Method
PATCH

### Endpoint
/assets/{id}/responsible/{responsibleId}

### Parameters
#### Path Parameters
* **id** (string) - Required - The ID of the Asset Model.
* **responsibleId** (string) - Required - The ID of the responsible user.

### Response
#### Success Response (200)
* **message** (string) - Confirmation message of the update.

#### Response Example
{
  "message": "Responsible user updated successfully."
}

## GET /assets/values/{property}

### Description
Return all values of a specific property for all assets.

### Method
GET

### Endpoint
/assets/values/{property}

### Parameters
#### Path Parameters
* **property** (string) - Required - The name of the property for which to retrieve values.

### Response
#### Success Response (200)
* **values** (array) - A list of values for the specified property across all assets.

#### Response Example
{
  "values": [
    "value1",
    "value2"
  ]
}

## GET /assets/group

### Description
Retrieve the values of a specific asset attribute and their respective counts.

### Method
GET

### Endpoint
/assets/group

### Parameters
#### Query Parameters
* **attribute** (string) - Required - The asset attribute to group by.

### Response
#### Success Response (200)
* **groupedValues** (object) - An object where keys are attribute values and values are their counts.

#### Response Example
{
  "groupedValues": {
    "typeA": 10,
    "typeB": 5
  }
}

```

--------------------------------

### Driver Info API - GetAppIcon

Source: https://industrial-assets.io/developers/device-builder/conn-suite-drv-info

Retrieves the application icon for the driver in a preferred image format.

```APIDOC
## POST /DriverInfo/GetAppIcon

### Description
Retrieves the application icon for the driver in a preferred image format. The client can specify a list of supported image formats.

### Method
POST

### Endpoint
/DriverInfo/GetAppIcon

### Parameters
#### Request Body
- **supported_image_formats** (repeated string) - Optional - A list of supported image formats, sorted by preference (e.g., ["svg+xml", "png"]). "png" is mandatory.

### Request Example
```json
{
  "supported_image_formats": [
    "svg+xml",
    "png"
  ]
}
```

### Response
#### Success Response (200)
- **image_format** (string) - The image format of the returned image (e.g., "png", "svg+xml").
- **image_data** (bytes) - Byte array containing the image data.

#### Response Example
```json
{
  "image_format": "png",
  "image_data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="
}
```

#### Error Response (INVALID_ARGUMENT)
- **message** (string) - Indicates that the provided parameters are wrong.

#### Error Response Example (INVALID_ARGUMENT)
```json
{
  "message": "Invalid image format requested."
}
```

#### Error Response (UNIMPLEMENTED)
- **message** (string) - Indicates that this function is not supported by the server.

#### Error Response Example (UNIMPLEMENTED)
```json
{
  "message": "GetAppIcon is not implemented."
}
```

#### Error Response (FAILED_PRECONDITION)
- **message** (string) - Indicates that the icon is not available.

#### Error Response Example (FAILED_PRECONDITION)
```json
{
  "message": "Icon not available."
}
```
```

--------------------------------

### GetConfigSchemaResponse Message Definition

Source: https://industrial-assets.io/developers/device-builder/conn-suite-drv-info

Defines the response message for GetConfigSchema, containing a list of ConfigSchema objects.

```protobuf
message GetConfigSchemaResponse {
  repeated ConfigSchema schemas = 1;
}
```

--------------------------------

### ConfigSchema Message Definition

Source: https://industrial-assets.io/developers/device-builder/conn-suite-drv-info

Defines the structure for configuration schema, including the URI and the JSON schema string.

```protobuf
message ConfigSchema {
  string uri = 1;
  string schema = 2;
}
```

--------------------------------

### Software Asset Management

Source: https://industrial-assets.io/developers/asset-schema/iah-base.schema

This section details the structure and properties of a SoftwareAsset, which can host software artifacts for tracking purposes. It also outlines related types like SoftwareArtifact, RunningSoftware, AssetLink, Dcd, and Gateway.

```APIDOC
## SoftwareAsset Object

### Description
Represents a software asset hosted by an industrial asset, used for tracking firmware versions or Software Bills of Materials (SBOM). It can also reference other related software components or links.

### Properties

- **software_assets** (array | null) - A list of software assets or artifacts associated with the main asset. This can include references to SoftwareAsset, SoftwareArtifact, RunningSoftware, AssetLink, Dcd, or Gateway objects.
- **zone** (string | null) - The zone to which the asset belongs, typically used for logical grouping and access control.

### Required Properties

- **management_state**
- **id**
```

--------------------------------

### Remote Access API (v2)

Source: https://industrial-assets.io/developers/programing-interface/programing-interface_authorization-api

API used to retrieve Remote Access Jobs, get details for a specific job, delete a job, or cancel a job.

```APIDOC
## GET /jobs

### Description
Retrieve list of remote access jobs.

### Method
GET

### Endpoint
/jobs

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Maximum number of jobs to return.
- **offset** (integer) - Optional - Number of jobs to skip.

### Response
#### Success Response (200)
- **remoteJobOverviewResponse** (RemoteJobOverview) - Response containing a list of remote access jobs.

#### Response Example
```json
{
  "jobs": [
    {
      "jobId": "job-abc",
      "assetId": "asset-123",
      "status": "COMPLETED",
      "createdAt": "2023-10-27T11:00:00Z"
    }
  ],
  "page": {
    "total": 1,
    "limit": 10,
    "offset": 0
  }
}
```
```

```APIDOC
## GET /jobs/{jobId}

### Description
Retrieve details of a remote access job for a given jobId.

### Method
GET

### Endpoint
/jobs/{jobId}

### Parameters
#### Path Parameters
- **jobId** (string) - Required - The ID of the remote access job.

### Response
#### Success Response (200)
- **remoteAccessJob** (remoteAccessJob) - Details of the remote access job.

#### Response Example
```json
{
  "jobId": "job-abc",
  "assetId": "asset-123",
  "status": "COMPLETED",
  "createdAt": "2023-10-27T11:00:00Z",
  "completedAt": "2023-10-27T11:05:00Z"
}
```
```

```APIDOC
## DELETE /jobs/{jobId}

### Description
Delete a remote connection job.

### Method
DELETE

### Endpoint
/jobs/{jobId}

### Parameters
#### Path Parameters
- **jobId** (string) - Required - The ID of the remote access job to delete.

### Response
#### Success Response (204)
No content.
```

```APIDOC
## PATCH /jobs/{jobId}/cancel

### Description
Cancel a remote access job for a given jobId.

### Method
PATCH

### Endpoint
/jobs/{jobId}/cancel

### Parameters
#### Path Parameters
- **jobId** (string) - Required - The ID of the remote access job to cancel.

### Response
#### Success Response (200)
- **updatedState** (updatedState) - The updated state of the job.

#### Response Example
```json
{
  "jobId": "job-abc",
  "status": "CANCELLED"
}
```
```

--------------------------------

### LinkML Source for ManagementState

Source: https://industrial-assets.io/developers/asset-schema/ManagementState

This snippet shows the LinkML definition for the ManagementState class. It includes the name, description, title, schema source, rank, and inheritance. It also specifies the usage of the 'state_value' slot with its range.

```yaml
name: ManagementState
description: Documents if the asset is being regarded (managed) by any AssetManagement
  or not. AssetManagement systems regarding the asset will be listed in the "managedBy"
  property.
title: Management State
from_schema: https://common-device-management.code.siemens.io/documentation/asset-modeling/base-schema/v0.12.0/iah-base.jsonld
rank: 1000
is_a: State
slot_usage:
  state_value:
    name: state_value
    range: ManagementStateValues

```

--------------------------------

### Identifier Class Definition (LinkML)

Source: https://industrial-assets.io/developers/asset-schema/Identifier

Defines the Identifier class using LinkML, including its name, description, examples, source schema, and associated slots.

```yaml
name: Identifier
description: 'An element that provides an unambiguous identification of an item.

  It can be an object, in which case the combination of the attributes specified as
  "unique keys" must be unique.'
examples:
- value: The combination of the 'manufacturer' 'Siemens' and the 'order ID' '6DR5513-0NG00-0AA0'.
- value: a combination of the values "vendor", "product ID" and "serial number"
- value: a MAC-address (can be modified on some systems, but might be considered static
    on certain environments)
from_schema: https://common-device-management.code.siemens.io/documentation/asset-modeling/base-schema/v0.12.0/iah-base.jsonld
close_mappings:
- sieiot:ThingIdentifier
rank: 1000
slots:
- identifier_type
- identifier_uncertainty

```

--------------------------------

### Asset API - Asset Views and Metrics

Source: https://industrial-assets.io/developers/programing-interface/programing-interface

This section covers API methods for retrieving asset views and metrics gathered by the inventory.

```APIDOC
## GET /assets/{id}/views

### Description
Retrieve the views of a specific asset.

### Method
GET

### Endpoint
/assets/{id}/views

### Parameters
#### Path Parameters
* **id** (string) - Required - The ID of the asset.

### Response
#### Success Response (200)
* **views** (array) - A list of views for the asset.

#### Response Example
{
  "views": [
    {
      "id": "view-1",
      "name": "Overview"
    }
  ]
}

## PUT /assets/{id}/leading-view

### Description
Set the leading view of an asset.

### Method
PUT

### Endpoint
/assets/{id}/leading-view

### Parameters
#### Path Parameters
* **id** (string) - Required - The ID of the asset.

#### Request Body
* **viewId** (string) - Required - The ID of the view to set as leading.

### Request Example
{
  "viewId": "view-1"
}

### Response
#### Success Response (200)
* **message** (string) - Confirmation message of the operation.

#### Response Example
{
  "message": "Leading view set successfully."
}

## GET /metrics/discovery-result/{correlationId}

### Description
Retrieve the discovery-result metrics of a device discovery.

### Method
GET

### Endpoint
/metrics/discovery-result/{correlationId}

### Parameters
#### Path Parameters
* **correlationId** (string) - Required - The correlation ID for the discovery job.

### Response
#### Success Response (200)
* **discoveryResultMetrics** (object) - The discovery result metrics.

#### Response Example
{
  "discoveryResultMetrics": {
    "status": "Success",
    "discoveredAssets": 5
  }
}

## GET /metrics/validation-result/{correlationId}

### Description
Retrieve the validation-result metrics of a device discovery.

### Method
GET

### Endpoint
/metrics/validation-result/{correlationId}

### Parameters
#### Path Parameters
* **correlationId** (string) - Required - The correlation ID for the discovery job.

### Response
#### Success Response (200)
* **validationResultMetric** (object) - The validation result metrics.

#### Response Example
{
  "validationResultMetric": {
    "status": "Passed",
    "validatedAssets": 3
  }
}

```

--------------------------------

### GetAppIconResponse Message Definition

Source: https://industrial-assets.io/developers/device-builder/conn-suite-drv-info

Defines the response message for GetAppIcon, containing the image format and image data. Currently, only 'png' is supported.

```protobuf
message GetAppIconResponse {
  string image_format = 1;
  bytes image_data = 2;
}
```

--------------------------------

### Product Instance Identifier

Source: https://industrial-assets.io/developers/asset-schema/iah-base.schema

Provides an identifier for a device based on its serial number.

```APIDOC
## GET /assets/{assetId}/product-instance-identifier

### Description
Retrieves the product instance identifier (serial number) for a specific asset.

### Method
GET

### Endpoint
/assets/{assetId}/product-instance-identifier

### Parameters
#### Path Parameters
- **assetId** (string) - Required - The unique identifier of the asset.

### Response
#### Success Response (200)
- **product_instance_identifier** (string) - The serial number of the product instance.

#### Response Example
```json
{
  "product_instance_identifier": "SN123456789"
}
```
```

--------------------------------

### GetAppIconRequest Message Definition

Source: https://industrial-assets.io/developers/device-builder/conn-suite-drv-info

Defines the request message for GetAppIcon, specifying supported image formats in order of preference. 'png' is mandatory.

```protobuf
message GetAppIconRequest {
  repeated string supported_image_formats = 1;
}
```

--------------------------------

### Discovery Profile Configuration for versions < V1.4.0 (JSON)

Source: https://industrial-assets.io/developers/device-builder/device-class-drivers/snmp-driver

This JSON configuration outlines discovery profiles for SNMP versions SNMP V2, SNMP V1, and SNMP V3, intended for versions prior to 1.4.0. It specifies parameters such as communities, port, timeout, retry, and SNMPv3 security details.

```json
{
    "discovery_profiles":[
        {
            "version":"SNMP V2",
            "readCommunity":"public",
            "writeCommunity":"private",
            "port":161,
            "timeout":2000,
            "retry":3
        },
        {
            "version":"SNMP V1",
            "readCommunity":"public",
            "writeCommunity":"private",
            "port":161,
            "timeout":2000,
            "retry":3
        },
        {
            "version":"SNMP V3",
            "readCommunity":"public",
            "writeCommunity":"private",
            "port":161,
            "timeout":2000,
            "retry":3,
            "userName":"dummy",
            "contextName":"",
            "engineId":"",
            "securityLevel":"AuthPriv",
            "authProtocol": "SHA",
            "authPassword":"dummy",
            "privProtocol": "AES256",
            "privPassword": "dummy"
        }
    ]
}
```

--------------------------------

### GetVersionInfo RPC Definition

Source: https://industrial-assets.io/developers/device-builder/conn-suite-drv-info

Defines the gRPC Remote Procedure Call for retrieving version information. It takes a GetVersionInfoRequest and returns a GetVersionInfoResponse.

```protobuf
rpc GetVersionInfo(GetVersionInfoRequest) GetVersionInfoResponse
Possible return values - OK
```

--------------------------------

### Asset API - Asset Management

Source: https://industrial-assets.io/developers/programing-interface/programing-interface_authorization-api

This section covers the API endpoints for managing Asset Models, including their creation, retrieval, updating, and deletion. It also includes endpoints for managing reachability state and responsible users.

```APIDOC
## GET /assets

### Description
Retrieve the Asset Models of all managed assets in a list.

### Method
GET

### Endpoint
/assets

### Parameters
#### Query Parameters
* **malformedOrUnknownQueryParams** (any) - Ignored - Malformed or unknown query parameters will be ignored.

### Response
#### Success Response (200)
- **assetModels** (array) - A list of Asset Model objects.

#### Response Example
{
  "assetModels": [
    {
      "id": "string",
      "name": "string",
      "type": "string"
    }
  ]
}

## POST /assets

### Description
Create or Update new Asset Models with system-generated ID.

### Method
POST

### Endpoint
/assets

### Parameters
#### Request Body
- **assetModel** (object) - Required - The Asset Model object to create or update.
  - **name** (string) - Required - The name of the asset.
  - **type** (string) - Required - The type of the asset.
  - **malformedOrUnknownRequestBodyParams** (any) - Ignored - Malformed or unknown request body parameters will be ignored.

### Request Example
{
  "assetModel": {
    "name": "Example Asset",
    "type": "Device"
  }
}

### Response
#### Success Response (200)
- **id** (string) - The system-generated ID of the created or updated Asset Model.

#### Response Example
{
  "id": "generated-asset-id"
}

## PATCH /assets/{id}

### Description
Patch an Asset Model.

### Method
PATCH

### Endpoint
/assets/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the Asset Model to patch.

#### Request Body
- **updates** (object) - Required - An object containing the fields to update.
  - **malformedOrUnknownRequestBodyParams** (any) - Ignored - Malformed or unknown request body parameters will be ignored.

### Request Example
{
  "updates": {
    "name": "Updated Asset Name"
  }
}

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
{
  "message": "Asset Model updated successfully."
}

## GET /assets/{id}

### Description
Retrieve an Asset Model.

### Method
GET

### Endpoint
/assets/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the Asset Model to retrieve.

### Response
#### Success Response (200)
- **assetModel** (object) - The retrieved Asset Model object.

#### Response Example
{
  "id": "asset-id",
  "name": "Example Asset",
  "type": "Device"
}

## DELETE /assets/{id}

### Description
Delete an Asset Model.

### Method
DELETE

### Endpoint
/assets/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the Asset Model to delete.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
{
  "message": "Asset Model deleted successfully."
}

## PATCH /assets/{id}/reachability-state

### Description
Update the reachability state of an Asset Model.

### Method
PATCH

### Endpoint
/assets/{id}/reachability-state

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the Asset Model.

#### Request Body
- **state** (string) - Required - The new reachability state (e.g., "Online", "Offline").
  - **malformedOrUnknownRequestBodyParams** (any) - Ignored - Malformed or unknown request body parameters will be ignored.

### Request Example
{
  "state": "Online"
}

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
{
  "message": "Reachability state updated successfully."
}

## PATCH /assets/{id}/responsible/{responsibleId}

### Description
Update the responsible user of an Asset Model.

### Method
PATCH

### Endpoint
/assets/{id}/responsible/{responsibleId}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the Asset Model.
- **responsibleId** (string) - Required - The ID of the responsible user.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
{
  "message": "Responsible user updated successfully."
}

## GET /assets/values/{property}

### Description
Return all values of one property for all assets.

### Method
GET

### Endpoint
/assets/values/{property}

### Parameters
#### Path Parameters
- **property** (string) - Required - The name of the property for which to retrieve values.

### Response
#### Success Response (200)
- **values** (array) - A list of values for the specified property across all assets.

#### Response Example
{
  "values": [
    "value1",
    "value2"
  ]
}

## GET /assets/group

### Description
Retrieve the values of a specific asset attribute and their respective counts.

### Method
GET

### Endpoint
/assets/group

### Parameters
#### Query Parameters
* **attribute** (string) - Required - The asset attribute to group by.

### Response
#### Success Response (200)
- **groupedValues** (object) - An object where keys are attribute values and values are their counts.

#### Response Example
{
  "groupedValues": {
    "typeA": 10,
    "typeB": 5
  }
}

```

--------------------------------

### Discovery Profile Configuration for V1.4.0 and later (JSON)

Source: https://industrial-assets.io/developers/device-builder/device-class-drivers/snmp-driver

This JSON configuration defines discovery profiles for SNMP versions V2c, V1, and V3, suitable for versions 1.4.0 and later. It includes parameters like read/write communities, port, timeout, retry, and security settings for SNMPv3.

```json
{
    "discovery_profiles":[
        {
            "version":"V2c",
            "readCommunity":"public",
            "writeCommunity":"private",
            "port":161,
            "timeout":3000,
            "retry":3
        },
        {
            "version":"V1",
            "readCommunity":"public",
            "writeCommunity":"private",
            "port":161,
            "timeout":3000,
            "retry":3
        },
        {
            "version":"V3",
            "port":161,
            "timeout":5000,
            "retry":3,
            "userName":"dummy",
            "contextName":"",
            "engineId":"",
            "securityLevel":"AuthPriv",
            "authProtocol": "MD5",
            "authPassword":"dummy",
            "privProtocol": "DES",
            "privPassword": "dummy"
        }
    ]
}
```

--------------------------------

### LinkML Definition for functional_parts

Source: https://industrial-assets.io/developers/asset-schema/functional_parts

This snippet shows the LinkML definition for the 'functional_parts' attribute. It specifies the name, description, title, examples, schema source, rank, alias, domain, range, and cardinality (multivalued).

```yaml
name: functional_parts
description: 'The functional objects that an asset is composed of, in case such a
  level of decomposition is desired. This is enables having assets composed of other
  assets and even devices composed of other devices and assets.

  An Asset must be addressable independently from other Assets (therefore they need
  to have an "id") and are therefore individually modeled. But not all parts of an
  Asset that are modeled need to be individually addressable, these are FunctionalObjects,
  but not Assets.

  Probably those functional_parts of an Asset providing some function for the Asset
  will be modeled here. Therefore an Asset can delegate the Interactions that it''s
  offering to its functional_parts.'
title: functional parts
examples:
- value: 'A server rack Asset can have following functional_parts that can be modeled
    like this: a frame (an Asset), servers (Devices), network switches/routers (Devices),
    power supply (a FunctionalObject),...'
- value: A library installed on a device
- value: The firmware of a device
from_schema: https://common-device-management.code.siemens.io/documentation/asset-modeling/base-schema/v0.12.0/iah-base.jsonld
rank: 1000
alias: functional_parts
domain_of:
- Asset
range: Asset
multivalued: true
inlined: true
inlined_as_list: true

```

--------------------------------

### Asset API

Source: https://industrial-assets.io/developers/programing-interface/programing-interface

API methods to create, read, update, and delete assets. This API covers all types of Assets, with Devices being a special subtype of Asset.

```APIDOC
## PATCH /asset-access-groups

### Description
Initiate asynchronous bulk patch of asset access groups.

### Method
PATCH

### Endpoint
/asset-access-groups

### Parameters
#### Request Body
- **body** (BulkPatchAssetAccessGroupsRequestBody) - Required - The request body for bulk patching asset access groups.

### Response
#### Success Response (200)
- **operationId** (string) - Description of the operation ID.
- **status** (string) - Status of the operation.

#### Response Example
```json
{
  "operationId": "some-operation-id",
  "status": "pending"
}
```

## PATCH /asset-management-states

### Description
Initiate asynchronous bulk patch of asset management states.

### Method
PATCH

### Endpoint
/asset-management-states

### Parameters
#### Request Body
- **body** (BulkPatchAssetManagementStatesRequestBody) - Required - The request body for bulk patching asset management states.

### Response
#### Success Response (200)
- **operationId** (string) - Description of the operation ID.
- **status** (string) - Status of the operation.

#### Response Example
```json
{
  "operationId": "some-operation-id",
  "status": "pending"
}
```

## PATCH /asset-responsibles

### Description
Initiate asynchronous bulk patch of asset responsibles.

### Method
PATCH

### Endpoint
/asset-responsibles

### Parameters
#### Request Body
- **body** (BulkPatchAssetResponsiblesRequestBody) - Required - The request body for bulk patching asset responsibles.

### Response
#### Success Response (200)
- **operationId** (string) - Description of the operation ID.
- **status** (string) - Status of the operation.

#### Response Example
```json
{
  "operationId": "some-operation-id",
  "status": "pending"
}
```

## DELETE /assets

### Description
Initiate asynchronous bulk deletion of assets.

### Method
DELETE

### Endpoint
/assets

### Parameters
#### Request Body
- **body** (BulkDeleteAssetsRequestBody) - Required - The request body for bulk deletion of assets.

### Response
#### Success Response (200)
- **operationId** (string) - Description of the operation ID.
- **status** (string) - Status of the operation.

#### Response Example
```json
{
  "operationId": "some-operation-id",
  "status": "pending"
}
```

## DELETE /assets/{id}

### Description
Initiate asynchronous deletion of a single asset.

### Method
DELETE

### Endpoint
/assets/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the asset to delete.

### Response
#### Success Response (200)
- **operationId** (string) - Description of the operation ID.
- **status** (string) - Status of the operation.

#### Response Example
```json
{
  "operationId": "some-operation-id",
  "status": "pending"
}
```

## GET /status/{id}

### Description
Get status of asynchronous write operation.

### Method
GET

### Endpoint
/status/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the asynchronous operation.

### Response
#### Success Response (200)
- **operationId** (string) - Description of the operation ID.
- **status** (string) - Status of the operation.

#### Response Example
```json
{
  "operationId": "some-operation-id",
  "status": "completed"
}
```

## POST /schemas/assets/validate

### Description
Validate one asset against a schema.

### Method
POST

### Endpoint
/schemas/assets/validate

### Parameters
#### Request Body
- **body** (ValidationRequestBody) - Required - The request body containing the asset data and schema to validate against.

### Response
#### Success Response (200)
- **isValid** (boolean) - Indicates if the asset is valid against the schema.
- **errors** (array) - A list of errors if the asset is not valid.

#### Response Example
```json
{
  "isValid": true,
  "errors": []
}
```
```