Perfion Web Service Interface

In order to use remotes with web service one has to use Perfion remote web service interface. This means that users must create their own web service, which will use Perfion web service interface and can handle various types of remote data requests sent from Perfion.

Remotes use very specific data structure and it is used in various places in Perfion. Perfion web service interface was created to support all those usage scenarios. For example, in some cases all available remote data should be returned to Perfion, in other cases only remote data headers are important, yet in another case only selected items must be returned.

The interface have three web methods: GetData, GetQueries and GetQueryInfo. Only GetData web method is mandatory.

GetData Web Method

This web method is used to get data of selected query. It must return a string with XML document, which contains data headers information and/or data.

Web method signature

string GetData( string queryParameters );

Where queryParameters is XML document with query parameters. Query parameters document structure:

Query parameters structure

</RemoteQuery>

How to use different type of parameters is shown in the table below.

Parameter name	Required	Options	Description
Remote Query	Yes	-	Root element, which must have four attributes: name, group, type and localizable
name	Yes	-	RemoteQuery attribute specifying query name.
group	Yes	“All”, “None”, <user defined>	RemoteQuery attribute specifying query group name. It specifies which part of query should be executed. Groups “All” and “None” must be supported and user defined groups are optional.
type	Yes	Single, Cluster	RemoteQuery attribute specifying remote data type. Single. The query returns only one row for each key value. Cluster. The query can return multiple rows for each key value, where each will be distinguished by variant.
localizable	No	True, False	RemoteQuery attribute specifying if returned data must be in a special format used with localizable features. Default value is “False” if parameter is not defined.
Field	No	-	It is the data field (data header or data column name) requested by the query. The name of the field is specified in “name” attribute. Query must return only the data fields specified by field elements. The field elements are optional. If they are not defined, then the query must return all available data fields. Field names are case insensitive. There are several reserved field names, which have special meaning in Perfion and can only be used to return specific data: Key or KeyValue. This field name is reserved for data fields with unique key values of the items to be returned by the query. This field is used to map Perfion data and data available in remote data source. “Key” and “KeyValue” data field names are aliases and both cannot exist in the same data response from the web service. For example, if “Key” is used, then “KeyValue” cannot be used, and vice versa. Variant. This field name is reserved to be used with Cluster type queries and the data field with this name will be used to return variant values for items to be returned by the query. If variant data is used, then data specified in “Key” data field and “Variant” data field must be unique, e.g. for each key value, there should be only unique variant values.
Parameter	No	-	It specifies parameter values used in query. The name of the parameter is specified in “id” attribute and are case insensitive. Parameters are optional. The values must be of data type specified by the GetQueryInfo web method.
Key	Yes	-	It specifies a unique value of the item to be returned by the query. There can be multiple keys specified, but they must be all unique.
Variant	Yes	-	It specifies a list of variant values to be returned by the query for each key value. Variants will be used only with Cluster type data. In any other cases variants are optional and if used, it can be used as a simple parameter with multiple values.
Languages	Yes	<Language codes supported by Perfion>	It is a special parameter and specifies the list of language codes used by Perfion based on context where remote data will be used. The languages may differ based on where from data was requested. For example, if Perfion will show data only using English language (e.g. in the grid), then it will specify “EN” language code. If it will show data using multiple languages (e.g. in Item Editor), then multiple language codes will be sent, e.g. “EN,DE,DAN”. This parameter is optional. Perfion will always send it, but it may be ignored in most cases except if query is specified as localizable. If query is localizable, then data must be prepared in a special format, suitable to be used with localizable remote features.

GetData web method must return XML document in a special format. The example is shown in the table below. The XML document structure is 100% identical to the XML representation of a standard .NET DataSet. Example below shows data returned for query specified in example, e.g. this is response for Cluster type query with Group parameter set to “All”.

Return data format

<xs:schema id="RemoteQueryData" xmlns=""

xmlns:xs="http://www.w3.org/2001/XMLSchema " xmlns:msdata="urn:schemas- microsoft-com:xml-msdata">

<xs:element name="RemoteQueryData"

msdata:IsDataSet="true" msdata:UseCurrentLocale="true">

<xs:complexType>

<xs:choice minOccurs="0" maxOccurs="unbounded">

<xs:element name="Data">

<xs:complexType>

<xs:sequence>

<xs:element name="Key" type="xs:string" minOccurs="0"/>

<xs:element name="Variant" type="xs:string" minOccurs="0" />

<xs:element name="Price" type="xs:double" minOccurs="0" />

<xs:element name="Currency" type="xs:string" minOccurs="0" />

</xs:sequence>

</xs:complexType>

</xs:element>

</xs:choice>

</xs:complexType>

</xs:element>

</xs:schema>

<Data>

</Data>

<Data>

</Data>

<Data>

</Data>

<Data>

</Data>

…

</RemoteQueryData>

GetQueries Web Method

This web method is used to get the list of all remote queries supported by web service. It must return a string with XML document, which contains names and types of all different queries. This web method is optional.

Web method signature

string GetQueries();

Return data format

…

</RemoteQueries>

Where:

Query name. The name of query.
Query type. The type of query. There are two types supported by Perfion:
- Single. The query returns only one row for each key value.
- Cluster. The query can return multiple rows for each key value, where each will be distinguished by variant.

GetQueryInfo Web Method

This web method is used to get information of selected query. It must return a string with XML document, which contains parameters and groups supported by query. This web method is optional.

Web method signature

string GetQueryInfo( string queryName );

Return data format

</RemoteQueryInfo>

Where:

Parameter is an input parameter used by the specified query. Each parameter has two attributes:
- “name”. The name of the parameter.
- “type”. The data type or the parameter. The supported data types:
  - Number
  - String
  - Date
  - Text

NOTE: Binaries are not supported.

Group is a group supported by the specified query. Groups can be used to partition a query into several groups that return specific part of the query result, e.g. in order to limit the query to only return items from the specified category (e.g. Cars, Movies, etc.). The groups with names “All” and “None” are reserved for specific behavior and are mandatory for each query:
- None. If query is requested using this group, then the query must return only metadata (schema part of query result), e.g. data headers, but no data rows. Perfion will use this group to determine which data columns are available to select from.
- All. If query is requested using this group, then the query must return all data available in remote source. Note: “all data”, means all available data in remote source, after applying all limitations defined by using various parameters.