CFML event gateway SendGatewayMessage data parameter

The ColdFusion CFML gateway type enables you to invoke CFC methods asynchronously. The structure that you use in the SendGatewayMessage function data parameter can include two types of fields:

  • Any number of fields can contain arbitrary contents for use in by the CFC.

  • Several optional fields can configure how the gateway delivers the information to the CFC.

    The CFML gateway looks for the following optional fields, and, if they exist, uses them to determine how it delivers the message. Do not use these field names for data that you send to your CFC method.

    Field

    Use

    cfcpath

    Overrides the CFC path specified in the ColdFusion Administrator. This field lets you use a single gateway configuration in the ColdFusion Administrator multiple CFCs. This field sets the CFEvent object CFCPath variable.

    method

    Specifies the name of the method to invoke in the CFC. The default method is onIncomingMessage. This field lets you use a single gateway configuration in the ColdFusion Administrator for a CFC that has several methods. This field sets the CFEvent object CFCMethod variable.

    originatorID

    Sets the originatorID field of the CFEvent object that ColdFusion delivers to the CFC. The default value is CFMLGateway.

    timeout

    Sets the time-out, in seconds, during which the listener CFC must process the event request and return before ColdFusion gateway services terminates the request. The default value is the Timeout Request value set on the Server Settings page in the ColdFusion Administrator. Set this value if a request might validly take longer to process than the default time-out; for example, if the request involves a long processing time. This field sets the CFEvent object CFCTimeout variable.

Example

The following example consists of a CFML page that sends a message to a logevent method in the file logger.CFC. The CFML page specifies the CFC and method to call, and sets the OriginatorID. 

<h3>Sending an event using a generic CFML event gateway and specifying the CFC and method.</h3> 
<cfscript> 
    status = False; 
    props = structNew(); 
    props.cfcpath="C:\CFusionMX7\gateway\cfc\MyCFCs\logger.cfc"; 
    props.method="logEvent"; 
    props.OriginatorID=CGI.SCRIPT_NAME; 
    props.Message="Replace me with a variable with data to log"; 
    props.file="GenericCFCtest"; 
    props.type="warning"; 
    status = SendGatewayMessage("DefaultCFC", props); 
    if (status IS True)  
        WriteOutput('Event Message "#props.Message#" has been sent.'); 
</cfscript>

The CFC method uses the OriginatorID and the message, file, and type fields of the CFEvent parameter’s data field to specify the log file and message.

<cfcomponent> 
    <cffunction name="logEvent" output="no"> 
        <cfargument name="CFEvent" type="struct" required="yes"> 
         <cfscript> 
            if (NOT IsDefined("CFEvent.Data.file")) { 
                CFEvent.Data.file="defaultEventLog"; } 
            if (NOT IsDefined("CFEvent.Data.type")) { 
                CFEvent.Data.type="information"; } 
        </cfscript> 
        <cflog text="Message from #CFEvent.originatorID#: #CFEvent.Data.message#" 
            file="#CFEvent.data.file#" type="#CFEvent.Data.type#" > 
    </cffunction> 
</cfcomponent>