Posting events using the HTTP gateway

An HTTP client can send events by using the HTTP gateway. A gateway feature must be included in the server configuration for the gateway to accept events over HTTP.

Before you begin

You must have an Insight Server that is configured and started. You must also deploy your solution to the server before you can post an event.

The Insight Server must be configured to enable the HTTP gateway feature. The HTTP gateway feature is enabled by default in a development server that is created from the cisDev template, and it can be enabled in a runtime server or inbound connectivity server.

The HTTP gateway feature can be activated by including the following configuration in the server.xml file:

<featureManager>
   <feature>ia:iaHTTPGateway-8.10.5</feature>
</featureManager>

If application security is enabled, the iaHTTPGatewaySubmitter security role is used to authorize users and groups to submit events by using the HTTP gateway. The <security-role> element must be configured in the <authorization-roles id="iaAuthorization"> element. The following example server.xml file shows how to authorize all authenticated users to submit events by using the HTTP gateway:

<featureManager>
   <feature>ia:iaHTTPGateway-8.10.5</feature>
</featureManager> 
<authorization-roles id="iaAuthorization">     
   <security-role name="iaHTTPGatewaySubmitter">      
      <special-subject type="ALL_AUTHENTICATED_USERS" />     
   </security-role>
   <!-- Other security-role elements, as required -->
</authorization-roles>

The HTTP gateway accepts HTTP POST requests containing XML or JSON content. You can use XML to POST events that are represented by TYPED_XML (conforming to the XML schema of the event) or GENERIC_XML.

Note: If the solution has inbound HTTP endpoints, you can configure and deploy the inbound connectivity for your solution by using the Deployment configurations wizard in Insight Designer. When you use inbound HTTP endpoints, you do not need to enable the inbound HTTP gateway, although both features can be configured. An inbound HTTP endpoint that uses the inbound connectivity feature accepts either TYPED_XML or JSON content, depending on the corresponding inbound binding definition.

Procedure

Create an XML or JSON file that describes an event.
1. If you are using TYPED_XML, export your event types to an XSD file.
  You can use a link in the solution map to open the export wizard. Select the solution in your workspace to open the solution map. For more information, see Exporting event types to an XML schema.
  Create an XML file (data/event.xml) from the XML schema. For more information, see Creating an event XML file from an XSD. In the New XML File wizard, select the event of interest as the root element. The result gives you an XML formatted message template. You must then edit the payload of the message for your test.
2. If you are using GENERIC_XML, create an XML file that contains the GENERIC_XML representation of the event.
3. If you are using JSON, create a JSON file that contains the JSON representation of the event.
  For more information, see JSON mapping.
Use an HTTP client to POST the contents of the file to the appropriate URL. The POST request must include a Content-Type header that specifies application/xml or application/json.

For the HTTP gateway, the URL depends on your server configuration and solution name. The URL is of the form: https://host:port/ibm/ia/gateway/solution_name
For example:
```
https://localhost:9443/ibm/ia/gateway/fraudSolution
```
Note: For an inbound HTTP endpoint, the URL depends on your server configuration and the path that is specified in the inbound HTTP endpoint definition.

After you POST your XML or JSON message, you get a JSON response with a routing status. For more information, see HTTP protocol.

Results

After you submit the events, you can use the administrator tools to validate the arrival of the events and the creation of the entities. The REST API for example, is a quick way to validate that entities are inserted into the grid. You can enter REST URLs in the address field of your browser to access the stored solutions and entities in the server.

What to do next

You can test events in a development environment by quickly sending in events. When you are ready to move on to system tests, staging, or production, add a connectivity definition for the inbound HTTP endpoint to your solution to use endpoint-specific, role-based security, transformations, and performance monitoring.