Binding a REST Web Service Data Source to a Mobile Business Object

Bind the attributes and operations of a REST (Representational State Transfer) Web service to a mobile business object.

The main difference with binding to a REST Web service data source and any other Web service data source is the definition page. Other pages (parameter mapping, attributes mapping, role mapping, and so on), are the same. Successfully invoking a REST Web service requires:
  1. In the Bind Data Source wizard, enter the following information and click Next:
    Field Action
    Data source type REST Web Service
    Connection profile Select the REST Web Service connection profile to which you are binding your mobile business object attributes. If the required data source is not in the list, click Create to define a new connection profile.
  2. In the Definitions page, enter the attributes definition information.
    This information translates into the detailed tabular view of the REST Web service that is mapped to mobile business object attributes:
    Tab Description
    Resource base URL The base URL for a REST Web service resource URL, required to construct the resource URI. For example, http://example.com.

    The base URL was defined in the connection profile, and is shown (read-only) in the definition page for attributes or operations.

    Resource URI template The URI template is appended to the base URL (for example, customers/{id}). The template determines how the URI is parsed so all possible parameters are retrieved. All parameters are treated as enterprise information system (EIS) operation arguments, enabling MBO create, read, update, and delete (CRUD) operations on the REST Web service resources.
    You can specify the datatype for parameters defined in the URI template using this format: {paramName(xsdType)} For example, '/getCustomer/{id(int)}'. A string datatype is used if you do not explicitly specify the datatype. You can also specify support of nullable for the parameter as: '/getCustomer/{id(int?)}'. These datatypes can be specified in the URI template and are case-sensitive:
    • boolean
    • string
    • binary
    • char
    • byte
    • short
    • int
    • long
    • integer
    • decimal
    • float
    • double
    • date
    • time
    • dateTime
    You cannot specify the length in the URI template for parameters, but can modify parameter length after the REST MBO is created from the Properties view.
    HTTP method The method called, either GET, PUT, POST, or DELETE.
    Expected status code All available HTTP status codes are shown in the drop-down list. The default is 200. If you change it to NONE, it means that the returned status code is not checked.

    For each EIS REST Web Service operation, you can choose an HTTP status code as the expected status code. If the returned status code is the same as the specified expected status code, the EIS operation was executed successfully.

    If the returned status code does not match the specified expected status code, the EIS operation fails.

    Representation
    Allows you to specify the request or response representation. Select the representation type:
    • Request
    • Response

    Enter or select:

    • Name – name of the representation, which must be unique.
    • Referenced representation – All existing representations defined for the same MBO are listed and can be selected, but only the same Type of representation can be referenced. For example, if you previously defined a request representation for a create EIS operation, you can use it as a referenced request representation to define a new update representation for a EIS operation.
    Click Edit to specify the XML schema for a request or response representation, instead of referencing an existing representation:
    • Name – name of the XSD.
    • Type – Request or response.
    • XSD URL – URL to an available XSD.
    • XSD file – allows you to import the XSD from a local file.
      Note: If you choose file under the project root path in the dialog used to locate the XSD file, SAP Mobile WorkSpace uses the relative file path against the project root instead of using the absolute file path. Otherwise, SAP Mobile WorkSpace continues to use the absolute file path. You are encouraged to put XSD files under a path relative to the project root path, since the XSD file can be located even if the project is moved to another folder, avoiding the "XSD absolution path not found" error returned during project import or migration.
    • Root element – The root element used as the XSD request input.
    • Load element – Select this after specifying the XSD URL or XSD file, to retrieve all available load elements defined in the XSD.

    Only one XSD can be defined for a given representation.

    Define XSLT manually – for response representation, after the XSD definition and root element was specified, SAP Mobile WorkSpace automatically generates a default XSLT for the response representation. You can open the XSLT editing dialog to modify the XSLT. Modifying multi-XSLTs for one response representation to support shared read MBOs is also supported. All available XSLT definitions are listed in the table in the XSD definition dialog:
    • Save to file – modify by changing the selections and save to a file.
    • Load from file – since it is difficult to type in the XSLT contents accurately, this option allows you to retrieve an existing XSLT file from the file system. If you choose this option the XSLT text in the window is replaced by the information contained in the selected file.

    Select OK to save your definition and exit the dialog.

    Authentication
    Supports HTTP Basic Authentication:
    • User name – authenticated user
    • Password – password of the authenticated user.

    The user name and password fields can be entered directly, retrieved from a personalization key, or by selecting <New key> and creating a new personalization key.

    To use the device user runtime credentials, you need to select system defined personalization keys ('username' and 'password'), in the corresponding fields from the drop-down list.

    HTTP header Captures all properties needed to execute or manage the REST Web Service.
    You can enter the existing HTTP header as defined in the HTTP specification, or declare your own HTTP header. For each element of the HTTP header you can:
    • Input/Output – specify if it is used as an input, output or both.
    • Variable – specify a literal value as the HTTP header’s value. Specify a "Variable" to denote it as a 'parameterized' header. For parameterized headers, SAP Mobile WorkSpace parses and treats the value as an input argument or output column of the EIS operation (depending on whether the definition is input or output).
    • Value – specify the header value. For example application/xml.
    The Input/Output/Both setting determines if Variable and Value are enabled:
    • Input – Variable is enabled:
      • If you select Variable, the Value field is disabled and cleared.
      • If you unselect Variable, the Value field is enabled, and you must specify a value.
    • Output – Variable is an automatically selected read-only field. The Value field is disabled and cleared.
    • Both – Variable is an automatically selected read-only field. The Value field is disabled and cleared.
  3. Click Finish to use default mappings, or Next to modify the columns to attributes mapping, or parameter mapping.
  4. From the Parameters page you can configure these MBO argument properties that are modeled from the data source's remote operation argument:
    • Argument – the MBO argument name
    • Datatype – datatype of the argument
    • Nullable – identifies if NULL is a valid value
    • Default value – the default value, if any, of the MBO argument

    Click Next or Finish when done.

  5. The Attributes Mapping screen provides a graphical view of the columns to table mappings. You can collapse and expand the view and click the navigational buttons to rearrange attributes, remove and add individual attributes, and remove a mapping or all mappings. Click Next or Finish when done.
    You can remove mappings without removing associated attributes from the graphical view only.
  6. After the Definition page of the New Operation wizard, you can modify operation and client parameters from the Parameters page by selecting the corresponding tab:
    • Operation Parameters – lists all operation arguments, associated datatypes, nullability, and the arguments value can be filled from attributes, client parameters, or default values.
    • Client Parameters – add client parameters used by device application users to provide values to the operation arguments during runtime.
  7. The Role Assignments screen allows you to Create, Add, and Remove role assignments from the mobile business object. Click Finish when done.