Please note the current system only provides the following methods to upload KPI Actuals:
  • Upload via the system UI, using Excel spreadsheets.which is not useful for automated uploads
  • Upload via the API detailed below.

Note the system doesn't provide an option for the upload to be done via an FTP at this point. So the only method for automated uploads would be using the API. We have been able to successfully use Microsoft Flow (https://flow.microsoft.com/en-us/) for automating the uploads. We are planning on adding better integration with Microsoft Flow in the future, but at this point, it is a bit of a manual process for setting it up. for more information on this option please an email to support@pipware.net

Using Swagger to get all the available APIs, note the PUT request for /API/Kpi/values is the best option to use. The valuesV2 version has the same import model but handles the date field slightly differently. These API calls are used by the web application, so we don't have much documentation on them. Below is the required field for the upload:
kpiCode: This is a string field, it expects to contain a code of a KPI on PIPware. This field is required.
valueDate: This is a date field, it is the date that the value applies to. The date should be in the following format: YYYY-MM-dd, i.e. 2019-09-19 for today's date. This field is required.
actualValue: This is a number field, it is the actual value to upload for the KPI. This field can be null. Uploading a null value is only really useful if you need to remove the value for a particular date.

The API expects to be called with a JSON array containing the KPI Actual Models as defined above. Below is an example of uploading 2 values for KPI_A and KPI_B.
[ {kpiCode: "KPI_A", valueDate: "2019-09-01", actualValue: 100.23 }, {kpiCode: "KPI_B", valueDate: "2019-08-01", actualValue: 0.112 } ]

The API key is required to call the API, otherwise, you will receive a 401 unauthorized error. The API key can be generated by logging into the system with a valid user profile, going to User > Profile and clicking "Refresh" in the API key field. Please note that the API key will only be displayed once, it will then need to be securely stored. If you lose the API key, you will need to click Refresh to generate a new key. In this case, the previous key will become invalid.

There are various ways to send the API key with the API Request:
  • Add a header with the X-PIPWARE-ApiKey header key.
  • Add an Authorization header with the following value: PIPWARE {ApiKey}, where {ApiKey} should be replaced with your API key.
  • Add a query string parameter called apiKey to the request URL. This is the least secure option and is not recommended since the API will be sent in clear text to the server.
The following fields Id, KpiId, and deleted can be excluded.

The fields are used for the following purposes:
  • Id: This is the primary key of the KPI Value row in the database. It is used internally by the system and should only be used if the PK value is known. If the id is not provided, the system will find the value row using the KpiId (or kpiCode) and the valueDate. You can either leave the property out of the API call or provide NULL for the value.
  • KpiId: This is a foreign key to the KPI table. It is used internally by the system and should only be used if the KPI Id value is known. If the kpiId is not provided, the system will find the KPI using the kpiCode. You can either leave the property out of the API call or provide NULL for the value.
  • deleted: This column is used for soft deletes in the KPI Values table. We generally don't delete any data in the system, it is flagged as deleted and then excluded from all future select calls. If you leave this property out, the system will use the default for the property which is false. Otherwise, if you prefer to include it in the API call, you can specify false as it's value.