Configuring the Microsoft SCOM REST Event Connector and Web Service

3 Configuring the Microsoft SCOM REST Event Connector and Web Service

The Event Connector Web Service is the API that receives the request directly from Oracle Enterprise Manager and performs the follow up actions of authenticating to the SCOM server and translating the alert into a format that the management pack can interpret.

Topics

Configuring the Event Connector Web Service

Log in to the host where you will run the Event Connector Web Service.

This can be a Windows or Linux host, provided it has Java 17 or later available.
Open a terminal window and navigate to the directory containing WebService.jar.

This directory will be referred to as ECWS_HOME in this chapter.

After configuring the Event Connector Web Service, two additional folders, logs/ and config/, are created inside it. It is recommended that you choose an empty folder that can be dedicated solely to the Event Connector Web Service files.
Execute the following command, where JAVA_HOME is set to Java 17 or later:
```
$JAVA_HOME/bin/java -jar WebService.jar -wsconfig
```
Select Configure connector webservice and provide the following inputs:
- Webservice Username and Password: The credentials used to authenticate Oracle Enterprise Manager requests to the Event Connector Web Service. These credentials are also required the next time you run WebService.jar to view or modify existing configurations. Note that these credentials are not the Microsoft SCOM Web Service credentials.
- Webservice Port: The port on which the Event Connector Web Service listens. If the Event Connector Web Service is on a different host than the Oracle Management Service, you must ensure that the port is accessible from the host where the Oracle Management Service is running. The default port is 8080.
- SCOM Username and Password: The credentials that allow the Event Connector Web Service to authenticate to the Microsoft SCOM Web Service. Do not include the domain name when providing the SCOM Username.
- SCOM Windows Domain: The domain to which the specified SCOM user belongs.
- SCOM Port: The port on which the Microsoft SCOM Web Service listens. If the SCOM Web Service is on a different host than the Event Connector Web Service, you must ensure that the port is accessible from the host where the Event Connector Web Service is running. The default port is 80.
- SCOM Server Hostname: The resolvable host name where the Microsoft SCOM Web Service is running.
- SCOM Management Server: The name that SCOM uses to identify its management server.
- Windows Event ID: The integer value that identifies an incoming event from Oracle Enterprise Manager. Select a value that does not conflict with other Event IDs in the Windows Application Logs. If no ID is provided, the configuration will default to 900.
- Enable Web Service SSL: Enter yes or no. This enables one-way SSL between the OMS and the Event Connector Web Service. You will also be prompted to provide the keystore password. For more information, see Enabling Secure Communication.
- Enable SCOM SSL: Enter yes or no. Enable this option when the Microsoft SCOM Web Service is configured for secure communication. This allows the Event Connector Web Service to trust the certificate presented by the Microsoft SCOM Web Service. You will also be prompted to provide the truststore password. For more information, see Enabling Secure Communication.
On the main screen, select View current configurations to verify that the information provided is correct.

Here's an example of the configuration:

If any of the information is incorrect, select Update current configurations on the main screen. After verifying that the configuration details are correct, select Exit. You can modify the configuration at any time by executing the WebService.jar file with the -wsconfig flag. Note that if you forget or misplace the credentials created for the Event Connector Web Service, delete the configuration file at <ECWS_HOME>/config/WebServiceConfig.json and reconfigure the connector.

Running the Event Connector Web Service

To run the service, navigate to ECWS_HOME and execute the WebService.jar file as mentioned in the configuration steps, but omit the -wsconfig flag:

$JAVA_HOME/bin/java -jar WebService.jar

If successful, the following message is displayed in the terminal session:

Connector webservice successfully started on port <PORT>

If no message is displayed or the application exits unexpectedly, re-run the command in debug mode using the -logLevel flag. This generates more detailed messages in the ecws.log files, located in the <ECWS_HOME>/logs directory. Here's an example command:

$JAVA_HOME/bin/java -jar WebService.jar -logLevel=DEBUG

You can also search the logs for the following line, which will be followed by its cause:

Unable to start web service due to the following

Running the Event Connector Web Service in the Background

By default, the Event Connector Web Service runs in a command or terminal window that must remain open. However, it can be manually configured on Windows and Linux to run as a background process at startup. The required steps depend on your Operating System (OS), so refer to the relevant OS documentation. However, here are example steps that work in most environments.

Windows Example

Open a text editor and paste the following script after replacing <ECWS_HOME> and <JAVA_HOME> with the appropriate paths:
```
@echo off
cd /d "%ECWS_HOME%"
"%JAVA_HOME%\bin\java.exe" -jar "WebService.jar" >> "logs\ecws.log" 2>&1
```
Save the script as a batch file named EcwsStartScript.bat.
Open Windows Task Scheduler.
From the Actions menu, select Create Task.
The Create Task dialog box is displayed.
In the General tab:
1. Enter ecws in the Name field.
2. Select the Run whether user is logged on or not option.
3. Select the Run with highest privileges option.
In the Triggers tab:
1. Click New.
  The New Trigger dialog box is displayed.
2. From the Begin the task menu, select At startup.
3. Ensure that the Enabled option is selected.
4. Click OK.
In the Actions tab:
1. Click New.
  The New Action dialog box is displayed.
2. From the Action menu, select Start a program.
3. Set the Program/script field to <ECWS_HOME>\EcwsStartScript.bat.
4. Click OK.
In the Conditions tab, ensure that the Start the task only if the computer is on AC power option is not selected.
In the Settings tab, ensure that the Stop the task if it runs longer than... option is not selected.
Click OK.
Open a command prompt as Administrator and use the following commands to:
- Start the task:
```
schtasks /run /tn "ecws"
```
- Stop the task:
```
schtasks /end /tn "ecws"
```

Linux Example

Create a new service file at /etc/systemd/system/ecws.service.

Replace <ECWS_HOME> with the appropriate installation path, for example, /opt/ecws, and copy the following contents into ecws.service:

[Unit]
Description=OEM to SCOM Event Connector Web Service
After=network.target

[Service]
WorkingDirectory=<ECWS_HOME>
ExecStart=/usr/bin/java -jar <ECWS_HOME>/WebService.jar
Restart=always
RestartSec=15
SuccessExitStatus=143

[Install]
WantedBy=multi-user.target

Execute the following commands to:
- Load the service:
```
sudo systemctl daemon-reload
```
- Enable the service:
```
sudo systemctl enable --now ecws
```
The service will be initiated at system startup but can be controlled using the following commands:
- Start the service:
```
sudo systemctl start ecws
```
- Stop the service:
```
sudo systemctl stop ecws
```

Configuring the Oracle Enterprise Manager Management Connector

Ensure that the Event Connector Web Service is configured and running.
Confirm that the OMS host can access the Event Connector Web Service by performing the following steps:
1. Open the test-connection endpoint in a browser. For example, if the Event Connector Web Service is running on host mycompany.com, port 8443, and secure communication is enabled, the URL would be:
```
https://mycompany.com:8443/test-connection
```
  You will receive an authentication prompt.
2. Enter the credentials you created for authenticating the Event Connector Web Service.
A json response indicating that the test was successful is displayed. If you do not see the message, resolve the communication or configuration issue before proceeding.
From the Setup menu, select Extensibility, then select Management Connectors, and create a new SCOM REST Event Connector instance.
On the configuration page, ensure that at least the following web service details are entered or updated:
- In the createEvent and updateEvent fields, replace <hostname> with the resolvable host name that your Event Connector Web Service is running on.
- In the createEvent and updateEvent fields, update the port number if you are not using the default 8080.
- In the createEvent and updateEvent fields, replace http with https if secure communication is enabled.
- Update the Webservice Username and Webservice Password with the credentials created for authenticating to the Event Connector Web Service.
- Configure proxy settings only if using a proxy (optional).
Note:
This configuration page information applies only to communication between Oracle Enterprise Manager and the Event Connector Web Service. These fields do not apply to communication between the Event Connector Web Service and the Microsoft SCOM Web Service.

Here's an example that shows the minimal configuration requirements:
Click OK to save the configuration.