Creating an custom object definition and maintain some data
Employee Central offers a powerful feature to create custom generic objects also called Metadata Framework (MDF) Objects. This feature is available via “Admin Tools–>Configure Object Definitions” if the logged in user has the corresponding permissions. The following screenshots shows such a custom generic object called cust_LMS_Trial. Each record of this object has a autogenerated code (externalCode), an associations to a user in employee central (externalName) and four fields of type string (cust_Field1,…cust_Field4). All other fields are system generated fields:
This object definition can be created using a simple UI without any coding required. And after saving the object definition above also a UI to enter data is available via “Admin Tools–>Manage data”:
Hint: In some cases it might be required to refresh the OData API metadata after creating the object before a first successful API call. This refresh can be found in “Admin Tools–>OData API Metadata Refresh and Export” (after enabling this feature in permissions in group “Manage Integration Tools”).
Retrieve data from the created generic object using OData
After saving this object definition OData API for reading and writing the data are available instantly. Note that this is only the case if
- you select “API Visibility” accordingly while creating the custom generic object and
- if the user used to call the API has proper permissions set (“Permissions–>Manage Integration Tools–>Admin access to OData API” and “Metadata Framework–>Read/Write Permission on Metadata Framework”.
After creating an object definition as described above a rest client such as “Advanced Rest Client” in google chrome can be used to call APIs for the created object cust_LMS_Trial in employee central.
The easiest API call would be the retrieval of all records of the created object cust_LMS_Trial. A request for this would look like this in our salesdemo environment (note that the URL might differ in your environment, please refer to the OData API Programmers Guide for the right URL in your case):
Request-URL and Operation:
GET https://salesdemo4.successfactors.com/odata/v2/cust_LMS_Trial?$format=JSON
Request-Header:
Authorization: Basic dXNlckBjb21wYW55OnBhc3N3b3Jk
Remark: The cryptic authorization string above is the base64 encoding of the username, the instance or company you use to login and the corresponding password of the user in this company. To get the string above any base64 encoding tool can be used to encode the string user@company:password (for example notepad++ and the mime-tools available in this editor). The same request including parts of the repsonse in the advanced rest client:
The parameter $format is used to influence the output format and returns the data in JSON format (default value is ATOM/XML).
Create new data for the generic object using OData (POST)
In order to create new data via OData APIs, a POST operation is used. To create data for our object cust_LMS_Trial we have to switch our operation to POST and add a content type parameter into the OData request header. This content type defines the format of the payload, in our case JSON, and the used character set (here utf-8):
Request URL and operation:
POST https://salesdemo4.successfactors.com/odata/v2/cust_LMS_Trial?$format=JSON
Request Header:
Authorization: Basic dXNlckBjb21wYW55OnBhc3N3b3Jk
Content-Type: application/json;charset=utf-8
Payload:
{
“cust_Field1”: “15”,
“cust_Field4”: “40”,
“cust_Field3”: “30”,
“cust_Field2”: “20”,
“externalName”: “greinhard”
}
Response:
Status “201 Create” and created data in response
The same create request in google chrome:
Update existing data for the generic object using OData (PUT)
In order to update existing data the PUT operation has to be used and the corresponding record has to be identified in the URL. A OData request to update a record for cust_LMS_Trial with key 162 would look like this. Pleas not that only the operation and the url changes compared to creating data:
Request URL and operation:
PUT https://salesdemo4.successfactors.com/odata/v2/cust_LMS_Trial(162L)?$format=JSON
Request Header:
Authorization: Basic dXNlckBjb21wYW55OnBhc3N3b3Jk
Content-Type: application/json;charset=utf-8
Payload:
{
“cust_Field1”: “151”,
“cust_Field4”: “401”,
“cust_Field3”: “301”,
“cust_Field2”: “201”,
“externalName”: “greinhard”
}
Response:
Status “200 OK” and no data in response
Same request in google chrome:
Important remarks about updating links with OData
Using field “externalName” in the example above as a simple field is just a shortcut to allow easy creation of data. Usually associations have to be created using a dedicated navigation property. This shortcut version of creating data does not work anymore if the field is marked as required and the corresponding permission checks are enabled for those fields in the object definitions:
From that point of view it is a not a good idea to use the shortcut if you plan to switch later to permission enabled mode and make this field “externalName” required.
In such a case it is better to use a payload as follows:
{
“cust_Field1”: “11”,
“cust_Field4”: “41”,
“cust_Field3”: “31”,
“cust_Field2”: “21”,
“externalNameNav”: {
“__metadata”: {
“uri”: “https://salesdemo4.successfactors.com:443/odata/v2/User(‘greinhard’)”,
“type”: “SFOData.User”
}
}
}
