> For the complete documentation index, see [llms.txt](https://interfacing.gitbook.io/interfacing-help-files/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://interfacing.gitbook.io/interfacing-help-files/solutions-developers/integrations/amos-kpi-integration.md).

# AMOS KPI Integration

Import KPI values from external systems into EPC & IMS automatically through the AMOS KPI integration.

## Overview

The **AMOS KPI integration** allows KPI values generated by an external system to be transferred to EPC and IMS.

Files are typically delivered through **SFTP** and are processed automatically by EPC Sync. Each file is tracked throughout the process, making it possible for support teams to monitor whether the data was successfully imported or requires attention.

{% hint style="info" %}
**Good to know**\
The business behavior of the AMOS KPI integration has not changed between versions 15.4.x and 16.0.x.
{% endhint %}

***

## How it works

The process is mostly automatic. Once the KPI file is provided in the expected format, EPC Sync takes care of processing and forwarding the data.

{% stepper %}
{% step %}

#### **KPI data is generated**

An external system generates a CSV file containing the KPI values.
{% endstep %}

{% step %}

#### **The file is delivered**

The file is placed in the agreed SFTP location.
{% endstep %}

{% step %}

#### **EPC Sync receives the file**

The file and its rows are added to the processing queue.
{% endstep %}

{% step %}

#### **The data is transferred**

EPC Sync sends the KPI values to EPC/BPC.
{% endstep %}

{% step %}

#### **The result is tracked**

Support teams can check the processing status if a problem occurs.
{% endstep %}
{% endstepper %}

***

## File format

For the integration to process a file correctly, both the **filename** and **CSV structure** must follow the expected format.

#### Filename

Each file must follow this pattern:

```
kpi_<company>_<kpi-uid>_<yyyyMMddHHmmss>.csv
```

The filename identifies:

| Part             | Description                                   |
| ---------------- | --------------------------------------------- |
| `company`        | The company associated with the KPI           |
| `kpi-uid`        | The unique identifier of the KPI in EPC & IMS |
| `yyyyMMddHHmmss` | The measurement date and time                 |

#### CSV structure

The file must contain the following header:

```
id,value
```

The rows then contain the reference ID and the KPI value:

```
id,value
row-001,98.2
row-002,97.4
```

{% hint style="danger" %}
**Important**\
Keep the `id,value` header exactly as shown. Changing the header can cause the file to fail processing.
{% endhint %}

***

## Understanding the KPI data

Each file represents **one KPI and one measurement timestamp**.

| Business element           | Where it comes from |
| -------------------------- | ------------------- |
| **KPI**                    | Filename            |
| **Measurement date**       | Filename            |
| **KPI values**             | CSV rows            |
| **Traceability reference** | `id` column         |

This means that the filename and the contents of the file work together to identify and transfer the KPI data correctly.

***

## Processing statuses

Once a file is received, it moves through different processing statuses.

| Status                  | What it means                                                               |
| ----------------------- | --------------------------------------------------------------------------- |
| **NEW**                 | The file has been received and is waiting to be processed.                  |
| **PROCESSING**          | The file is currently being processed and its values are being transmitted. |
| **DONE**                | The file was processed successfully.                                        |
| **FAILED**              | The file or one of its rows could not be processed.                         |
| **RETRY**               | The system will automatically try to process the file again.                |
| **PERMANENTLY\_FAILED** | The maximum number of automatic retries has been reached.                   |

### What should I do if a file fails?

If a file has a **FAILED** or **PERMANENTLY\_FAILED** status, the support team should review the file and processing details to determine the cause.

Common causes include:

* An incorrect filename
* An incorrect CSV header
* Invalid or malformed data in a row
* A value that is not numeric
* An issue with the receiving system

***

## Common questions

<details>

<summary><strong>Why was my file ignored?</strong></summary>

The filename may already exist in the processing history.

Reusing the same filename does **not** cause the file to be processed again. Make sure each new file has a unique filename.

</details>

<details>

<summary><strong>Why did the whole file fail?</strong></summary>

The filename or CSV header may not match the expected format.

Check that:

* The filename follows the required naming convention
* The CSV header is exactly `id,value`

</details>

<details>

<summary><strong>Why are only some rows failing?</strong></summary>

Some rows may contain invalid or malformed data.

For example, a KPI value that is not numeric may prevent that row from being processed correctly.

</details>

<details>

<summary><strong>Why are my rows still pending?</strong></summary>

The file may still be waiting for the scheduled processing job, or the system receiving the data may temporarily be unavailable.

</details>

***

## Best practices

To help ensure KPI files are processed successfully:

<table data-card-size="large" data-view="cards"><thead><tr><th></th></tr></thead><tbody><tr><td><h4>Use unique filenames</h4><p></p><p>Make sure every new KPI file has a new filename. Reusing a filename can cause the file to be treated as a duplicate.</p></td></tr><tr><td><h4>Check the KPI identifier</h4><p></p><p>Make sure the KPI UID in the filename corresponds to the correct KPI in EPC.</p></td></tr><tr><td><h4>Keep the CSV format unchanged</h4><p></p><p>Always use the exact <code>id,value</code> header and ensure the values are correctly formatted.</p></td></tr><tr><td><h4>Monitor failed files</h4><p></p><p>Support teams should regularly monitor files with <strong>FAILED</strong> or <strong>PERMANENTLY_FAILED</strong> statuses.</p></td></tr></tbody></table>

***


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://interfacing.gitbook.io/interfacing-help-files/solutions-developers/integrations/amos-kpi-integration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.