|
Configuring MainBoss Service |
This help file applies to an out-of-date version of MainBoss.
The most recent version of MainBoss is MainBoss 4.2.4.
This help file does not exist in MainBoss 4.2.4, but the index for that version can be found here.
< Previous section | Table of Contents | Index | Next section >
The first time you configure MainBoss Service, you create a configuration record by clicking New MainBoss Service Configuration in Administration | MainBoss Service | Configuration. Once you have created an initial configuration, you can edit the configuration by clicking the 
button in the same window.
You can edit the MainBoss Service configuration record on any computer where MainBoss is installed. However, you can only use Configure the Windows Service for MainBoss (in Administration | MainBoss Service) on the computer where MainBoss Service runs.
Permissions for Configuring MainBoss Service: Installing and starting MainBoss Service requires Windows and SQL Server Administration privileges. In many organizations, maintenance personnel will not have such privileges; at the same time, people who do have such privileges may not have much experience with using MainBoss. This can lead to difficulties in configuring the service properly.
To give maintenance personnel as much freedom as possible, MainBoss has a feature that lets you specify configuration information even if you don't have Windows Administration privileges. In particular, if you have the MainBoss Administration security role, you can test a MainBoss Service configuration even if you don't have Windows Administration privileges.
This means that you can set up a configuration, test it, and see if any diagnostic messages result. You can then change the configuration and try again, repeating as often as necessary. Once you have a configuration that doesn't result in diagnostic messages, you can get someone with Windows Administration privileges to start up the real MainBoss Service using your finished configuration.
MainBoss Service MailBox: When you configure MainBoss Service you may specify a mailbox where people can send problem reports. You may also specify how MainBoss Service can send and receive messages from that mailbox.
MainBoss can receive email messages using a variety of techniques; these are variations of the POP3 or IMAP4 protocols.
For more information on SMTP, POP3 and IMAP, see the documentation for your email software.
MainBoss can automatically determine which protocol(s) your email software supports. We recommend that you mark the Automatically Determine option (discussed below). If you do, MainBoss tests for secure (encrypted) techniques first and only chooses plain POP3 or IMAP4 if no other technique works. If you specify a name in "Mailbox Name", MainBoss doesn't try POP3 or any of the related variants, since "Mailbox Name" only applies to IMAP4. (If required, you can force MainBoss to use one of the POP3 variants by clicking the appropriate option button.)
When MainBoss automatically determines which technique(s) your mail software supports, it only checks the default port numbers. If your mail server uses a different port than the default, you must mark a specific connection technique (e.g. POP3S) and you must enter the port number in "Override Default Port".
The window for configuring MainBoss Service contains the following:
Details section: Specifies basic information about MainBoss Service for this organization.
Service Name: Will be the name of the Windows service. This must be different from the names of all other Windows services running on this computer. The name should only consist of alphanumeric characters, with no blanks or punctuation charcters.
By default, "Service Name" is MainBossService. If you have multiple MainBoss databases, each one should have its own MainBoss Service and each should have a unique service name. Once you set the name of a service, it cannot be changed.
Description: Additional information about the configuration record.
Automatically Create Requestors, Automatically Create Requestors From Active Directory, Automatically Create Requestors From Email: When MainBoss Service receives an email message, it checks the address of the message's sender against the list of authorized requestors (Coding Definitions | Requests | Requestors). For each authorized requestor, MainBoss Service checks whether the sender's email address matches the "Email" or "Alternate Email" address in the requestor's contact record (Coding Definitions | Contacts). If the sender's email address matches either recorded address, the sender is accepted as an authorized requestor and the request is accepted.
If the sender's email address does not match any known requestor, you can configure MainBoss Service to attempt to create a new requestor record for the sender. This process is controlled by the three Automatically Create checkboxes. You may checkmark any or all these boxes, or leave them blank; each choice leads to different results.
If you do not checkmark any of the Automatically Create checkboxes, MainBoss Service never creates requestor records. If a request comes in from a non-requestor, it will be rejected. (However, the rejection may not happen immediately—see the description of "Manual Processing Time Allowance" below.) The only way to authorize someone to be a requestor is for a person with appropriate MainBoss security roles to create a requestor record manually.
If you checkmark any or all of the checkboxes, MainBoss Service begins by determining if there is a deleted requestor record for the message's sender. If there is such a record, it will be restored (undeleted) and MainBoss Service will process the email request as if it was sent in from that requestor. Note that this happens no matter which Automatically Create checkbox was checkmarked.
If there are multiple deleted requestor records corresponding to the sender's email address, MainBoss Service cannot decide between them. The email message will be marked with the error message Senders email address matches multiple Requestors and the message will be marked for rejection. (However, it will not be rejected immediately—see below.)
The Web Requests facility can also create requestor records automatically, using the email address that a user specifies when submitting a request. The three Automatically Create options have the same effect on Web Requests as they do on MainBoss Service.
Remember that your MainBoss Requests license may place limits on the total number of requestors allowed in the Requestors table.
Automatically Create Requestors: If you checkmark Automatically Create Requestors, MainBoss Service attempts to create requestors based on existing records in the Contacts table. It checks the contacts records to see if any have an "Email" field matching the email address of the person who sent the request. If so, MainBoss Service creates a requestor record referring to that contact record and the email request is accepted. Otherwise, MainBoss Service checks to see if any contact record has an "Alternate Email" field matching the email addess of the person who sent the request. Again, if MainBoss Service finds a match, the service creates a requestor record referring to the contact record.
There may be multiple contact records whose "Email" or "Alternate Email" fields match the sender's email address. In this case, MainBoss Service can't decide between them. The email will be marked with the error Senders email address matches multiple Contacts and the message will be marked for rejection.
Automatically Create Requestors from Active Directory: If you checkmark Automatically Create Requestors from Active Directory, MainBoss Service begins by checking existing records in the Contacts table, going through the same process as Automatically Create Requestors. If a matching contact record is found, MainBoss Service will create a corresponding requestor record as described for Automatically Create Requestors. If no matching contact record is found, MainBoss Service then checks through any deleted contact records. If any deleted record has an "Email" or "Alternate Email" field matching the sender's email address, MainBoss Service will restore the deleted record (undelete it) and use it to create a requestor record. MainBoss will also restore a contact record if its "AD Reference" matches the requestor's Active Directory entry.
If there are no deleted contact records with the sender's email address, Automatically Create Requestors From Active Directory tells MainBoss Service to create a new contact record for the sender. MainBoss Service will check the Active Directory of your Windows network, and will look for any person whose primary email address matches the sender's email address. If there is a single matching address, MainBoss Service creates a new contact record using information from the Active Directory entry; if there are multiple matching addresses, MainBoss Service issues an error message (since there is no way to choose which person is correct).
If there are no matching email addresses, MainBoss Service checks the secondary email addresses in Active Directory. Again, if there is a single record with a matching email address, MainBoss Service creates a MainBoss contact record using information from the Active Directory. If there are multiple records with maching addresses, MainBoss Service issues an error message.
If MainBoss Service attempts to create a contact record, the process will fail if there's already a contact record with the same name. In this case, MainBoss Service will mark the request for rejection.
If MainBoss Service has been successful in finding or creating a contact record, the service creates a requestor record referring to that contact record. It then creates a request based on the sender's email message.
Automatically Create Requestors From Email: If you checkmark Automatically Create Requestors From Email, MainBoss Service begins in the same manner as Automatically Create Requestors From Active Directory—it first determines if there are any contact records with email addresses matching the sender's address. If not, MainBoss Service checks for deleted contact records; if any matches are found, MainBoss Service restores the record and proceeds just as with Automatically Create Requestors From Active Directory.
If there are no matching contact records (active or deleted), then MainBoss Service attempts to create one. In order to do so, it begins in the same way as Automatically Create Requestors From Active Directory: it searches the Active Directory for an entry whose primary email address matches the sender's email address. The Active Directory information is used to create a contact record if there is one and only one Active Directory entry whose primary email address matches the sender's. If MainBoss Service can't find an Active Directory entry with a matching primary email address, it checks secondary email addresses. Again, if there is one and only one matching address, MainBoss Service creates a contact record using the Active Directory information; however, the "Email" address of this contact record will be set to the sender's email address, not to the primary email address given in Active Directory.
If no matches are found in the Active Directory, MainBoss Service will attempt to create a contact record using information in the email message itself. The contact record's "Code" field will be set to the message's "Display Name" and the contact record's "Email" field will be set to the message's sender.
When MainBoss Service attempts to create such a contact record, the process may fail (typically because there's already a contact record with the same name). In this case, the original email message is marked for rejection. If MainBoss Service succeeds in creating the contact record, it creates a corresponding requestor record and accepts the email message as a request.
In general, we do not recommend checkmarking Automatically Create Requestors From Email—for example, if you receive spam in your mailbox, MainBoss Service will attempt to create a requestor record for whoever sent the spam. However, the option may be acceptable if your mailbox is well protected from spam, or if you only activate the option for a limited time, e.g. when you first start using MainBoss and you want MainBoss to "learn" about your usual requestors.
Accept Auto Create Email Pattern: Is a string specifying a pattern (also called a regular expression). When MainBoss Service processes an incoming email request and the requestor's email address isn't already in the list of authorized requestors, MainBoss checks the sender's email address against this pattern. If the address matches the pattern, the incoming email message will automatically be accepted; in addition, the message's sender will be added to the list of acceptable requestors (if the sender isn't on the list already).
One common type of pattern will be something like "@ourcompany.com". This tells MainBoss Service to accept all requests from anyone whose email address includes the string @ourcompany.com. In other words, you'll automatically accept requests from people inside your company.
The rules governing the pattern are the standard regular expression rules for Windows. For an introduction to these rules, see
https://www.codeproject.com/Articles/9099/The-Minute-Regex-Tutorial
Reject Auto Create Email Pattern: Is the opposite of "Accept Auto Create Email Pattern"—MainBoss Service automatically rejects all email requests sent by people whose email address matches "Reject Auto Create Email Pattern".
For example, suppose that you have been receiving nuisance complaints from joe@xyz.com. You could add this address to your reject pattern so that MainBoss Service would automatically reject messages from the given address. If you have multiple addresses that you want to reject, you can just separate them with "|" characters as in
joe@xyz.com|pat@hij.net|chris@lmn.org
There is no limit on the length of the string you can specify.
"Reject Auto Create Email Pattern" overrides the Automatically Create checkboxes described earlier and also overrides "Accept Auto Create Email Pattern". If an email sender matches the "reject" pattern, the message is immediately rejected (without being tested against the "accept" pattern) and MainBoss does not try to create a requestor record for the sender.
Comments: Any comments you wish to record.
Incoming Mail section: Controls how MainBoss Service processes requests sent in by email.
Process Requestor Incoming Email: If this box is checkmarked, MainBoss Service will operate normally. If the box is blanked out, MainBoss Service will not process incoming requests. In general, this box should be checkmarked; however, if you're changing your configuration, you may wish to turn off request processing until you've completed reconfiguration. You may also want to blank out the box if you want MainBoss to stop receiving email requests.
Mail Server Type: Choose one of the options listed. If you choose Automatically determined, MainBoss will test each possibility in the following order: POP3 with encryption, IMAP4 with encryption, POP3S, IMAP4S, plain POP3 (no encryption), and plain IMAP4 (no encryption). In doing these tests, MainBoss only looks at the default port for each server type; if your mail server uses a different port than the default, you must mark a specific server type (e.g. IMAP4S) and specify the port number in "Override Default Port".
Encryption: Choose one of the options listed:
Require Encryption with a Valid Certificate: MainBoss will only deal with your mail server if it has a valid security certificate. This automatically implies that encryption will be used. You'll receive an error message if the server has an invalid certificate.
Require Encryption: MailBoss will only deal with your mail server using one of the encrypted techniques. You'll receive an error message if none of the techniques work. Note that this option requires that your mail server has a security certificate, but it accepts self-signed certificates; it also accepts certificates that are not technically valid.
When Available: If you select this option, MainBoss still tries to use encryption when dealing with your mail server. However, if the server doesn't accept encryption, MainBoss will not issue an error message; it will simply communicate with the mail server using unencrypted data.
Mail Server: The name of the computer that receives your incoming mail. For example, if you're running Microsoft Exchange, this is usually the name of your Exchange server. This machine must allow mail access through POP3 or IMAP4.
Override Default Port: Should only be filled in if your mail server uses a non-standard port. MainBoss considers the following to be the standard ports:
Do not specify a port number if you have marked the Automatically determined option under "Mail Server Type".
Override Default MailBox: The name of the mailbox, if you're using any version of IMAP4 and if you're using any other name than the default INBOX.
Although the IMAP4 standard calls this the mailbox name, most people would likely call this value a folder name. In general, the only time a value should be entered here is if incoming request emails somehow end up stored in a different folder from the default. (This can happen if you're using server-side rules to sort incoming mail into folders.)
Since "Override Default MailBox" is only used with versions of IMAP4, MainBoss will not try to use POP3 or any variant of POP3 if you enter a name in the "Override Default MailBox" field.
Mail User Name: The name of the email account to which requests will be sent. For example, if users send mail to workreqs@yourcompany.com, the Mail User Name would usually be workreqs.
Important Note: Different sites will have different mail packages handling POP3 and IMAP4 processing. Some packages issue an authentication error if "Mail User Name" includes the @sitename part of an email address—you must only give the user name, e.g workreqs. Other packages require the @sitename part—you must specify the whole email address, e.g. workreqs@yourcompany.com. If you are getting authentication errors with a given user name, try changing the name to the other format to see if this corrects the problem.
Mail User's Password: The password (if any) for the specified Mail User Name. As a protection measure, MainBoss encrypts this password before storing it in MainBoss's database; therefore, when you type in the password, you'll only see "*" characters, the same as with most Windows passwords.
Wakeup Interval: Dictates how often MainBoss Service will check for new incoming messages. By default, this is 0:30 (every 30 minutes).
Maximum Mail Size: The maximum size allowed for any part of an incoming mail message (specified as a number of characters). For example, this limits the size of attachments that you'll accept. If you leave this blank, MainBoss chooses a default equal to the largest number that can be stored in a 32-bit integer. (This comes out to about 4 GB.)
Manual Processing Time Allowance: If MainBoss Service marks an email message for rejection, the service doesn't send a rejection to the sender right away. Instead, MainBoss Service delays, allowing time for human users to deal with the problem. For example, if there's some reason that MainBoss Service can't create a requestor record for the sender, MainBoss waits a certain length of time; this gives you a chance to resolve the problem, e.g. by manually creating a requestor record for the sender.
The length of time that MainBoss waits is dictated by the value of "Manual Processing Time Allowance". For example, if you fill in this field with 12:00:00, MainBoss will wait 12 hours after an email request is marked for rejection. This gives you time to do something about the request, if you choose to do so.
If the time allowance expires and nothing has changed, MainBoss will reject the request.
If the error message changes on a received request, MainBoss starts on a new delay. For example, suppose you see that there's a problem with a request and you make some change that you think will fix the problem. However, when MainBoss tries to process the request, a different problem arises. In this case, MainBoss will wait the full delay time again before rejecting the request; this gives you a chance to do something about the new problem.
Outgoing Mail section: Controls how MainBoss Service sends out email (acknowledgements to requestors and notifications to assignees).
Process Notification Email: If this box is checkmarked, MainBoss Service will send out notifications as normal. If the box is blanked out, MainBoss Service will not send out notifications. In general, this box should be checkmarked.
Return Email Address: The return email address to be placed on acknowledgements and notifications (i.e. the address that will be used if the recipient wants to reply). This should be the email address of a person in the maintenance department who can personally handle responses from clients.
Important: The "Return Email Address" should not be the same as the mailbox to which users submit requests. If it is, you'll run into trouble if a requestor has an auto-reply set up, such as "Hi, I've gone on vacation and won't be answering my email." What happens is this: if MainBoss Service sends an acknowledgement to the user, the auto-reply replies to the MainBoss Service mailbox; MainBoss Service thinks this is a new request, so sends an acknowledgement to the requestor; the requestor's auto-reply sends another reply to MainBoss Service; MainBoss Service sends another acknowledgement; and so on, until someone runs out of disk space. The way to avoid this is to set "Return Email Address" to refer to a human being (who can be smart about dealing with auto-replies).
Return Email Display Name: The name to be associated with "Return Email Address".
HTML Email Notification: If this is checkmarked, MainBoss Service sends notifications in HTML format. Otherwise, notifications are sent as plain text.
MainBoss Web Access URL: If you have a Web Access license, MainBoss Service can add HTML links to notifications that will let users jump from the notification email directly to a web page displaying an associated request or work order. In order to do this, you have to specify the URL of the web site that you use for MainBoss's Web Access. For example, you might set "MainBoss Web Access URL" to
http://ourcompany.com/MainBossWeb
Notification Interval: Dictates how often MainBoss Service will check to see if notifications should be sent. By default, this is 0:10 (every 10 minutes).
SMTP Server: The name of the computer that will handle MainBoss Service's outgoing mail. Normally, this is the same as "Mail Server" in the Incoming Mail section of the configuration record; however, it doesn't have to be.
SMTP Port: The port used by the SMTP mail server. This is usually port 25 or 587.
Use TLS/StartTLS: If this box is checkmarked, MainBoss Service will use TLS encryption when sending out mail.
SMTP Credential Type: The options in this area determine what kind of authentication (if any) MainBoss Service will use when sending out mail.
Anonymous: If this option is selected, MainBoss Service will not use authentication (mail is sent without going through any identification process).
Use the default network credential: If this option is selected, MainBoss Service uses whatever authentication is provided by the network as the default.
Using the specified SMTP domain, username and password: Choosing this option indicates that your SMTP server requires a domain, username, and password in order to send out mail. The fields below specify the required information:
SMTP User Domain: The domain that MainBoss Service should specify when sending out mail.
SMTP User Name: The username that MainBoss Service should specify when sending out mail.
SMTP Encrypted Password: As a protection measure, MainBoss encrypts this password before storing it in MainBoss's database.
Messages section: Controls the text strings used by MainBoss Service when sending email to users.
The main list in this section shows the strings whose text can be changed. For example, the string with identifier EstimatedCompletionDate is used as a label when MainBoss Service puts an estimated completion date into an email message. If you change the value of this string to "We think the job will be done by:", MainBoss will use the given phrase instead of the default "Estimated Completion Date:".
You can set up different strings for different languages. For example, if some of your users and/or requestors prefer to use English and others prefer to use French, you can create a set of English strings and a separate set of French strings. (Note: you specify people's preferred language in their Contacts record.)
Note: Before MainBoss 4.0, a different system was used to customize the contents of email messages. If you update from an old version of MainBoss to a version that uses the system described here, the updating process will automatically attempt to incorporate any existing customizations you have made.
After you have created or editing your configuration information and saved the configuration record, go to Administration | MainBoss Service and click Manually run the MainBoss Service (on the second drop-down button at the bottom of the window). This performs a single trial run of the MainBoss Service software; it produces a number of diagnostic messages which are displayed in the log message window immediately above the button. If there are problems with your configuration information, the log messages should help you make corrections.
You can use Manually run the MainBoss Service even if you don't have Windows Administration privileges. Manually run the MainBoss Service doesn't actually run a Windows service, but it runs the same software that will be used for MainBoss Service later on. Output from this software is written to the MainBoss Service log and possibly to error windows.
If the log messages that you see don't tell you enough, you may gain more information by going to the Windows event logs. However, Windows Administration privileges are required to view the event logs.
< Previous section | Table of Contents | Index | Next section >