New article
Recently updated
Formatting requirements for Performance Indicator data
Who is this article for?Users who need help formatting data for importing updated PI values.
PI_Update data, PI_Activate, PI_Targets Edit, permissions are required.
To update Performance Indicator (PI) values via the web service integration, your data must meet specific formatting requirements. This guide will outline the structure and syntax you need to bear in mind when importing data.
In this article:
1. POST structure
For an import to succeed, please make sure your data follows our XML schema, and that the web service integration POSTs the data to the following endpoint: https://www.pentanarpm.uk/CovalentWebServices/SendData.
Your POST should also include the following parameters:
|
Key |
Contents |
Notes |
|---|---|---|
|
<user> |
Login details of the Integration User. |
Must be an active User with appropriate Permissions. |
|
<pass> |
Password of the Integration User. |
Must be a valid password for the active User. |
|
<id>/<cust> |
Customer ID/Customer Name |
Customer ID is the unique identifier assigned to your site. You can reach out to the Support Team if you are not sure what your ID is. Customer names the first portion of your site URL, before .pentanarpm.uk. |
|
<data> |
XML Data |
|
|
<service> |
Text |
PI Values integrations: ‘PIVAL’. |
2. PI XML syntax
Data contained within the 'PI Values' update must follow the following format:
|
Key |
Attributes |
Contents/Data Type |
Notes |
|---|---|---|---|
|
<pis> |
|
<pi> |
|
|
<pi> |
code=”PI Code” |
<values>+ |
This targets the specific PI to be updated. |
|
<values> |
|
<period> <year> <frequency> <target> <numerator> <numeratorTrgt> <denominator> denominatorTrgt> |
Each set of these values is nested under a <pi code = “PI Code”> identifier. |
|
<value> |
|
(text) |
PI data value. |
|
<period> |
|
(text) |
PI data period. |
|
<year> |
|
(number) |
Year of this PI data. |
|
<frequency> |
|
“D”, “W”, “M”, “Q” or “Y” |
PI data collection frequency. |
|
<target> |
|
(number) |
PI value target. |
|
<numerator> |
|
(number) |
Numerator value. |
|
<numeratorTrgt> |
|
(number) |
Numerator target value. |
|
<denominator> |
|
(number) |
Denominator value. |
|
<denominatorTrgt> |
|
(number) | Denominator target value. |
The <period> element format is dependent on the value of the <frequency> element:
|
<frequency> value |
<period> format |
|---|---|
|
D |
Date of the day in the 'ddmm' format (e.g. 1110 for 11th October) . |
|
W |
Start date of the week in the 'ddmm' format. |
|
M |
Three letter representation of the month. Accepted values: JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG, SEP, OCT, NOV, DEC. |
|
Q |
Numerical value of the quarter (1-4). |
|
Y |
Year for this value (e.g. 2008). |
For more information and guidance on the format of PI Value imports, please see the help documentation or contact our Support Team.
3. XML sample
Once constructed, an import may look something like this:
Single PI data entry
<?xml version="1.0" encoding="ISO-8859-1"?>
<pis xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://www.pentanarpm.uk/schema/pivalues-1.0.xsd">
<pi code="XML 1">
<values>
<value>100</value>
<period>MAR</period>
<year>2023</year>
<frequency>M</frequency>
</values>
</pi>
</pis>
Multiple PI data entries
<?xml version="1.0" encoding="ISO-8859-1"?>
<pis xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://www.pentanarpm.uk/schema/pivalues-1.0.xsd">
<pi code="XML 1">
<values>
<value>100</value>
<period>MAR</period>
<year>2023</year>
<frequency>M</frequency>
</values>
</pi>
<pi code="XML 2">
<values>
<value>100</value>
<period>MAR</period>
<year>2023</year>
<frequency>M</frequency>
</values>
</pi>
</pis>
Multiple PI data entries using Targets, Numerators and Denominator Values
<?xml version="1.0" encoding="ISO-8859-1"?>
<pis xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://www.pentanarpm.uk/schema/pivalues-1.0.xsd">
<pi code="XML 1">
<values>
<value>null</value>
<period>MAR</period>
<year>2023</year>
<frequency>M</frequency>
<target>100</target>
<numerator>20</numerator>
<numeratorTrgt>30</numeratorTrgt>
<denominator>20</denominator>
<denominatorTrgt>20</denominatorTrgt>
</values>
</pi>
<pi code="XML 2">
<values>
<value>null</value>
<period>MAR</period>
<year>2023</year>
<frequency>M</frequency>
<target>100</target>
<numerator>20</numerator>
<numeratorTrgt>30</numeratorTrgt>
<denominator>20</denominator>
<denominatorTrgt>20</denominatorTrgt>
</values>
</pi>
</pis>
Other PI data entry example
<?xml version="1.0" encoding="ISO-8859-1"?>
<pis xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://www.pentanarpm.uk/schema/pivalues-1.0.xsd">
<pi code="XML 1">
<values>
<value>89.9</value>
<period>JUL</period>
<year>2023</year>
<frequency>M</frequency>
<target>100</target>
</values>
<values>
<value>81.9</value>
<period>AUG</period>
<year>2006</year>
<frequency>M</frequency>
<target>97</target>
</values>
</pi>
<pi code="XML 2">
<values>
<value>null</value>
<period>2005</period>
<year>2005</year>
<frequency>Y</frequency>
<target>100</target>
<numerator>20</numerator>
<numeratorTrgt>30</numeratorTrgt>
<denominator>20</denominator>
<denominatorTrgt>20</denominatorTrgt>
</values>
</pi>
<pi code="XML 3">
<values>
<value>na</value>
<period>0106</period>
<year>2005</year>
<frequency>W</frequency>
<target>100</target>
</values>
</pi>
</pis>