The Sampro Registry entry ‘sys-FMMS’ must be present in order to enable the FMMS system. It can be temporarily disabled by adding a Setting Key: Enabled Setting Value: No line. Changing the Value to Yes will re-enable the FMMS system.
See Registry Service Channel PIN for details on setting the registry entries needed to support multi-company certificates for uploaded invoices.
Id: sys-fmms-vendor-ServiceChannel
Configuration settings for the ServiceChannel FMMS system are stored in the ‘sys-FMMS-vendor-ServiceChannel’ entry of the SAMPro Registry.
This release supports a registry to enable enhanced processing to support sales tax for Canadian Service Channel invoicing. The GST will be reported in the 'invoiceTax' column while other taxes are to be reported in the 'tax2' and 'tax2Name' columns. The Sales Tax Authority's 'Tax Code From State' field is used to identify the appropriate tax category to be reported for an invoiced tax amount. This should contain one of the following values: 'GST', 'PST', 'HST', or 'QST'.
The following Service Channel Registry entry is required to turn on Canadian Tax reporting
Id: sys-fmms-vendor-ServiceChannel
Setting Key: InvoiceIsCanadian Setting Value: yes (or begins with 'y', 'Y', 't', 'or T')
Note that the Tax Authority Tax Code From State field has been relaxed to allow values that are longer than 2 characters.
Setting Key: InvoiceTemplate Setting Value: I.14
Setting Key: InvoiceIsDetailed Setting Value: Y (or y, T or t)
Note:
The Service Channel i.14 invoice template requires that materials are used to complete the job; ServiceChannel will reject the invoice if it doesn't contain material information. Since all jobs do not require materials, this release will add a dummy $0 material line to get around this requirement. The Material Description of 'No Material Required' will be used on the $0 line to conform to ServiceChannel requirements.
Version 9.1 expands the support of optional detail lines on Service Channel Invoice I.14 to Other Labor lines.
When SAMPro detects certain Status changes to a Work Order, it sends ServiceChannel a CALL XML message that includes TR_NUM and the new ServiceChannel STATUS code. When entering certain Status values, ServiceChannel would like us to include a CHECK element within the CALL XML. The CHECK element includes a TYPE code which corresponds to the new Status Code.
Registry Id: sys-FMMS-Vendor-ServiceChannel
Setting Key: CheckTypeForServiceChannelStatus
Setting Value: ServiceChannelStatusCode:CorrespondingCHECKTypeCode
1. There may be multiple Registry lines with the ‘CheckTypeForServiceChannelStatus’ key.
2. Each line may consist of multiple mappings with individual mappings separated by a ‘,’ character.
3. The Valid CHECK Type Codes are: IN, OUT, DISP, and CLOSE
Example:
Setting Key: CheckTypeForServiceChannelStatus
Setting Value: ON_SITE:IN, COMPLETED:OUT
4. If a mapping is not found (or evaluates to ‘N/A’), no CHECK element will be included in the CALL XML.
5. There being several ServiceChannel Status Codes beginning with ‘COMPLETED’ , a special ‘short cut’ is available for those Status Codes: If no mapping is found (or if an ‘N/A’ mapping is found) for a Status Code and the Status Code begins with ‘COMPLETED’, Sampro will try to identify and use a mapping for the ‘COMPLETED’ status code.
Check elements include an ‘ID’ attribute that ServiceChannel uses to internally sequence Check Ins and Check Outs. The restrictions are:
1. Each Check In process should be identified by an ID attribute value greater in value than that used in any prior Check In processes.
2. Each Check Out process should be identified by an ID attribute that matches that used in the corresponding Check In process.
In order to implement this sequencing, Sampro must somewhere retain the appropriate Check Sequencing information. This has been implemented as follows:
1. Sequencing information will be retained on one of the Work Order’s User Fields.
2. The User Field to be used will be identified in the following registry entry by the line having the key ‘. The value of this key should be a number between 1 and 5 inclusive.
Registry Id: sys-FMMS-Vendor-ServiceChannel
Setting Key: WOUserFieldNumberForCheckInCheckOut
Setting Value: a number between 1 and 5 inclusive.
3. The chosen User Field in the Work Order should be customized to ‘SC In/Out Count:’.
4. If no ‘WOUserFieldNumberForCheckInCheckOut’ key is found, the value of the next rn will be used for the ID attribute. This will not result in proper sequencing.
5. The format of the In/Out Count field will be of the form ‘inCount/OutCount’.
Example: ‘2/1’ meaning there have been 2 CHECK INs but only 1 CHECK Out.
6. A blank value of the in/Out Count Field will be treated as ’0/0’ so there is no need to initialize this field.
7. Whenever SAMPro sends a CHECK IN, it will increment the Work Order’s inCount; whenever Sampro sends a CHECK OUT, it will increment the Work Order’s outCount.
8. Whenever SAMPro sends either a CHECK IN or a CHECK OUT, it will use the value of the Work Order’s inCount for the ID value, ignoring the outCount. Thus a CHECK IN can have multiple CHECK OUTs. Note that because of this, the outCount is actually irrelevant in this processing and is maintained only for informational purposes.
Caution:
Note that this feature should only be used for customers not using ServiceChannel’s IVR check-in/check-out system. It is not clear at this time what will happen if, for example, a Check-Out is sent to ServiceChannel as a response to SAMPro processing a Check-Out message sent by ServiceChannel itself.
When New Call creates a new Workorder based on a Service Request from ServiceChannel (via the Weblog), it must send ServiceChannel a message that the Service Request has been accepted. This message includes a Scheduled Date and a Scheduled Time.
Normally the Scheduled Date and Scheduled Time are derived from the Workorder being created. The following registry may be implemented to derive the Scheduled Date and Scheduled Time are from data in the original Service Request that was sent by ServiceChannel.
Id: sys-fmms-vendor-servicechannel
Setting Key: SchedDateTimeSourceWhenAcceptingWO
Setting Value: ServiceRequest or WorkOrder (default)
If the key is missing or the value is other than 'ServiceRequest' (case insensitive), a value of 'WorkOrder' will be assumed.
If the Setting Value is 'ServiceRequest', then the Scheduled Date and Scheduled Time will be taken from the original Service Request issued by ServiceChannel. If the value is 'WorkOrder', the Scheduled Date and Scheduled Time will be taken from the Workorder being created.
Setting Key: Enabled Setting Value: Yes
This acts like the ‘sys-FMMS’ enabled flag but is used specifically for the ServiceChannel Data Bridge (as opposed to all FMMS activity).
InboundDocumentSourceFolder which identifies the folder in which the web server (described below) drops new Service Requests.
InboundDocumentArchiveFolder and InboundDocumentRejectFolder which identify the folders in which new Service Requests are moved after being processed.
WebserverPort identifies the port on which the Sampro HTTPServer (described below) listens for new Service Requests. This defaults to 9999 if not specified.
ServiceChannelUrl which identifies the URL to which messages to ServiceChannel are to be sent.
ServiceChannelUri which identifies the uri of the Web Service at ServiceChannel
CustomerId, StoreId, and Pin which identify the service provider to Service Channel
LogMode. When set to ‘on’ instructs the FMMS system write events to the file identified by the LogPath
LogPath identifies the full path name of the file to be used for the FMMS log.
Email entries are used when Sampro emails invoice spreadsheets (as attachments) to ServiceChannel. These entries include:
emailSavePath identifies a folder into which invoice spread sheets will be saved.
emailFrom identifies the ’From’ line to be used in the emails.
emailTo identifies the ‘To’ line to be used in the emails.
emailSubject identifies the ‘Subject’ line to be used in the emails.
emailMessage identifies the contents of the message to be used in the emails.
emailRetainDays identifies the number of days an invoice spread sheet will be retained in the emailSavePath folder before being automatically removed. This defaults to 7 if not specified.
statusMappings settings are used to map SAMPro Escalation Status values to ServiceChannel status values. A typical entry would be of the form
Setting Key: statusMappings Setting Value: Acknowledged:DISPATCH CONFIRMED
A comma-delimited list of multiple mappings may be contained on one line as per:
Setting Key: statusMappings Setting Value: a:AAA, b:BBB
This release adds the flexibility to map SAMPro log status’ to Service Channel log status’ based on registry set values keyed by Client Id (derived from the Job in the WO header).
Normally, SAMPro Workorder status codes are mapped to ServiceChannel status codes via the ‘StatusMappings’ lines found in the SAMPro ServiceChannel Registry entry; they will be used for all Service Channel Clients. However, various ServiceChannel clients may have differing status code mappings. This release extends the SAMPro Registry to allow multiple status mapping sets based on the Workorder's Client Id (derived from the Job in the WO header).
To create a set of Status Mappings in the SAMPro sys-fmms-vendor-ServiceChannel Registry for a specific Client, append a '-' and the Client Id to the 'StatusMappings' key.
Example:
Id: sys-fmms-vendor-ServiceChannel
Setting Key: StatusMappings-Wendys
Setting Value: Acknowledged:DISPATCH CONFIRMED
Tip:
Make sure that a StatusMappings option without the Client Id appended is retained for general use.
Sampro QuoteMaster Cost Category settings. These identify which QuoteMaster Other tab Cost Categories will be converted to Tax and Freight values in an uploaded ServiceChannel Proposal.
ProposalOtherCostCategoryForTax
ProposalOtherCostCategoryForFreight
Invoices are uploaded to ServiceChannel by sending them an email with an attached spreadsheet. For each work order, the spreadsheet includes a userId and a password. The userId and password are derived from the Sampro Registry sys-fmms-vendor-servicechannel.
Setting Key: InvoiceUID Setting Value: User Id provided by Service Channel
Setting Key: InvoicePIN Setting Value: IVRPINNumber
The value of this setting should the IVR PIN Number used by your company.
Id: sys-fmms-vendor-ServiceChannel
Setting Key: IncludeMustCompleteDateInNewWorkOrder Setting Value: Y
When this registry is enabled, when a Work Order is generated from Service Channel, the ServiceChannel SCHED_DATETIME will be copied to the Work Orders' Date and Time Must Complete fields.
ServiceChannel provides an IVR facility that allows techs to phone into them with a change to a Workorder's status. This change is then forwarded to SAMPro for posting to the SAMPro Workorder. Sometimes it becomes necessary (for ServiceChannel internal reasons) for a tech to make such a IVR entry for a Workorder that has a 'finished' status (e.g. 'billed') within SAMPro. In this release, we prohibit SAMPro from updating a Workorder's status in response to such an inbound IVR status change message for ‘Cancelled’ and ‘Billed’ Work Orders. Note that the Work Order’s current status is derived from the wrkordrlgtype_id on the first line of the Workorder’s Technicians tab.
This functionality may adjusted via registry.
Id: sys-fmms-vendor-ServiceChannel
Setting Key: StatusUpdateIsProhibitedForStatusCodes Setting Value: listofstatuscodes
The Setting Value is a list of status codes separated commas. The codes ‘Cancelled’ and ‘Billed’ are always automatically added to the list. If no entry is found, the list will consist solely of these two entries.
Id: sys-fmms-vendor-ServiceChannel
Setting Key: UploadEquipmentWorkPerformedNotes
Setting Value: Y
Note that values of Y, y, T, or t enable this mod; the default is that this mod is not enabled. When this option is enabled, Work Order's Work Performed is now sent as Notes to ServiceChannel whenever a Status update is sent.
A Work Order Note is sent to ServiceChannel for each Equipment line in the Work Order.
The Note includes the contents of the Work Order Equipment Work Performed field.
Each note is prefixed with the Equipment Id, Manufacturer, Model, and Serial Number.
If this option is not enabled, the Work Performed will be included in a <RESOL> sub-element of the <CALL> element when a status change is sent.
Note: see the following registry to refine the upload setting.
The previous registry enables a feature that sends a Work Order Note to ServiceChannel for each equipment line on a work order. This registry allows the upload feature to be disabled for specified Equipment Ids. This new registry option may be used to refine which Equipment Id's have their Work Performed uploaded to ServiceChannel. The value of this key is a comma separated list of Equipment Ids to be excluded from the Note sending operation.
Id: sys-fmms-vendor-ServiceChannel
Setting Key: UploadEquipmentWorkPerformedNotesExceptEquipment
Setting Value: Id1,Id2,...
Setting Key: UploadEquipmentWorkPerformedNotes
Setting Value: Y (note that this setting is also required)
The following example would prevent the sending of Work Order Notes for Client Site Equipment Id 'RTU2', but allow that for all other Equipment Id's to be sent.
Setting Key: UploadEquipmentWorkPerformedNotesExceptEquipment
Setting Value: RTU2
This registry provides a Registry-specified delay between the posting of the Status change and the sending of the Equipment Work Performed notes. The assumption is that by providing a sufficient delay, TechAnywhere will have uploaded the required Equipment information before the delay expires.
Id: sys-fmms-vendor-ServiceChannel
Setting Key: EquipmentWorkPerformedDelaySeconds Setting Value: delay in seconds
Example: The following will delay the sending of the Equipment Work Performed message for 30 minutes following the status change. The default delay is zero seconds.
Setting Key: EquipmentWorkPerformedDelaySeconds Setting Value: 1800
T
SAMPro supports the following charges to be broken out on the ServiceChannel Invoice Spreadsheet: Trip Charge, Material Total, Freight Charge, Markup. Previously, the Trip Charge and the Freight Charge were included in the Material Total. In addition, a separate Markup charge was not reported on the Invoice.
There are separate columns on the spreadsheet for Trip Charge, Material Total, and Freight Charge. The Markup amount is to be reported in the Other Charges columns.
Charges from the Work Order’s Other tab that are not identified as a Freight Charge or a Trip Charge will be included in the ‘Other Charges’ column.
If there is exactly one ‘Other Charge’, the Other Rate’s Description will appear in the ‘Other Charges Description’ column.
If there is more than one ‘Other Charge’, the word ‘Various’ will appear in the ‘Other Charges Description’ column.
The following registry entries are required to implement these enhancements:
Setting Key: OtherCodesFreight
Setting Value: A comma separated list of Other Rate Ids identifying Freight Charges.
Setting Key: OtherCodesTravel
Setting Value: A comma separated list of Other Rate Ids identifying trip charges.
In SAM Pro invoices, the description of the ‘other’ charges comes from the Other Rate Description. However, ServiceChannel now only allows the following valid Other Charge Descriptions:
Discount
Management Fee
Markup
Overhead & Profit
Rental Fee
Shipping & Handling
Subcontractor Cost
To ensure that the ServiceChannel invoice conforms to this standard, the following registry should be implemented to statically set the description:
Setting Key: OtherChargesDescription Setting Value: valid description
If this entry is not found the description 'Not Found In Sampro Registry' will be used. Anytime a ServiceChannel invoice is generated and contains a dollar amount in the Other Charges Total section, it will need to use what is specified in the registry.
This enhancement to Service Channel integration allows users to break out their Labor (Other Rate) subcontracting charges into the 'Labor Total' section of the ServiceChannel invoice format as well as for the tax that they pass on to the customer as an Other Rate to display in the 'Invoice Tax' section of the Service Channel invoice format.
Setting Key: OtherCodesLabor Setting Value: list of other rates for labor
Setting Key: OtherCodesTax Setting Value: list of other rates for tax
This release supports multiple lines for the same group of Other Codes (e.g. OtherCodesLabor). This is in case there are too many cpdes (e.g. OtherCodesLabor codes) to fit on a single line in the registry entry.
This enhancement extends SAMPro’s ServiceChannel Data Bridge to provide for the use of the ServiceChannel IVR service for Work Orders not originating as ServiceChannel New Service Requests. A registry (see below) is required to enable this functionality.
When a Work Order is created in SAM Pro via New Call, Create PM Work Order, Create PM Billing, or Create Rental Billing, a New Work Order XML message (as per ServiceChannel specs) for transmission to ServiceChannel. In the New Call case, however, this process will be omitted if the Work Order was created as the result of the pulling of a ServiceChannel New Service Request from SAMPro’s weblog.
The queueing of the New Work Order XML will take place regardless of whether the Client is or is not a “Mutual” Authority/ServiceChannel client. The contents of the New Work Order XML message will be derived from the contents of the SAMPro Work Order and the appropriate entries in the following Registry.
Registry Id: sys-FMMS-Vendor-ServiceChannel
Setting Key: NewWOToServiceChannelEnabled Setting Value: True
This registry option is required to enable this feature. Set its value to ‘Yes’ or ‘True’ to turn this feature on. Actually, any value beginning with ‘Y’, ‘y’, ‘T’, or ‘t’ will enable this feature.
Setting Key: NewWOToServiceChannelDefaults
Setting Value: LOC:multi, SUB:#fromSC, PRIORITY:NORMAL, PRICE:0.00, NTE:0.00, STATUS:OPEN, CURRENCY:USD, TRADE:HVAC, OPERATOR:namefromSC, CATEGORY:Repair
This registry sets the default values of certain attributes for the generated New Work Order. Note that these all appear on one registry line. The format of the line is a collection of comma separated key/Value pairs with the keys separated from the values by a colon.
Check with ServiceChannel for the correct values for the LOC, SUB, TRADE, OPERATOR, and CATEGORY keys as these may vary from installation to installation.
A conflict exists with PM Work Order if the above registry option is enabled. This is because ServiceChannel creates their own PM Work Orders sends them to SAMPro as New Dispatches. If the SAMPro 'Start Create PM WorkOrders' is also used to create PM Work Orders, this results in duplicated PM Work Orders and much confusion takes place. Contact Support for a registry entry and procedures to resolve this condition.
Identifying CVS Clients
A Sampro user could potentially have ServiceChannel arrangements for a mixture of CVS and Generic clients. It is assumed that such a user would also produce a uniquely formatted paper invoice format for CVS. Within Sampro, the appropriate invoice format is identified by the Report Query Id found in the appropriate Job Billing Item record.
Setting Key: ReportQueriesForMarkupMode
Setting Value: A comma separated list of Report Query Ids
These Report Query Ids will identify clients (via their Billing Items) requiring special CVS formatted ServiceChannel invoice spreadsheet lines.
For CVS type clients
Charges will appear in the ‘Freight Charges’ and ‘Trip Charge’ columns as determined by the same mechanism used by the ‘Generic’ type clients.
Charges that would (for ‘Generic type Clients) be included in the ‘Other Charges’ column will now appear in the ‘Material Total’ column. This will free up the ‘Other Charges’ column to be used for Markup.
Charges appearing in the ‘Material Total’ column will have to be classified as either being ‘Marked Up’ or as ‘Flat Rate’. This will be done by examining the charge’s ‘Billing Rate Type’. Charges from the Work Other’s ‘Other’ Tab will be considered as ‘Marked Up’ if and only if the Billing Rate Type is set to one of the ‘markup’ types of markup, margin or multiplier. Charges from the Work Order’s ‘Inventory’ Tab will always be considered as ‘Marked Up’.
If a charge is considered as ‘Marked Up’, the ‘Markup Amount’ will be included in the ‘Other Charges’ column but not in the ‘Material Total’ column.
If it is determined that the ‘Other Charges’ column will be non-zero, the ‘Other Charges Description’ column will be set to ‘Markup’. Otherwise it will be left blank.
The following registry may be used to disable sending public notes to ServiceChannel; it would typically be enabled to prevent TechAnywhere created notes from being sent. Since there is not a way to determine if the note came from TechAnywhere or not, the only suitable solution is to create a registry setting that will disable this FMMS functionality.
Registry Id: sys-fmms-vendor-servicechannel
(Or sys-fmms-vendorservicechannel--agenttech which will disable this function only for the techanywhere event manager)
Setting Key: UploadNotes Setting Value: N
Registry Id: sys-FMMS-Vendor-ServiceChannel
Setting Key: IncludeScheduledDateInNewWorkOrder Setting Value: No (default Yes)
When New Call accepts a new Service Request via the weblog, the scheduled and time will be omitted if this option is set to 'No'.
Registry Id: sys-FMMS-Vendor-ServiceChannel
Setting Key: PriorityToWorkCodeMappings Setting Value: PriorityCode:WorkCodeId
When enabled, this registry automatically sets the Work Code Id to a value derived from the Service Request's PRIORITY attribute.
This option specifies how the Service Channel Priority Codes map to the SAMPro Work Code Id's when a Work Order is created from a Service Channel . It supports multiple lines so that all ServiceChannel Priority Codes may be properly mapped.
Example: The following option maps the ServiceChannel 'Emergency' Priority Code to the SAMPro Work Code Id 'Safety'.
Setting Key: PriorityToWorkCodeMappings: Setting Value: Emergency:Safety
When enabled, this registry will automatically select the Client Site Equipment based on the contents of the Service Request's TRADE attribute. It supports multiple lines so that all ServiceChannel Trades may be properly mapped.
Registry Id: sys-FMMS-Vendor-ServiceChannel
Setting Key: TradeToEquipmentMappings Setting Value: TradeCode:EquipmentId
This registry disables sending ETA changes to ServiceChannel when a Sampro Work Order's ETA changes.
Id: sys-fmms-vendor-ServiceChannel / sys-fmms-vendor-FacilitySource / sys-fmms-vendor-Corrigo
Setting Key: UploadWorkorderETAChanges Setting Value: No (default is Yes)
Note this setting is applicable to all FMMS Subsystems (e.g. Corrigo, FacilitySource). Any value beginning with 'Y', 'y', 'T', or 't' is equivalent to 'Yes' and any other value is equivalent to 'No'. The absence of the Registry entry is equivalent to a 'Yes' value. So there will be no change in functionality if the Registry entry is not found.
This registry may be used to disable the updating a Sampro Work Order's status based on IVR Check-In and Check-Out messages received from ServiceChannel.
Id: sys-fmms-vendor-ServiceChannel
Setting Key: PostIncomingStatusUpdates Setting Value: No (default is Yes)
Any value beginning with 'Y', 'y', 'T', or 't' is equivalent to 'Yes' and any other value is equivalent to 'No'. The absence of the Registry entry is equivalent to a 'Yes' value. So there will be no change in functionality if the Registry entry is not found.