Generation of an interface structure file for EC Compound Employee API
Employee Central’s Compound Employee API supports now the generation of a consumer interface structure file by returning such an XSD as query response.
To generate an XSD query parameter resultOption with value xsd needs to be passed when calling the Compound Employee API via the query request. The result for such a query is an XSD that matches the query response structure for the requested select items and the given query mode in the query request. Special about the XSD is, it corresponds to the succession data model configuration of the given company that is used in the login operation.
XSD generation options
This new feature also provides the freedom to influence the structure dependent on the consumer needs. Query parameter xsdOptions can be utilized for this. It supports certain options, which have the following effects on the structure of the query response:
- If no xsdOptions query parameter value is passed, the generated XSD contains all fields included in Compound Employee APIs static set of fields and all additional fields that have the visibility edit, view, or both in the Succession Data Models. For personal global information the XSD contains an element for each configured country. For MDF object-based segments the XSD contains all relevant fields defined in the corresponding object model.
- Passing value returnAllFields will return the superset of all fields supported by Compound Employee API. The generated XSD contains all fields included in its static set of fields and all additional and configurable fields of any of the Succession Data Models, independent of their visibility. For personal global information the generated XSD contains all supported countries and not only the configured ones. This parameter doesn’t have an impact on MDF object based segments.
- Passing value returnAllSegments will return all segments supported by Compound Employee API including all MDF objects registered for extensibility. Segments passed as select items do not have an impact on the generated XSD.
- Passing value useWeakTypes leads to a generated XSD in which data type String is used for all numeric typed fields (Long or Double) in the XSD .
Special handling for numeric typed fields using xsdOptions parameter value useWeakTypes
Numeric typed fields can be handled considering the modeling of the field in the Succession Data Models, which depends on the parameter value that is passed via the query request. If a numeric field is defined with a reference to a picklist, foundation object, or generic object, the data type used in the generated XSD needs to be String instead of Long or Double. This behavior is required because the Compound Employee API exposes the external code for these referenced object. Keeping the original numeric typing may cause validation issue on consumer side as external codes also may contain characters.
The tables below give an overview about the XSD results for fields with different data types, data model configuration, and xsdOptions used. In these examples, ExtRef means “external reference”. It indicates that the field has a reference to a picklist, foundation object, or generic object modeled in the Succession Data Model.
Table above shows the result of XSD generation behavior for country independent select items such as personal information, email, phone or select items that have a global model such as employment information, job information, or compensation information.
Table above shows the XSD generation behavior for country dependent select items such as personal global information or address information.
XSD query response handling
The query response for the XSD generation contains more information than needed for the consumer interface structure. From the query response the information needs to be taken as shown in the example below marked in the pink color to define the schema file.
<?xml version=”1.0″?>
<S:Envelope xmlns:S=”http://www.w3.org/2003/05/soap-envelope”>
<S:Body>
<queryResponse xmlns=”urn:sfobject.sfapi.successfactors.com”
xmlns:ns2=”urn:fault.sfapi.successfactors.com”>
<result>
<sfobject>
<id>xsd</id>
<type>CompoundEmployee</type>
<xsd><![CDATA[
<?xml version=”1.0″ encoding=”UTF-8″?>
<xs:schema xmlns=”urn:sfobject.sfapi.successfactors.com”
xmlns:xs=”http://www.w3.org/2001/XMLSchema”
targetNamespace=”urn:sfobject.sfapi.successfactors.com”
elementFormDefault=”qualified”>
…
</xs:schema>
]]>
</xsd>
</sfobject>
<numResults>1</numResults>
<hasMore>false</hasMore>
<querySessionId>0ee36b8a-0e21-4e47-942d-f8ef4e6431a1</querySessionId>
</result>
</queryResponse>
</S:Body>
</S:Envelope>
