Sending events to correlators

Dashboard Builder supports the creation of dashboard commands that send user-defined events.

Using the Define Apama Command dialog

You define a send-event command by associating it with the command, actionCommand, or commandString property of a Dashboard object such as a button.

To make the association

  1. Select the Dashboard object.

  2. Right-click the actionCommand or commandString property in the Object Properties panel.

  3. Select Define Command > Apama from the popup menu.

  4. In the Define Apama Command dialog

    1. Command. Select Send event from the command drop down list.

    2. Correlator. The correlator where the command is to be run.

    3. Package. The choices for the Package field include all the packages for the selected correlator. Events that do not have a package are grouped under the package “default”.

    4. Event. The choices for the Event field include all the events for the selected package.

    5. Channel. Optionally, specify a channel on which to send the event. For example, orders. If you do not specify a channel then the default channel is used.

Other dialog fields

The remaining fields shown are dependent on the event selected; one field is shown in the dialog for each field in the event. As with other commands, the value of each event field can be attached to a dashboard variable or set to a hard coded value.

Default values

It is not necessary to set each event field in order to send an event. Empty fields are set to default values depending on field type. See also Default values for types.

Specifying values for reference types

You specify values for reference types (such as location, sequence, dictionary or event) by using the format specified in the API reference for EPL (ApamaDoc). For example, to specify extraParams you can specify the value as follows:

{"field1":"value1","field2":"value2"}

You can also use dashboard variables, or a single dashboard variable that contains the entire value, for example:

$extraParams

where $extraParams equals {"field1":"value1","field2":"value2"}.

Event fields of type optional are empty by default. If you want to specify a value, make sure to specify the value as shown in the following examples:

  • optional(123.45) for float values.
  • optional("hello world") for string values.

Updating event definitions in Builder

The Dashboard Builder retrieves the latest event definitions from each correlator at startup. If the event definitions change, you can force them to be refreshed by using the Refresh Event Definitions button at the bottom of theDefine Apama Commanddialog.

Note that the Refresh Event Definition button only updates the event definitions for the selected correlator.

Send event authorization

By default, any user is authorized to send any event. However you can create a custom event authority that determines whether a given user is authorized to send a given event. An event authority is a Java class that implements the canSend method of the interface com.apama.dashboard.security.IEventAuthority:

boolean canSend (IUserCredentials credentials, Event event);

If canSend() returns true the user is allowed to send the event. If it returns false the user is not allowed to send the event and the attempt to send the event is treated as a command failure. Dashboard object property settings determine if this error is displayed to the user.

The event authority is specified in the EXTENSIONS.ini file in the lib directory of your Apama installation. Here is a portion of EXTENSIONS.ini as shipped:

### List of event authorities. An event authority is called to determine
### if a user has rights to send an event to a correlator. Each must implement
### the interface:
### 		com.apama.dashboard.security.IEventAuthority
### Multiple authorities can be specified. They will be called in the order
### listed.
### Format:
###		eventAuthority <classname>
### NoOpEventAuthority - Allows all users to send events
eventAuthority com.apama.dashboard.security.NoOpEventAuthority
### DenyAllEventAuthority - Allows no users to send events
###eventAuthority com.apama.dashboard.security.DenyAllEventAuthority
### eventAuthority <your_class_name_here>

Two event authorities are provided with your installation:

  • com.apama.dashboard.security.NoOpEventAuthority: Permits all users to send any event.
  • com.apama.dashboard.security.DenyAllEventAuthority: Denies all users rights to send any event.

NoOpEventAuthority is the default event authority. Use a custom event authority when deploying your Dashboards.

See Deploying and Managing Apama for more information on customizing authorization.