Invoking upsert and delete Operations Using Data Change Notification

Data change notifications (DCNs) with payload directly update the Unwired Server cache, either with the built-in, direct cache-affecting operations :upsert (update or insert), or with :delete.

Syntax

DCN with payload requires a JavaScript Object Notation (JSON) string (dcn_request) that contains one or more :upsert and :delete operations that are applied to the Unwired Server cache (CDB).

http://SAP_mobile_server_host:SAP_mobile_server_port(default 8000)/dcn/DCNServlet
? cmd=dcn
&username=userName
&password=password
&domain=domainName
&package=SAP_mobile_server_PackageName 
&dcn_request={"pkg":"dummy","messages":[{"id":"1","mbo":"CustomerWithParam", "exp":"2012-09-29 00:20:00", 
"op":":upsert","cols":{"id":"10001","fname":"Adam"}}]}
&dcn_filter=fully_qualified_name_of_dcn_filter

Parameters

SAP_mobile_server_host – Unwired Server host name to which the DCN is issued.
SAP_mobile_server_port – Unwired Server port number. The default port is 8000.
username – authorized Unwired Server user with permission to modify the MBO and permission to submit DCN requests (controlled by possessing the "SUP DCN User" logical role).
password – authorized user's password.
domain – Unwired Server domain that contains the package.
package – Unwired Server package that contains the MBO. The format is package:version. For example, e2e_package:1.0. This is the package name and version as it appears in the Packages folder as viewed from Sybase Control Center.
dcn_request – the JSON string that contains operation name and parameters, which must include:
- Package name (pkg) – this package name is required to support backwards compatibility but ignored. The package value supplied in the header is the package value used by DCN.
- A list of messages (messages). Each message includes:
  - A unique message ID (id) used to report back the status. The values provided for the "id" element of each DCN statement within a DCN request message are used only to identify the corresponding status message in the DCN response, which means you can select any value, including nonnumeric characters. Use unique values, so that responses to the correlated requests can be clearly identified.
  - Mobile business object name (mbo).
  - An optional expiration date (exp) sets the expiration time for the cached data using UTC time format (YYYY-MO-DD HH:MM:SS, for example 2012-09-29 00:20:00), which is converted to local time by Unwired Server.
  - Operation name (op): either one of the direct cache-affecting operations (:upsert or :delete) or one of the user-defined MBO operations.
    Note: The specified cache policy property of the operation still applies when DCN is used to invoke a user-defined MBO operation.
  - Bindings (cols): name and values of operation arguments which are mapped to MBO attributes.
- (Optional) ppm – personalization parameters (for either the server or client side) that need to be explicitly defined in the DCN request. The format must conform to the JSON messaging synchronization format, which is a Base64-encoded map of personalization parameters. For example, for runtime credentials sent via DCN, the PPM might be:
```
base64encode("{\"username\":\"supAdmin\",\"password\":\"test\"}");
```
  See Data Change Notification Requirements and Guidelines for guidelines including how to build the ppm.
dcn_filter – (optional) the custom filter used to pre-process the DCN request and post-process the DCN status message. By default, Unwired Server requires the value of the dcn_request field to be a valid JSON string. A DCN filter is used to convert the dcn_request field from a client-specific format to a valid JSON string, before processing in the SUP server. The filter can also reformat the status message returned in the DCN response into a custom format defined by the user.

Examples

Upsert example with header – In the following examples, supAdmin represents the Unwired Server Administrator, and supPwd represents the Administrator's password defined during Unwired Platform installation.
this DCN contains a single :upsert operation that updates or inserts (upserts) data in the Unwired Server cache for the Department MBO.
```
http://dsqavm5:8000/dcn/DCNServlet?cmd=dcn&username=
supAdmin&password=supPwd&package=dept:1.0&domain=default&dcn_request=
{"pkg":"dummy","messages":[{"id":"1","mbo":"Department","op":":upsert",
"cols":{"dept_id":"2","dept_name":"D2","dept_head_id":"501"}}]}
```
Upsert example without header – this JSON string included in a DCN contains a single :upsert operation that updates or inserts (upserts) data in the Unwired Server cache for the Department MBO.
```
dcn_request={"pkg":“TestPackage",
"messages":
	[{"id":"1","mbo":"Department",
		"op":":upsert",
		"cols":{"DepartmentID":"3333",
				 "DepartmentName":"Test Value",
									"DepartmentHeadID":"501"}}]
}
```

Delete example with header – this DCN example deletes a row of data from the Unwired Server cache for the Department MBO:

http://dspevm5:8000/dcn/DCNServlet?cmd=dcn&username=
supAdmin&password=supPwd&package=dept:1.0&domain=default&dcn_request=
{"pkg":"dummy","messages":[{"id":"1","mbo":"Department","op":":delete",
"cols":{"dept_id":"2"}}]}

Delete example without header – this example JSON string included in the DCN sent to Unwired Server, deletes a row of data from the Unwired Server cache for the Department MBO:
```
dcn_request={"pkg":“TestPackage",
	"messages":[{"id":"1","mbo":"Department",
"op":":delete",
	"cols":{"DepartmentID":"3333"}}]}
```

Usage

Follow these guidelines when constructing a DCN:

For timestamp values use this format YYYY-MM-DDTHH:MM:SS where:
- YYYY is the four digit year, MM is the two digit month, DD - day, HH - hour, MM - minutes, and SS -seconds
- - is the literal dash ('-') character, : is the literal colon (':') character, and T is the literal T character.
  For example, 2009-03-04T17:12:45.
Note: Time zone information should not be included since it is ignored by the server. Convert timestamps to the corresponding UTC value before submitting them.
The :upsert operation requires:
- All MBO primary key attributes to be present in the payload.
- Any other MBO attributes used in the upsert.
- All columns in the operation use attribute names (not the column names to which they are mapped).
The :delete operation requires:
- The MBO primary key attribute be present in the payload.
- All columns in the operation use attribute names (not the column names to which they are mapped).