This is the first in a series of blogs leading up to Tech Ed by the SAP Jam team to help you get more familiar with how to extend SAP Jam. In this blog, I will be giving an introduction to using SAP Jam’s OData API which can be used to automate workflows or integrate them into your own business applications.
Preparing your environment
To start with using the API, I would suggest having a free SAP Jam Developer Edition on SAP HANA® Cloud Platform. If you don’t already have one, I would suggest reading the following blog. This will allow you to have full control over a SAP Jam company without having to worry about affecting your company’s SAP Jam instance. Additionally, using the API from SAP HANA Cloud Platform to connect to this copy of SAP Jam is very simple. First, you need to setup trust between SAP HANA Cloud Platform and SAP Jam. These steps are well documented here. Go through the “Setup your Trust configuration on SAP HANA Cloud Platform” and “Setup your Destination configuration on SAP HANA Cloud Platform” sections. The next section in the documentation allows you to run a servlet that runs many examples, however, from my own experience, this may be a little overwhelming as a first introduction to the SAP Jam API. My suggestion is to use Eclipse® and set it up as described here.
Sample Code
I’ve uploaded some very basic samples in our GITHUB® here. They are all contained in the ODataSamples folder which is an Eclipse project that you can import into your environment. In this project there are a few folders to help group the different calls that you can make into logical areas such as Groups. Each of these folders is then split into each of the major endpoints that exist in this area, Groups contains both a Groups and a GroupTemplates folder. The next level of folders organizes the content into one of four main functions (Create, Get, Update, Delete). Currently I’ve only created samples for Create and Get, which will show the majority of what you need to do in order to work with the API.
There are a couple of important things to note with these samples:
1. In the web.xml, the following tag is to allow the application code to utilize the same named destination that was configured in your SAP HANA Cloud Platform (if you follow the documentation on setting this up, you shouldn’t have to change this file as it will match the “sap_jam_odata” name already provided) in order to easily communicate with your SAP Jam system:
<resource-ref>
<res-ref-name>sap_jam_odata</res-ref-name>
<res-type>com.sap.core.connectivity.api.http.HttpDestination</res-type>
</resource-ref>
2. In the web.xml, the following is needed to force authentication which will be handled by SAP HANA Cloud Platform. This allows us not to have to add any extra code to do the authentication within our application.
<login-config>
<auth-method>FORM</auth-method>
</login-config>
<security-constraint>
<web-resource-collection>
<web-resource-name>Protected Area</web-resource-name>
<url-pattern>/</url-pattern>
</web-resource-collection>
<auth-constraint>
<role-name>Everyone</role-name>
</auth-constraint>
</security-constraint>
<security-role>
<description>All SAP HANA Cloud Platform users</description>
<role-name>Everyone</role-name>
</security-role>
Now let’s look at one of the Get samples, getUserGroups.jsp. The first thing you may notice when looking for this file is that there is another with the same name, but is an html page. The html page is provided as a way to launch this jsp page with a simple UI to enter the needed parameters to keep these samples dynamic. In this case, there are no specific parameters actually required, so we just have a run button.
Looking into the code, the first few lines actually retrieve the destination information that is setup on SAP HANA Cloud Platform and our web.xml file:
Context ctx = new InitialContext();
HttpDestination destination = (HttpDestination)ctx.lookup("java:comp/env/sap_jam_odata");
HttpClient client = destination.createHttpClient();
The next step, we need to create the http call type we will be making while passing in the path of the endpoint we are calling. In this case, we are doing a GET, so we will use the HttpGet class.
HttpGet jamRequest = new HttpGet("/api/v1/OData/Groups");
We are just calling the base end point which will return all groups that the currently logged in user belongs to. In other cases, we may include the id of a specific object that we want to return information on.
The next step is to set any additional headers that we want. In this case, I want the response to be in JSON format, so I set this as the Content-Type:
jamRequest.addHeader("Content-Type", "application/json");
The following line actually executes this request:
HttpEntity responseEntity = client.execute(jamRequest).getEntity();
From which we can get and output the result (You will likely parse the result first to provide a nicer display of exactly what the user should see, this sample just keeps it simple and displays the JSON output of everything so you can see what can be returned):
String responseString = EntityUtils.toString(responseEntity);
out.println(responseString);
As you can see here, it has only taken 8 lines of code to do everything we need to do for a basic Get call. The same set of calls could be used for a Delete call, the only difference would be using the HttpDelete class instead.
The update and create calls have a couple additions needed, and would use the HttpPatch and HttpPost classes respectively. An example of a create function can be found by looking at createGroupTask.jsp. The first difference you will notice is that I pull a couple parameter values back from the request (generated by the html page):
String taskName = request.getParameter("taskName");
String groupID = request.getParameter("groupID");
A second change is that I’ve set another header, which is saying that I am going to be passing the information in JSON format:
jamRequest.addHeader("Accept", "application/json");
I then create a string that contains the JSON request (this could use a JSON library to create this object, I have written it out freehand to make it clearer what is being passed in). I’ve broken it into multiple lines for readability. In this case, as this sample is just creating a task within a group, all I actually need to pass here is the Title property, which is the name of the task:
String jsonToSend = "";
jsonToSend += "{";
jsonToSend += "\"Title\" : \"" + taskName + "\"";
jsonToSend += "}";
The last different step is that we need to include this string as part of the request that we make:
StringEntity entity = new StringEntity(jsonToSend);
jamRequest.setEntity(entity);
The rest of the code is the same to execute the request and get the string response back to be displayed.
For a full listing of the different end points and the properties exposed in the API, you can find the documentation here.
I hope that this blog has helped you understand how quickly you can begin coding with the SAP Jam API to help streamline your use of SAP Jam!
