Getting Started with the Siebel REST API

This chapter provides an overview of how to get started with using the Siebel CRM REST API. It contains the following topics:

About Setting Up the Siebel CRM REST API

The Siebel REST API is implemented as part of the Siebel Application Interface installation. You must create and deploy a Siebel Application Interface profile before using REST related components on the Siebel server. For more information about Siebel Application Interface, see Siebel Installation Guide for Microsoft Windows.

Before you begin using the Siebel CRM REST API, you must perform the tasks described in this topic. Many of these tasks are described in the Siebel Deployment Planning Guide.

Review all documented hardware and software requirements.
For more information, see the Certifications tab on My Oracle Support.
The latest version of Siebel Enterprise Server software must be installed.
For more information about performing a new Siebel Enterprise Server software installation, see the Siebel Installation Guide for the operating system you are using.
Install Siebel Application Interface.
For more information about installing Siebel Application Interface, see Siebel Installation Guide for Microsoft Windows.
Configure a Siebel Application Interface profile.
For more information about configuring a Siebel Application Interface profile, see Siebel Installation Guide for Microsoft Windows.
For information about Siebel RESTful configuration parameters that must be configured when you create the Siebel Application Interface Profile, see Using Siebel Management Console to Configure a Siebel Application Interface Profile.
Deploy your Siebel Application Interface profile.
For more information about deploying a Siebel Application Interface profile, see Siebel Installation Guide for Microsoft Windows.
Determine your sizing requirements.
Based on your sizing requirements, install and configure your application interface nodes. For more information about configuring load balancing, see Configuring the worker.properties File for Load Balancing.
Oracle recommends load balancing to distribute complex tasks among multiple Java Web Containers. For more information about load balancing, see Siebel Deployment Planning Guide.
Configure business service methods for RESTful access. For more information about configuring business service methods, see Configuring Business Service Methods for RESTful Access.
Configure integration objects for REST API data access. For more information about configuring integration objects, see Configuring Integration Objects for REST API Data Access.

Using Siebel Management Console to Configure a Siebel Application Interface Profile

After the Siebel Application Interface is installed, you must use the Siebel Management Console to create a Siebel Application Interface profile before using Siebel RESTful services. For more information about creating a Siebel Application Interface Profile, see Siebel Installation Guide for Microsoft Windows.

This topic includes the Siebel RESTful configuration parameters that must be configured when you create the Siebel Application Interface Profile. This topic includes the following:

Configuring REST Inbound Authentication Parameters

You can configure resource parameters by giving the parameters alternative query names.

The following table contains the REST inbound authentication parameters that you configure when you create a Siebel Application Interface Profile. For more information about configuring a Siebel Application Interface profile, see Siebel Installation Guide for Microsoft Windows.

Table REST Inbound Authentication Configuration Settings

Siebel Management Console Parameter	Section	Description
Anonymous User Name	Authentication > REST Inbound Authentication	Specify the anonymous user to use for anonymous REST inbound requests.
Anonymous User Password	Authentication > REST Inbound Authentication	Specify the password for the anonymous user for REST inbound requests.
Authentication Type	Authentication > REST Inbound Authentication	Specify the authentication type that the Siebel Application Interface nodes accept for REST inbound authentication. You can select one of the following options: Basic Authentication Single Sign-On OAuth
Trust Token	Authentication > REST Inbound Authentication	This option appears if you select the Single Sign-On or OAuth option. Specify the trust token to use for REST inbound authentication
Authentication URL	Authentication > REST Inbound Authentication	This option appears if you select the OAuth option. Specify the URL to use for REST inbound authentication.
User Specification	Authentication > REST Inbound Authentication	This option appears if you select the Single Sign-On option. Specify the user specification to use for REST inbound authentication.
Session Timeout (seconds)	Authentication > REST Inbound Authentication	Specify the session timeout, in seconds, to use for REST inbound authentication. This is the timeout which a connection will be kept open for further requests from same user.
Secure Channel	Authentication > REST Inbound Authentication.	This option applies only for the OAuth authentication type as follows: Select this check box only when you have already imported the Authentication URLfs CA certificate into the Application Interface truststore. Deselect this check box when the Authentication URLfs CA certificate is not available in the Application Interface truststore. In this case, the Application Interface trusts all certificates while calling the Authentication URL over HTTPS.

Configuring REST Inbound Default Parameters

The following table contains the REST inbound default parameters that you configure when you create a Siebel Application Interface Profile. For more information about configuring a Siebel Application Interface profile, see Siebel Installation Guide for Microsoft Windows.

Table REST Inbound Default Configuration Settings

Siebel Management Console Parameter	Section	Description
Object Manager	REST Inbound Defaults	Select the Object Manager component to use for REST inbound communications, such as EAI Object Manager.
REST Response Base URL	REST Inbound Defaults	Specify the base URL used to generate URLs for resources in REST responses.
Maximum Possible Connections	REST Inbound Defaults	Specify the maximum number of possible connections available to serve REST requests. Default value: 20.
Minimum Connections in Pool Size (%)	REST Inbound Defaults	Specify the minimum number of connections in the pool available to serve REST requests, as a percentage of the maximum. Default value: 25.

Configuring REST Resource Parameters

The table below contains the REST resource parameters that you configure when you create a Siebel Application Interface Profile. For more information about configuring a Siebel Application Interface profile, see Siebel Installation Guide for Microsoft Windows.

Table REST Resource Parameter Configuration Settings

Siebel Management Console Parameter	Section	Description
Method Name	REST Inbound Defaults / REST Resource Parameter List > Query.	Specify the method name to use for queries.
Name	REST Inbound Defaults / REST Resource Parameter List > Query > Parameter List.	Specify the name for each query parameter.
Alias	REST Inbound Defaults / REST Resource Parameter List > Query > Parameter List	Specify the alias for each query parameter in the REST resource URls. Query parameters include: Limit, Pagesize, and Offset.

Configuring the worker.properties File for Load Balancing

A load balancer acts as a reverse proxy and distributes network or application traffic across a list of available of servers. A load balancer works as a middleman between the client and the servers by accepting requests from clients and distributing the requests to the backend servers based on the configured parameters.

The Apache HTTPD mod_jk Web server module is used to load balance Apache Tomcat servers. The load balancer.mod_jk is the connector used to connect Apache Tomcat with Web servers using an AJP connector.

This topic describes the initial configuration of the workers.properties file for load balancing. For more information about planning and managing load balancing for your deployment, see Siebel Installation Guide for the operating system you are using, Siebel Deployment Planning Guide, and Siebel System Administration Guide.

For more information about third-party load balancing options, see the Certifications tab on My Oracle Support.

Oracle recommends for optimal usage of Siebel User Session Connections maintained on Apache Tomcat.

To configure load balancing

Download and install the version of Apache HTTPd Server you want to install from the following location:
http://tomcat.apache.org/
For detailed information about installing the HTTPd Server, see Apache Tomcat documentation.
To configure the listen port, go to <HTTPDRootDir\> folder and do the following:
1. Using any text editor, open the httpd.conf file on the Web server.
2. Locate the Listen section and add the HTTP port number:
  
  Listen <port>
3. Save the httpd.conf file.
4. Start the Web server by executing the httpd.exe file.
5. To check if the Web server is running, open a Web browser and enter the following URL:
  http://hostip:<port>
Download the Apache mod_jk module from the following location:
http://httpd.apache.org/download.cgi
Save the mod_jk.so file then place it in the <HTTPDRootDir\> modules directory folder.
Create the following properties and log files:
1. Create the workers.properties file then place it in the <HTTPDRootDir\> directory folder.
2. Create the mod_jk.log file then place it in the <HTTPDRootDir\> directory folder.

Modify the apache httpd.conf file as follows:

Add a Load statement to load the mod_jk.so file as follows:

# Load the mod_jk module

LoadModule jk_module modules/mod_jk.so

Add an if statement to define the commands to be executed once the module is loaded as follows:

#Declare the module for use with the <IfModule directive> element.
<IfModule jk_module>
  JkWorkersFile conf/workers.properties
  JkLogFile logs/mod_jk.log
  JkLogStampFormat "[%b %d %Y - %H:%M:%S] "
  JkRequestLogFormat "%w %V %T"
  JkLogLevel trace
  JkMount /* loadbalancer
  JkMount /Jkmanager status
<IfModule>

Save and close the httpd.conf file.

Define the list of Tomcat workers that can accept requests by adding the following configuration to the workers.properties file:

# Define workers

worker.list=loadbalancer,status

# Set properties for worker1
worker.javacontainer1.type=ajp13
worker.javacontainer1.host=<hostip>
worker.javacontainer1.port=<ajportnumber>
worker.javacontainer1.lbfactor=1
worker.javacontainer 1.socket_keepalive=1
worker.javacontainer1.socket_timeout=300

# Set properties for worker2
worker.javacontainer2.type=ajp13
worker.javacontainer2.host=<hostip>
worker.javacontainer2.port=<ajportnumber>
worker.javacontainer2.lbfactor=1
worker.javacontainer2.socket_keepalive=1
worker.javacontainer2.socket_timeout=300

# Set properties for loadbalancer
worker.loadbalancer.type=lb 
worker.loadbalancer.balance_workers= javacontainer1, javacontainer2

# Get statistics
worker.status.type=status

Note: For the worker.<workername> property, both Apache Tomcat workers must have a unique name. For each node, the workername must be same as the JVMRoutename defined in the Apache Tomcat server.xml file. For example, if tomcat 1 has javacontainer1 set as the value for the JVMRoute name in the Apache Tomcat server.xml file for tomcat1, then the worker.properties parameter must have a worker.javacontainer1 value.

Test the server by submitting the following REST API request:
http://hostip:<port>/siebel/v1.0/data/Account/Account/88-431RF

Configuring Business Service Methods for RESTful Access

You can use the Siebel REST API to access Siebel Business Services. Before you access the Siebel Business Services, you have to associate the business with a responsibility to control access to the business service and its methods. For more information about associating a business service with a responsibility, see the Siebel Security Guide.

Caution: Oracle recommends that you do not add responsibilities to the EAI Siebel Adapter Business Service as it may lead to denial of general REST (repository or data) and SOAP Web Services access to other users.

The REST Service API has more restrictive access for Siebel Business Services than other Siebel Access Channels. Each Business Service and Business Service Method that is accessed through the REST API needs to be explicitly configured for access.

Note: For the Siebel REST API, if a Business Service Method is not configured for access by a particular responsibility, then it will not be accessible. This is different from SOAP or the User Interface channels where an unconfigured Business Service is accessible to all.

To configure Business Service Methods for RESTful Access

Log in as an administrator.
Navigate to the Administration - Application screen, then the Business Service Access view, and then the Access By Responsibility view.
In the Business Service list, click New to select a business service.
A new record appears in the Business Service list.
Click the Select button in the Name field.
The Business Service dialog box appears.
Select the business service to which you want to control access, then click OK.
The selected business service appears in the Business Service list view.
In the Access By Responsibility list view, click New.
The Add Responsibilities dialog box appears.
Select a responsibility to associate with the business service and then click OK.
The selected responsibility appears in the Access By Responsibility list view.
In the Business Service Method list, click New to specify the business service methods to which the responsibility gains access.
The Business Service Method dialog box appears. This dialog box displays the list of business service methods to which access is currently controlled.
If the business service method to which you want to allow the responsibility access appears in the Business Service Method dialog box, select it, then click OK.
Click the Select button in the Name field.
The Business Service Method dialog box appears.
Select a business service method to associate with the responsibility and then click OK.
The selected business service method appears in the Business Service Method list view.
From the Broadest Visibility list, select the view mode to associate with the responsibility.
Step off the record to save changes.
Click Clear Cache.

Restart the Siebel Application Interface Apache Tomcat server by executing the following batch scripts:

For Microsoft Windows:

\applicationcontainer\bin\shutdown.bat
\applicationcontainer\bin\startup.bat

For UNIX:

\applicationcontainer\bin\shutdown.sh
\applicationcontainer\bin\startup.sh

Configuring Integration Objects for REST API Data Access

An additional Business Object may be exposed through the Siebel REST API by creating an Integration Object for the Business Object, Base <Business Object Name>. Each Integration Component in the Integration Object should have an Integration Component Key, REST ROWID User Key:1, with one Integration Component Key Field Id defined. Without this Integration Component Key, the REST API upsert requests will not work on the Integration Component. For example:

If BO = "Service Request" then the IO name must be "Base Service Request"

For more information about integration objects, see Integration Platform Technologies: Siebel Enterprise Application Integration.

Creating an Outbound Web Service Based on an Open APICompliant JSON File

Use the procedures in this topic to create an outbound Web Service based on an OpenAPI compliant JSON file.

To create an outbound Web service based on an OpenAPI compliant JSON file

In Siebel Tools, create a new workspace.
From the File menu, choose New Object to display the New Object Wizards dialog box.
Click the EAI tab, and then double-click Web Service.
The JSON Import Wizard appears.
1. Select the project where you want the objects to be held after they are created from the JSON document.
2. Specify the external JSON schema document that contains the Web service or Web services definition that you want to import.
3. Specify the log file where you want errors, warnings, and other information related to the import process to be logged or accept the default.
Click Next.
A summary of your import information, as well as any errors, appears.
Oracle recommends that you do not select the Deploy the Integration Object(s) and the Proxy Business Service(s).
Click Finish to complete the process of importing the external object definitions into the Siebel repository.

This procedure generates two objects in the Siebel repository:

A REST outbound proxy business service. This service acts as a client-side implementation of the Web service and includes the operations and the arguments to the operations defined in the JSON document.
Integration objects, representing input and output parameters of the service methods, if any of the operations require a complex argument to be passed. If the service does not use complex arguments, then no integration object definitions will be created.

Business Services, methods, arguments, and port information are shown in the Administration - Web Services screen, REST Outbound Web Services view in the Siebel client.

Before importing the external schema, ensure that there are no objects in the Siebel Database with the same name as that of the new Web Service, Port, Port Type and Operation or Methods.

For additional information about outbound web services, see Integration Platform Technologies: Siebel Enterprise Application Integration.