X

It's All About the Platform.

Calling Custom Object Functions via RESTful Services

Richard Bingham
Senior Development Manager

Overview

Following on from our introduction article on using the Custom Object RESTful API, let's next look at how to use it to call scripts.

In essence this is done using a POST method on a single custom object record, and including the following values in the request JSON payload:

  • name:[name of your ObjectFunction]
  • parameters:[an array of input parameters]

The response will be either a String value if your object function has a return, or simply a HTTP 204 'No Content' message. If the call fails you will get an error message. Let's use a simple example to illustrate usage.

First we define our Object Function making sure to publish any sandbox it is created in as this is required for use. Obviously triggers and rules applied when the record data is changed and these will fire automatically.  You cannot directly call Global Functions from the RESTful API. Here is a simple example Object Function with code to return the user who created the current record:

Then is called by a simple JSON request using the POST method with the application/vnd.oracle.adf.action+json media type. The Resource must include one specific transaction (Id) and it is for this record that the data will be returned. The payload simply specifies the name of the object function.

The response shows the value we expect, the person who created this particular record.

Using Input Parameters

For more complex Object Functions you may have dynamic input parameters against which the logic runs.  When using the RESTful API, at this time only String data types are supported, and so use groovy scripts to validate and manipulate the values passed in.

For multiple parameters you specify them in an Array of String values. See the example below for the syntax and formatting required.

{
"name":"countOpty" , "parameters":[{"inputA":"MyValue01"},{"inputB":"MyValue02"}]
}

The following video shows an example, where an Object Function queries opportunity records based on the first input parameter, and calculates a return value using the opportunity count and a second input parameter. Note that in this illustrative example there is no error checking or data validation that would be required for real usage.

Recommendations and Reminders

These items are some gotchas we found during testing may catch you out when first calling Object Functions using the RESTful services:

  1. When calling object functions the request Media Type must be application/vnd.oracle.adf.action+json and you may see error "JBO-27502: Invalid Resource Type" if you have this incorrectly set.
  2. You'll need to PUBLISH your sandbox to "see" the Object
    Functions via the RESTful service. This doesn't apply to using the
    service resources otherwise.
  3. You need to have one specific Id value in your RESOURCE part
    of the URI for it to work. You cannot just make a request without an Id.
  4. Updating records via calling object functions using setAttribute() will
    not work via the RESTful service due to the lack of transaction
    control. The proper way to do this is to use the PUT method to update
    the record.
  5. The RESTful API only supports sending/receiving String data types, therefore both your parameters and return value will need to be set as String in the Object Function. Build in casting, conversions and data validation in your code.
  6. To reduce data volumes you can add the "fields=" to the end of the resource URI then you'll only get the fields you ask for (i.e. not everything). This is shown below using a REST client, returning only RecordName data.

Join the discussion

Comments ( 4 )
  • shiva Tuesday, May 10, 2016

    Hi,

    How can we do with child custom object using Rest API?


  • guest Monday, May 16, 2016

    Hi.

    I believe this is related to the Request URL. Interrogate the parent /describe document where it should include reference (URI) to the children. As such you should be able to derive the link given to make the request to its object function(s).

    Kind regards

    Richard


  • Omar Garcia Thursday, June 1, 2017
    Hi Richard,

    I have a complex JSON structure that need be pass to a custom method, how can I sent to the method.
    The structure looks like this:
    {
    "name": "postTransactPO",
    "parameters":
    [
    {
    "orders":
    [
    { "id": "2039482342"},
    { "cartItem":
    [
    { "partNumber" : "12345"},
    { "fsc" : "12345"},
    { "cond" : "F"},
    { "qty" : 2},
    { "unitPrice" : 19055.00}
    ]
    },
    { "shipping":
    [
    { "addressId": "123456"}
    ]
    },
    { "billing":
    [
    { "addressId" : "654321"},
    { "purchaseOrderNumber" : "10019830"},
    { "cardId" : "8066"}
    ]
    }
    ]
    }
    ]
    }

    Thank you in advance
  • zab Friday, February 16, 2018
    hi ,

    How can i call this REST web service from java. particularly , how i pass the payload like parameters:[] .
    thanks
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.Captcha