Adding custom event codes

You can add custom events to Sterling File Gateway that are associated with any custom protocols and business processes you create. You will need a code, a name, and a description for each event you want to create, as well as permission and subscription settings.

1. Open or create a file named /<install_dir>/properties/customer_overrides.properties.
2. Add entries in the customer_overrides.properties file with the appropriate details about the custom event codes you are creating. Your new event will be a series of properties describing attributes of the event. See the filegateway_eventcodes.properties file for examples. Do not edit the filegateway_eventcodes.properties file. Use the example as a model:

   filegateway_eventcodes.CUST_0265.name=
   filegateway_eventcodes.CUST_0265.displayName=
   filegateway_eventcodes.CUST_0265.attributes=
   filegateway_eventcodes.CUST_0265.text=
   filegateway_eventcodes.CUST_0265.description=
   filegateway_eventcodes.CUST_0265.permissions=
   

   • Event Code: The event code in the example above is CUST_0265. It consists of keyword underscore 4-digit code. It is used to identify all the attributes for a particular event code. Required.
     • Keyword - any text, optimally 4 characters long, but cannot be FG_ nor AFT_. In the example, the keyword is CUST.
     • 4-digit Code - consists of two 2-digit codes - a category identifier and a unique identifier. No two events can have the same 4-digit code.
       • Category Identifier - The first 2-digit code is a category identifier. You can use a system-defined category or create your own 2-digit code to categorize your codes in a way that is convenient for you. In the example, the category identifier is 02. The following are the system-defined category codes:

         Code	Category
         00	Producer File Transfer
         02	Routing Business Process
         04	File Gateway General
         05	Route Plan Determination
         06	File Transformation
         07	Consumer File Transfer

       • Unique Identifier - The second 2-digit code is the unique identifier for the event within the category. 00 to 49 are successful events and 50 to 99 are error events. Error events display in red in Sterling File Gateway. You cannot exceed 99 event codes in a category. In the example, the unique identifier is 65.
   • <EventCode>.name - This is the name of your event. Required.
   • <EventCode>.displayName - This is the long form of the <EventCode>.Name of your event. It will be shown in the subscription UI (Profile > Notifications) if subscriptions are enabled, and in the log.
   • <EventCode>.attributes - A comma-delimited list of attributes for this event. While any attribute can be passed into the event, only these attributes will be stored in the database, will be searchable through the UI, and are usable in the event text defined below. They are generally indexed with the first one in the list having an index of 0. The attribute names must be names that can be passed as an xml element (no special characters, no spaces). This property is required but the list can be empty.
   • <EventCode>.text - This property contains the text that will show up in the UI when this event is viewed. It can contain text and is generally limited by the Java™ Format rules (for example, in order to have a single quote, you must put two of them right next to each other.) You can also use attributes above by using the notation {#} which will substitute in the UI the value of the attribute at the index of the #. You do not have to use attributes, the user in the UI can click on the event and see all the attributes and they will still be searchable. So you can send in and store more attributes than you might want to show in the UI. Required.
   • <EventCode>.description - This description is shown in the subscription UI (Profile > Notifications). Required.
   • <EventCode>.permissions - This is a comma-delimited list of permissions for this event. There are three possible values to use: producer, consumer, subscription. This property is required but it can be empty. Empty means that only the Operator can see the event, and no one can subscribe for notifications to the event.
     • producer - This event can be seen and subscribed to by the producer for this route.
     • consumer - This event can be seen and subscribed to by the consumer for this route.
     • subscription - This event can be subscribed to. For a producer or consumer to subscribe to an event, the event must have the corresponding producer or consumer permission AND the subscription permission. For a Operator to subscribe to an event, the event requires only to have the subscription permission.
   • EventNotificationEmailSubject - This is the subject line for the email notifications when events occurs. This applies to all event codes for your system. The default value is File Gateway Routing Event E-mail Notification [Event Code = {0}], where 0 is the four-digit identifier for the event code.
   • EventNotificationEmailContentType - This specifies the content type for the email notification when the event occurs. This applies to all event codes for your system. Valid values are text/plain and html. The default is text/plain.
   Fast path: See the /<install_dir>/properties/filegateway_eventcodes.properties file as an example for how to structure your event properties. Do not edit the filegateway_eventcodes.properties file.
3. Save the customer_overrides.properties file and restart Sterling File Gateway for the new file to take effect.
4. Edit your business process that generates the new event codes to call the FileGatewayRouteEventService, with the proper parameters, including the new custom event codes.
5. Add the FileGatewayRouteEventService, with the proper parameters, including the new custom event code. The following example will fire a hypothetical event:

   	<operation>
       <participant name=" FileGatewayRouteEventService "/>
       <output message="Output">
         <assign to="EventCode">CUST_0265</assign>
         <assign to="ExceptionLevel">Normal</assign>
         <assign to="EventAttributes/Directory" 
          from="directory/text()" append="true"/>
         <assign to="EventAttributes/Comment" >
          BP changed directories</assign>
         <assign to="." from="*"></assign>
       </output>
       <input message="Input">
         <assign to="." from="*"></assign>
       </input>
     </operation>
   

   To send attributes to the FileGatewayRouteEventService, use the following guidelines. These guidelines only apply to the EventAttributes, not to other parameters of the service:

   • The attributes will be sent to the service as a series of assigns. They need to be a series of assigns in order to support the advanced event attribute naming of Sterling File Gateway.
   • The first assign must have an attribute append=”true”. This will append the EventAttributes the first time. The remaining assigns cannot have the append attribute.
     • Hardcoded Values. If you want to send a hardcoded attribute value to the service (for example, IsError=true, when you know it will be true every time) then use the following assign statement template:

       <assign to=”EventAttributes/IsError” 
         from=”string(‘true')” />
       

     • Process Data. If you want to send an attribute that is copied from another attribute in the service (for example, the results of another service, stored in the ProcessData at MyService/ResultCode) then use the following assign statement template:

       <assign to=”EventAttributes/MyServiceResultCode” 
         from=”MyService/ResultCode/text()” />
       

   You can combine those two methods to send both types of attributes into the service, adding the append to the first one:

   <assign to=”EventAttributes/IsError” 
     from=”string(‘true')” append=”true” />
   <assign to=”EventAttributes/MyServiceResultCode” 
     from=”MyService/ResultCode/text()” />
   

filegateway_eventcodes.CUST_0265.name=Custom Event - File Error
filegateway_eventcodes.CUST_0265.attributes=ConsumerName,MyServiceResultCode,
                                            IDNumber
filegateway_eventcodes.CUST_0265.text=File Error generated during processing:
	Result code: {1} reported for File ID {2} received for Consumer {0}
filegateway_eventcodes.CUST_0265.description=Event from Custom BP generated 
	when error occurs
filegateway_eventcodes.CUST_0265.permissions=producer,consumer,subscription