The ServiceChannelHelper class is used to implement the client side of the Service Channel FMMS system. It provides facilities for
The posting logic for inbound messages.
Various helper methods.
Contact your Data-Basics Support Representative for current installation instructions.
See Registry Service Channel (sys-FMMS) for the registry settings required to support the Service Channel data bridge.
How Messages are Received by Sampro from ServiceChannel
ServiceChannel uses HTTP GET messages to send Service Request messages to its subscribers. This means that Sampro customers will need to provide some type of Web Server in order to receive these messages. Sampro includes an HTTPServer class which is used for this purpose.
The body of the GET message sent by ServiceChannel contains an XML encoded Service Request. Sampro needs to parse the Service Request and makes appropriate entries to the wblg table where it will be picked up via New Call.
The Sampro HTTPServer class is used to listen for new Service Requests and to save them in a file system folder. Here’s how it works:
The method FMMSServiceChannelHelper class>>startWebServer instantiates a HTTPServer instance and starts it listening on the port indicated in the sys-FMMS-Vendor-ServiceChannel registry entry. Port 9999 is used if this entry cannot be found.
When it receives a GET request, it extracts the query path (which should be ‘/FMMSServiceChannelHelper/newcall.smi’) from the request. Since the path ends in ‘.smi’, the Web Server considers the path to contain a class name and the name of a class method in that class. Accordingly, the method FMMSServiceChannel class>>newcall: is invoked. The contents of the GET request, encoded as a Dictionary, are passed to the newcall: method.
‘newcall:’ extracts the XML encoded Service Request from the GET message. It then writes the request as a new file in the InboundDocumentSourceFolder identified in the Sampro registry entry. The name of the file containing the Service Request will include the dispatch number (CALL.TR_NUM attribute) (I don’t believe this to be currently true).
Note that it would also be possible to use another web server to accomplish this same task.
What happens to the Service Requests after they have been written to the inbound folder is described in the Processing New Service Requests section below.
How Messages are Transmitted From Sampro to ServiceChannel
Sampro uses HTTP POST messages to send messages to ServiceChannel. The mssge table is used to queue messages to be sent. Periodically, a Sampro function will invoke the method ServiceChannelHelper >>scanSendQueue which will scan the mssge table looking for messages to send to ServiceChannel. It will then use the HTTPClient class to transmit the message. This process is described greater detail in a later section of this document.
Database Tables
ServiceChannelHelper relies on the following Sampro database tables
mssge – Used to queue messages to be sent to ServiceChannel and responses to be posted.
lrgeobjct – Extends mssge when long messages need to be encoded into the mssge table. Probably not required for ServiceChannel version of FMMS.
wblg – Used to store new dispatches for importing into New Call.
fmmsinfo – Contains columns used in joining dispatches, mssge rows, and Sampro Work Orders. This table is used solely so that columns do not have to be added to existing tables (which would be the preferred approach). The fmmsinfo table is discussed in detail in a separate document.
fmmsmppng – Used to map certain FMMS vendor field values to their corresponding Sampro values.
ServiceChannelHelper uses the BusinessObject class and its subclasses for all database access. The following BusinessObject subclasses are implemented:
DB_Message – mssge table
FMMSInfo – fmmsinfo table
FMMSMapping = fmmsmppng table
Weblog = wblg table
Processing New Service Requests (Dispatches)
As described above, the Data-Basics Service Provider will use a Web Server to capture HTTP GET messages send by ServiceChannel. This Web Server will create a new file for each inbound GET message. This file will contain the XML encoded Service Request obtained from the GET message. The identity of the folder into which the file will be written is defined within the Sampro Registry.
Periodically, a scheduled event invokes the method ‘FMMSServiceChannelHelper >> scanInboundFolder’. This method scans the inbound folder looking for new Service Request files. Each of these files contains a single new XML encoded Service Request.
For each request file encountered, the file’s XML content is converted to a Node hierarchy. The method ‘FMMSServiceChannelHelper >> postNewDispatchNode:’ is then used to post the Service Request. The parameter passed to this method is the Node hierarchy representing the request’s CALL element.
If the post is successful, the file is moved to an Archive folder. If the post is unsuccessful, the file is moved to the Reject folder. These folders are identified in the Sampro registry.
The following actions take place for each new Service Request:
A new entry in the wblg table is created. This entry will have a
‘wblg_dte_lggd’ and ‘wblg_tme_lggd’ are set to the current date and time.
‘wblg_wrk_rqstd’ set to the ‘Problem’ field from the message
‘wblg_ack’ set to false.
‘wblg_stts’ set to ‘New’
‘wblg_stts_dscrptn’ set to blank
‘wblg_sbmttd_by’ set to ‘ServiceChannel’
‘wblg_rfrnce_msge_rn’ set to zero.
‘wblg_dte_wrk’ set to the date portion of the ‘DateTime’ field from the CALL’s ‘DATETIME’ attribute
‘wblg_type’ set to ‘Client’
‘wblg_clntste_rn’ set to 0.
A new entry in the fmmsinfo table will be created. This entry will have a
‘wblg_rn’ set to the rn of the weblog created in the prior step.
‘fmmsinfo_txt’ column containing the CALL Node structure represented as an XML string..
‘fmmsinfo_dsptch_id’ set to the value of the CALL’s ‘TR_NUM’ attribute.
‘fmmsinfo_prtcl’ set to ‘ServiceChannel’
‘fmmsinfo_vndr: is set to ‘ServiceChannel’
All other columns will retain their default values.
Note that the ‘wblg_rn’ column of the fmmsinfo table may be used to join the wblg entry to the corresponding fmmsinfo entry. This fact can be used to determine if a wblg entry is an FMMS entry.
New Call Processing
Prior to FMMS, New Call already had a mechanism for picking up new service request from the wblg table. This method has been expanded for FMMS new calls.
Identifying an FMMS Service Request Weblog entry
New Call uses the method weblogIsFromFMMS to determine whether it has to perform special FMMS processing when the Weblog Id field is filled in. An FMMS weblog entry is identified by checking to see if there is an fmmsinfo table row referencing the weblog’s rn.
Processing the selection of an FMMS Weblog entry
When New Call identifies a selected weblog entry as being an FMMS entry, it invokes the method ‘doFMMSWeblogProcessing’. This method checks the FMMS protocol from the fmmsinfo_prtcl column (currently either Officetrax or ServiceChannel) and dispatches processing to a handler method in the subclass of FMMSHelper specific for that protocol. This would be either FMMSServiceChannelHelper or FMMSOfficetraxHelper.
The FMMSServiceChannelHelper handler obtains the fmmsinfo table entry corresponding to the Weblog entry and decodes the XML string obtained from its fmmsinfo_txt column. It uses the resulting Node hierarchy to build the contents of a dialog box it displays to the user. The Dialog gives the user the option to decline the request, to ignore the request, or to proceed with the request.
Declining the Service Request: When the user chooses to decline the request, a list dialog is displayed from which the user can pick the reason for the decline. Choices are 'Location Declined', 'Trade Declined', or 'Time Declined'. New Call then creates a ‘ToSend’ message in the mssge table. The ‘mssge_txt’ column is set to a XML encoded string identifying the following CALL attributes:
TR_NUM
STATUS (Set to the reason of the decline)
Proceeding with the Service Request: If the user chooses to proceed with the request, processing returns to the normal New Call sequence. Before returning, however, a number of New Call fields are preset based on the properties of the Service Request.
The presetting procedure takes prior experience into account via the fmmsmppg tble. For example, when a new Service Request for SUB ‘AAA’ and LOC ‘BBB’ (SUB and LOC are properties of the ServiceChannel CALL element identifying the retailer and a site for the retailer) is received and a prior dispatch for SUB ‘AAA’ and LOC ‘BBB’ resulted in the dispatcher selecting Site Id ‘SSSS’, New Call’s Search Text field will be automatically preset to ‘SSSS’.
Proceeding with a Service Request does not immediately result in the queuing of an Accept message. This will not occur until a New Call actually creates a new Work Order for the Service Request (as described below).
The following actions occur when an FMMS Weblog entry results in the creation of a new Work Order (i.e. when the user selects the Add button on the New Call screen). These actions are implemented by NewCall methods.
‘doFMMSAttachNoteToWorkorder’ attaches a note to the Work Order containing the details of the Service Request. This is the same information as appears in the dialog box described above.
‘doFMMSUpdateFMMSInfo’ updates the fmminfo record for the Service Request with the new Work Order’s wrkordr_rn value. This identifies the Work Order associated with the Service Request.
‘doFMMSUpdateFMMSMappingForServiceChannel’ records any ServiceChannel / Sampro value mappings in the fmmsmppng table.
‘doFMMSQueueAcceptMessageForServiceChannel’ queues an acceptance message by adding a ‘ToSend’ entry to the mssge table. The ‘mssge_txt’ column is set to an XML encoded string identifying the following CALL attributes:
TR_NUM
STATUS (set to 'DISPATCH_CONFIRMED')
WO_NUM (set to the id of the newly created Work Order
'SCHED_DATETIME' (set to the date and time the work is scheduled to be performed.
Uploading Proposals to ServiceChannel
To upload a Proposal to ServiceChannel, create a Sampro Quote referencing the Work Order and press the ‘Upload to ServiceChannel’ button on the Quote’s parent form. If you want to include previously incurred charges on the quote, make sure you enter them on the Work Order before uploading the Quote.
Processing ServiceChannel Generated Check-ins and Check-outs
ServiceChannel provides a mechanism through which a Technician can check in or check out of a Work Order. This is provided by their telephone Interactive Voice Response (IVR) system.
When a Technician checks in or out, ServiceChannel sends an appropriate message to the Data Bridge which then updates the Work Order accordingly.
Notifying ServiceChannel of Work Order Status and ETA Changes
Whenever a Work Order is changed, the method ‘FMMSHelper class>>checkStatusChangeFrom:To:workorderId’ is invoked. Subsequent processing determines if the Work Order’s status has changed and, if so, queues a POST request in the mssge table to notify ServiceChannel of this change.
Whenever a Work Order’s ETA changes, the method ‘FMMSHelper class>> queueChangeETAForWorkorder:eta:’ is invoked. Subsequent processing queues a POST request in the mssge table to notify ServiceChannel of this change.
Notifying ServiceChannel of Generated Invoices
Periodically a function invoking the method ‘FMMSHelper>>queueInvoices’ is run. This method identifies Sampro invoices that have not previously been sent to ServiceChannel. The method ‘FMMSHelper class>> queueAddInvoice:’ is invoked for each such invoice.
The ‘queueAddInvoice:’ method encodes the invoice as a series of comma delimited lines which it forwards to ServiceChannel as an attachment to an email message.
Queuing Outbound HTTP POST Requests
A ‘FMMSServiceChannel>>queueSendRequestForCall:’ method has been created for the purpose of queuing outbound HTTP Post messages based on the CALL XML element. The argument to the method is a Dictionary containing the values of all the attributes for the CALL elements to be included in the outbound CALL message.
This method simply makes an entry in the mssge table including all information necessary to send the request.
The ‘mssge_stts’ column will be set to ‘ToSend
The ‘mssge_txt’ column will be set to XML for the CALL element.
The ‘mssge_type’ column will be set to ‘FMMSServiceChannel’
The ‘mssge_sbmittd_by’ column will be set to ‘FMMS’
The ‘mssge_actn’ column will be set to a ‘Call’
Sending the Queued Outbound HTTP POST Reqeusts
Periodically, a Scheduled Event invokes the FMMSServiceChannelHelper>> scanSendQueue method which scans the mssge table and uses the HTTPClient class to send an appropriate POST message to ServiceChannel. The internet addressing and authentication information for the message is obtained from the Sampro registry. The payload of the post is taken from the mssge record’s mssge_txt column.
Summary of Processing Sequence:
Receiving new Service Reqeusts
A Web Severer which listens for inbound requests on a specific port is started.
ServiceChannel issues a GET request to the port. The query parameter is in the form ‘XMLString=<an XML string>. The XML string encodes a node hierarchy which includes a <CALL> node. The <CALL> node contains the new service request.
The Web Server extracts the XML String and writes it to a file in the Inbound folder identified in the Registry. This task is performed by the ‘newcall:’ method. ‘newcall:’ instructs the Web Server to respond with the simple string ‘1’.
Periodically, a task scans the inbound folder and passes the corresponding <CALL> node hierarchy to FMMSServiceChannelHelper.
The appropriate data is extracted from the hierarchy and written to the Weblog and the FMMSInfo tables
New Call Processing
The user double clicks on the Weblog field and picks an FMMS weblog entry.
The appropriate data is fetched from the Weblog and FMMSInfo tables. It is formatted and displayed for inspection by the dispatcher.
The dispatcher either accepts or declines the service request.
If the user declines the request, a Decline message us queued in the Message table with a status of ‘ToSend’. New Call is then re-initialized.
If the user accepts the request, New Call resumes with certain fields defaulted from the request contents. If the user then continues in New Call and creates a Work Order, an Accept message is queued in the Message Table with a status of ‘ToSend’. New Call is then re-initialized.
Message Queue Processing
New Call queues Accept or Reject message requests in the Message table.
Periodically a task scans the Message table looking for messages to send.
When a message is found, a corresponding POST is constructed and sent to ServiceChannel via an HTTPClient. The HTTP Client is instructed to invoke HTTPResponseReceived: when the response to the message is received.
HTTPResponsedReceived: queues a new message in the mssge table with a status of ‘PostPending’. This message encodes the response received and the rn of the initiating message. The originating message is then stamped with a status of ‘Posted’.
Periodically, a task invokes the ‘FMMSServiceChannelHelper>>scanPostQueue’ method which scans the Message Table looking ‘PostPending’ messages to post. It invokes the method ‘postResponseMessage:’ for each response to post. Currently, ‘postResponseMessage:’ simply marks the message as posted.