Creating Service Callbacks

When you use dw.svc.Service.call(Object...) to invoke a web service, the service framework checks whether the call exceeds either the rate limiter or circuit breaker thresholds and, if not, makes the call.

When making a call, the framework invokes the callbacks you implemented in your service instance. Each callback corresponds to one of the following callback methods defined by the dw.svc.ServiceCallback class.

These methods are called in the following order:

  1. initServiceClient(Service) ― Creates the underlying client used to make the call. Required only for SOAP Services. Other client types are created automatically.
  2. createRequest(Service, Object...) ― Given arguments to the Service.call(Object...), configure the actual service request. This may include setting request headers, defining the message body, and so on.
  3. execute(Service, Object) ― Perform the actual request. At this point the client has been configured with the relevant credentials, so the call should be made. This is required for SOAP services.
  4. parseResponse(Service, Object) ― Convert the result of the call into an object to be returned from the Service.call(Object...) method.

Some callback methods may be optional, depending on the type of service.

Every callback method requires a Service object (for a generic service) or one of its subclasses (FTPService, HTTPFormService, HTTPService, or SOAPService).

HTTP and HTTP Form Callbacks

For an HTTP service, pass in HTTPService objects. For an HTTP form, pass in HTTPFormService objects.

Recommended callbacks for HTTP services:
  • createRequest: Required to create a requestData object. If you need additional processing, you can pass the requestData object to the execute callback. Otherwise, the requestData object is used to call the web service when the Service object is invoked.
  • parseResponse: Gives the HTTPClient as its extra argument. Use to parse the response contained in the Service object.

FTP and SFTP Callbacks

For an FTP or SFTP service, pass in FTPService objects.
Recommended callbacks
  • createRequest: Required to create a requestData object. If you need additional processing, you can pass the requestData object to the execute callback. Otherwise, the requestData object is used to call the web service when the Service object is called.
  • parseResponse: Gives the FTPClient as its extra argument. Use to parse the response contained in the Service object.
  • execute: If the setOperation method isn't called in the web service script, operations defined in the execute callback are executed when the web service is invoked. You can use the execute method to perform multiple operations in sequence.

SOAP Callbacks

For any SOAP service, pass in a SOAPService object.

Recommended callbacks
  • initServiceClient: Use get a dw.rpc.stub and webreferences object (rpc-style) or a dw.ws.port (doc-style) and webreferences2 object.
  • createRequest: Required to create a requestData object. This object must be passed to the execute method.
  • execute: Specifies additional processing for the web service request.
    Note: If you get your stub or port in this step, instead of in the initServiceClient callback, any timeouts you set will override those set in the service configuration. This isn't recommended.
  • parseResponse: Use this method to parse the response in the Service object.

Generic Callbacks

Does not wrap any class. Used to define custom calls.

Note: You must pass a plain Service object, rather than a subclass, for this callback method.

Mock Callbacks

You can mock web service responses in two ways.

First, you can the web service to use mock responses:

  1. In Business Manager, select Administration > Operations > Services. For the Service Mode, select Mocked.
  2. Provide a mockCall callback handler. For example, in your web service script:
mockCall: function(svc:HTTPService, client:HTTPClient){
    return {
        statusCode: 200,
        statusMessage: "Success",
        text: "MOCK RESPONSE (" + svc.url + ")"
        };
    }
Second, you can force a mock call, regardless of configuration. Add a mock method to your service definition and then call it explicitly in your web service script. Remove this method from your script when testing live web service calls.
result = service.setMock().call();