How To Execute A Service Operation

In order to execute an SData service operation, we need to know what information to send to it. The best way to gather this information, is through SData itself, by inspecting the $template for the service operation, e.g. /sdata/slx/dynamic/-/activities/$service/Complete/$template, which would return the following information:

Atom

<?xml version="1.0" encoding="utf-8"?>
<entry>
  <author>
    <name>SalesLogix</name>
  </author>
  <http:httpStatus>200</http:httpStatus>
  <sdata:payload>
    <slx:ActivityComplete>
      <slx:request>
        <slx:ActivityId xsi:nil="true" />
        <slx:userId xsi:nil="true" />
        <slx:result xsi:nil="true" />
        <slx:resultCode xsi:nil="true" />
        <slx:completeDate>0001-01-01T00:00:00+00:00</slx:completeDate>
      </slx:request>
      <slx:response xsi:nil="true" />
    </slx:ActivityComplete>
  </sdata:payload>
</entry>

JSON

{
  "$httpStatus": "OK",
  "$descriptor": "",
  "request": {
    "ActivityId": null,
    "userId": null,
    "result": null,
    "resultCode": null,
    "completeDate": "\/Date(-62135596800000-0800)\/"
  },
  "response": null
}

The primary information that is needed from the above is the payload container name, i.e. ActivityComplete, from the Atom payload, and is required when executing a service operation via Atom, and the parameter names and default values.

In order to execute the service operation, we must first create an instance of the SDataServiceOperationRequest class, which is constructed much like any other request:

var request = new Sage.SData.Client.SDataServiceOperationRequest(this.service)
	.setResourceKind('activities')
	.setOperationName('Complete');

You pass the SDataService instance to the constructor, set the resource kind, and then set the name of the operation we want to execute with the setOperationName method. Once the request object is created, we need to build up the payload to send to the operation:

var entry = {
  "$name": "ActivityComplete",
  "request": {
    "ActivityId": "VDEMOA0000BA",
    "userId": "ADMIN",
    "result": "Complete",
    "completeDate": "\/Date(1300315517984)\/"
  }
};

Notice that the structure of the payload closely matches that of the template received via JSON. The additional $name property is required by the client libraries in order to correctly format the payload when using Atom as your serialization format. If the Atom serialization format is never going to be used, this property can safely be omitted, but the general recommendation is to use it. The request property contains all of the paramters that are required by the service operation.

Now, to execute the operation, we use the execute method of the SDataServiceOperationRequest class, passing it the entry and options for the request, e.g.:

request.execute(entry, {	
	success: function(result) { ... },
	failure: function() { ... }
});

The success function is passed the result of the service operation call and the structure of this object again closely matches that of the template received via JSON, but instead of a request property being filled out, it will have a response property, which contains the data returned by the service operation, e.g.:

{
  "$httpStatus": "OK",
  "$descriptor": "",
  "request": null,
  "response": {
    "Result": {
      "$key": "HDEMOA0000LL",
      "$url": "http://localhost/sdata/slx/dynamic/-/history('HDEMOA0000LL')",
      "$lookup": "http://localhost/sdata/slx/dynamic/-/history",      
      "Description": "Review Proposal"      
    }
  }
}

The structure of the response property value depends on the service call.