You use the entity operation handler as a JSON object with the following properties:

  • type — use this property to identify the type of ABL program. Possible values include class and procedure. If no value is set, the DOH uses class as the default value. If you are referencing a procedure, you must set the value to procedure.
  • name — the name of the ABL class or persistent procedure, as is set in your application's PROPATH. If the ABL class is contained in a package, specify the full package name (for example, Business.Customer). If the ABL procedure file is in a folder in the ABL web app project, specify the relative path (for example, Business/Customer).
  • function — the name of the ABL class method, procedure, or user-defined function that needs to be invoked.
  • arg — a JSON array of objects to map the method or procedure's input and output parameters to message elements in the HTTP request or response. Each object in the array represents the mapping of a single parameter to HTTP message elements. Each parameter object contains the following properties:
    • ablName — the name of the ABL input or output parameter. If the parameter type is RETURN, as set in the ioMode property (see below), skip this property.
    • ablType — the datatype of the ABL parameter. Possible values include CHARACTER, LONGCHAR, INTEGER, INT64, DECIMAL, LOGICAL, ROWID, RECID, DATE, DATETIME, DATETIME-TZ, RAW, MEMPTR, DATASET1, TABLE2, BLOB, CLOB, EXTENT3, and CLASS4.
    • ioMode — the parameter type. Possible values include INPUT, OUTPUT, INPUT-OUTPUT, and RETURN.
    • msgElem — a JSON object or array of objects that maps the ABL parameter to a message element in the HTTP request or response. Each msgElem object contains two properties--type and name. The value of the name property depends on the value of the type property. Specify values for type and name as described in this table.
Type Name When to use Use for both requests and responses?
none Leave the name property blank or use null.
  • When the ABL parameter is an input type and there is no corresponding element in the HTTP request to map it to. Specifying none prompts the DOH to send an empty parameter to the ABL class method or ABL procedure.
  • When the ABL parameter is of an output type and you do not want to produce an HTTP message element from it.
Requests and Responses
path Specify the name of the path parameter as defined in the WEB transport properties When the ABL parameter is an input type and its value needs to be extracted from a parameter in the requested URL path. For example, assume that a client application makes a GET request to http://localhost:8810/myapp/web/ CustomerOrderService/customers/123 to retrieve customers records by customer ID (123).

To set this up, set path as the msgElem type and customerID as the msgElem name. Edit the PAS for OpenEdge instance's openedge.properties file and add a handler for the path parameter in the web application's WEB transport properties section (that has a title similar to oepas1.myapp.WEB). Here is an example of the handler property to add: handler2= OpenEdge.Web.DataObject.DataObjectHandler: /customers/{customerID}

Requests only
query Specify the name of the query parameter When the ABL parameter is an input type and its value needs to be extracted from a query in the requested URL path. For example, assume that a client application makes a GET request to http://localhost:8810/myapp/web/ CustomerOrderService?id=123 to retrieve customers records by customer ID (123).

To set this up, set query as the msgElem type and id as the msgElem name.

Requests only
queryMap Leave the name property blank or use null When the ABL parameter is an input type and the requested URL path contains a query of the type

OpenEdge.Core.Collections.IStringStringMap. This is mostly useful for debugging.

 Requests only
header The name of the HTTP header. For complex headers with parameters, use the syntax <headername>; <parameter> When the ABL parameter is an input, output, or input-output type, and its value needs to be either retrieved from an HTTP request header (for input operations) or passed on to an HTTP response header (for output operations). Requests and Responses
headerSet Leave the name property blank or use null When the ABL parameter is an input, output, or input-output type and its value is an array of HTTP header objects. This is mostly useful for debugging. Requests and Responses
field The name of a root-level key in a JSON or multipart message When the ABL parameter is an input, output, or input-output type, and the value needs to be retrieved from or passed on to a JSON or multi-part message in an HTTP request or response. You can only retrieve or pass the value of a key that is at the topmost level in the message hierarchy. For example, in the following JSON message, you can only retrieve the value of message, status, date, or customer. If you need to access a 'child' element (such as text, target, id, or name in this example), you must do so from within your ABL code.
{
	"message": {
		"text": "Order number 213 was delivered."
		"target": "239888"
	},
	"status": "sent",
	"date": "10-APRIL-2018",
	"customer": {
		"id": "1282",
		"name": "John Jones"
	}
}
 Requests and Responses
cookie Specify the name of the browser cookie When the ABL parameter is an input, output, or input-output type, and its value needs to be retrieved from or passed on to a single-value browser cookie. Requests and Responses
statusCode Leave the name property blank or use null When the ABL parameter is an output type, and the its value needs to be passed to the client application as an HTTP status code. Note that this overrides the statusCode property set for the HTTP verb. Responses only
body Leave the name property blank or use null When the ABL parameter is an input, output, or input-output type, and you need to either retrieve its value from the message body of the HTTP request or pass on the value from the ABL parameter to the message body of the HTTP response. While retrieving the value for an INPUT parameter, you can set a flag to strip the envelope from the HTTP request message. Similarly, in the case of an OUTPUT parameter, you can optionally set a flag to add the envelope to the parameter output before forming the HTTP response. To set these flags, add a an options property under the HTTP verb in the mapping file as shown in this example: 
"/getPersonalizedMessage": {
            "GET": {
                "contentType": "application/json",
                "options": {
                    "writeBI": true,
                    "requestEnvelope" :true     
                    "responseEnvelope" :true    
                    "errorEnvelope" :true       
                },
 Requests and responses
request Leave the name property blank or use null When the ABL parameter is an input type, and you want to populate its value with the complete HTTP request message, including the headers, body, etc. Requests only
httpMethod Specify the name of the HTTP verb When you want to perform some type of debugging by passing the HTTP method name (GET, PUT, POST, etc) to an ABL method via an INPUT parameter. Requests only
constant Specify the value that you want to pass on to the ABL parameter When you want to populate the value of an input parameter with the value of the name property. This is mostly useful for testing. Requests only

Example of a dataset schema in the mapping file

If you specify DATASET in the ablType property, you must specify the dataset schema in the mapping file. Place the dataset or temp-table schema under a schemas object inside your ServiceName (HelloService in the following example), at the bottom of the JSON mapping file. Here is an example of a schema for a dataset that contains a temp-table:

"services": {
	"HelloService": {
		....
		....
		"schemas": {
     	"dsCustomer" : {
    		"ttCustomer": {
    			"trackChanges": true,
    			"indexes" : {
    	            "CustNum": {
    	                "primary": true,
    	                "unique": true,
    	                "word": false,
    	                "fields": ["CustNum"]
    	            },
    	            "Name": {
    	                "primary": false,
    	                "unique": false,
    	                "word": false,
    	                "fields": ["Name"]
    	            },
    	            "SalesRep": {
    	                "primary": false,
    	                "unique": false,
    	                "word": false,
    	                "fields": ["SalesRep"]
    	            }
    			},
    			"fields": [
    			            {"name": "CustNum", "ablType": "INTEGER  ", "extent": null},
    			            {"name": "Country", "ablType": "CHARACTER", "extent": null},
    			            {"name": "Name", "ablType": "CHARACTER", "extent": null},
    			            {"name": "Address", "ablType": "CHARACTER", "extent": null},
    			            {"name": "Address2", "ablType": "CHARACTER", "extent": null},
    			            {"name": "City", "ablType": "CHARACTER", "extent": null},
    			            {"name": "State", "ablType": "CHARACTER", "extent": null},
    			            {"name": "EmailAddress", "ablType": "CHARACTER", "extent": null}
    			]
    		}
    	}
    }
  }	
}
Related temp-tables in a dataset

If you have related temp-tables in a dataset and you want the response message to represent this relationship as nested JSON objects, you must define the relationship in the dataset schema. Here is the format (note the relationship in the attr object):

"schemas": {
   "<dataset-name>" : {
       "<temp-table-1>" : { /* definition */},
       "<temp-table-2>" : { /* definition */},
       "attr": {
            "relations": [
                 { 
                    "parentTable": "<parent-temp-table-name>",
                    "childTable": "<child-temp-table-name>",
                    "fields": [ 
                         {
                           "parentField": "<parent-table-field-name>", 
                           "childField": "<child-table-field-name>"
                         }
                     ],
                     "name": "<relation-name>",
                     "nested": true,
                     "active": true,
                     "recursive": false,
                     "reposition": false                    
                 }
             ]
       }
   }
}

Each of the relationship attributes (name, nested, active, recursive, and reposition) correspond to options that you can specify in the data-relation part of an ABL dataset definition. To learn more about these options, see Static ProDataSet and its Data-Relations.

Note: You can define multiple relationships in the relations JSON array. The relationships should be defined in the same order as in the ABL dataset definition.

Example

Consider a customer record that is related to multiple order records. Without a relationship defined (between the Customer and Order temp-tables) in the dataset schema, the DataObjectHandler produces individual JSON objects in the response message:
{
    "dsEntityInfo": 
        {
            "Customer": 
                [
                    {
                     "CustNum": 1,
                     "CustName": "Lift Tours"
                    },
                ],
            "Order": 
                [
                    {
                    "OrderNum": 100,
                    "OrderTotal": 1234.89,
                    "Customer_id": 1
                    },
                    {
                    "OrderNum": 150,
                    "OrderTotal": 999.99,
                    "Customer_id": 1
                    },
                 ]
        }
}
However, if the relationship is defined in the dataset schema, the Order records are nested under the Customer record in the response message, as shown in the example below.

Dataset schema example with related temp-tables

"schemas": {
   "dsEntityInfo" : {
       "Customer" : { /* definition */},
       "Order" : { /* definition */},
       "attr": {
            "relations": [
                 { 
                    "parentTable": "Customer",
                    "childTable": "Order",
                    "fields": [ 
                         {
                           "parentField": "CustNum", 
                           "childField": "Customer_id"
                         }
                     ],
                     "name": "Cust-Order-Relation",
                     "nested": true,
                     "active": true,
                     "recursive": false,
                     "reposition": false                    
                 }
             ]
       }
   }
}

Example output in response message

{
    "dsEntityInfo": 
        {
            "Customer": 
                [
                    {
                     "CustNum": 1,
                     "CustName": "Lift Tours"
                     "Order": 
                     [ 
                       {
                       "OrderNum": 100,
                       "OrderTotal": 1234.89,
                       "Customer_id": 1
                       },
                       {
                       "OrderNum": 150,
                       "OrderTotal": 999.99,
                       "Customer_id": 1
                       }
                     ] 
                    }
                 ]
          }
}
1 If you specify a DATASET as the ablType, you also need to define the dataset schema in the mapping file. To learn more, see the example dataset schema that follows the msgElem properties table.
2 Use this to specify temp-tables. You also need to define the temp-table schema in the mapping file. To learn more, see the example dataset schema that follows the msgElem properties table below.
3 If the parameter is an ABL array, use the syntax <Datatype> EXTENT (for example, CHARACTER EXTENT).
4 If the parameter is an ABL object, use the syntax CLASS <full.type.name> (for example, CLASS Business.Customer)