Communication Business rules

We now need to define business rules applicable to the new objects.

There are a number of calculated attributes defined for this object, so we need to calculate values of these attributes. The Sent on rule calculates the value of the SentOn attribute:

IF OutgoingEmail.State WAS CHANGED TO 'Sent' THEN 
   OutgoingEmail.SentOn=CURRENT_TIMESTAMP 

We also need to calculate the SentToAddress attribute, so we define the Destination address rule:

IF OutgoingEmail.State WAS CHANGED TO 'Sent' THEN 
   OutgoingEmail.SentToAddress = OutgoingEmail.Correspondent.EmailAddress 

Once e-mail has been sent we shouldn’t allow anyone to change the SentToAddress, so we need to protect this attribute:

IF OutgoingEmail.State='Sent' THEN 
   PROTECT OutgoingEmail.SentToAddress FROM ALL 

We only have one rule that calculates the SentOn attribute:

IF OutgoingLetter.State WAS CHANGED TO 'Sent' THEN 
   OutgoingLetter.SentOn=CURRENT_TIMESTAMP 

According to the requirements the application is supposed to automatically send e-mails or letters to members when the items they have reserved become available and to remind them that their loan is overdue (see Requirements). In order for the system to be able to send e-mails to members, the Member object must become intelligent (see also the “Intelligent Business Objects” and “Outgoing Email” sections).

To make the Member object intelligent open the Member object for editing and click on the Communication property in the list of object properties. Tick the Email channel in the list of channels for the object. This means that it is possible to communicate with this object through e-mails. Select the “Use values from SystemSettings object” radio button (we will explain this object in System Initialization). Click on the OK button on the dialog and click on the “Save” button to save the changes to the object.

The next step is to configure a notification representing an e-mail. Note that unlike most business objects notifications are not stored in the system – they just represent a piece of information that is sent around or exchanged. So there is a difference between the OutgoingEmail object, which registers all e-mails sent to members and an e-mail notification, which represents the information sent to members. If we did not want to register e-mails we would not need the OutgoingEmail object, yet we would still need the email notification.

We will define the following notifications:

1. A notification representing an e-mail that is sent when a reservation is offered
2. A notification representing an e-mail that is sent to remind a member about overdue loan
3. A notification representing any other e-mail that may be sent to a member by an operator at any time

Let us define the first notification. To do this, right click on the Notifications node in the Elements Tree and select Add Outgoing Email Notification from the pop-up menu. AwareIM will automatically create a new notification with the attributes required for the notification to be an e-mail. The editor for this notification will appear in the working area of the screen. We will change the name of the notification from OutgoingEmail to ReservationOfferEmail and then select the Subject attribute. In the list of attribute properties we will enter the following text as the initial value for this attribute Reserved item available. Now we will add the initial value for the Message attribute. As the text of the initial value is quite large we will click on the Initial value property and enter the text in the dialog that appears:

Dear <<Reservation.Member.FirstName>> <<Reservation.Member.LastName>>,
 
The item <<Reservation.Item.Title>> you reserved on 
<<Reservation.ReservedOn, dd/MM/yyyy>> is now available 
for you to borrow. You have 7 days to borrow the item. 
The reservation expires on <<Reservation.ReservedOn+7*24, dd/MM/yyyy>>.
 
Regards,
 
The Library. 

Note that we assume that the Reservation object that we refer to in the tags of this message is available in the context.

In a similar fashion we define the LoanOverdueEmail notification – see the sample application located in the samples directory of your AwareIM installation for the text of the message. We also define the OutboundEmail notification without any initial values for the Subject and Message attributes – this notification will represent a general e-mail sent by an operator.

Let us now add business rules that will send the notifications we have defined. We will start with the reservation offer e-mail. Offered reservations are handled by the rules of the Reservation. We will add the Reservation offer e-mail rule that will send the ReservationOfferEmail to a member when the state of the reservation changes to Offered:

IF Reservation.Status WAS CHANGED TO 'Offered' AND Reservation.Member.EmailAddress IS DEFINED THEN 
   SEND ReservationOfferEmail TO Reservation.Member 
   CREATE OutgoingEmail WITH 
    OutgoingEmail.Message=ReservationOfferEmail.Message,
    OutgoingEmail.Correspondent=Reservation.Member, 
    OutgoingEmail.Subject=ReservationOfferEmail.Subject, 
    OutgoingEmail.State='Sent' 

The CREATE action in the rule above creates the OutgoingEmail object so that the e-mail is registered in the system. Note that the Reservation object that the ReservationOfferEmail expects in the context is in the context, since this is the object the rules of which are being executed.

Now we need to add a business rule to the Loan object that will send the LoanOverdueEmail notification to the member:

IF Loan.OverdueFeeChargedOn WAS CHANGED AND Loan.Member.EmailAddress IS DEFINED THEN
   SEND LoanOverdueEmail TO Loan.Member
   CREATE OutgoingEmail WITH 
    OutgoingEmail.Text=LoanOverdueEmail.Message,
    OutgoingEmail.Correspondent=Loan.Member, 
    OutgoingEmail.Subject=LoanOverdueEmail.Subject, 
    OutgoingEmail.State='Sent' 

If a member does not have e-mail (which means that there is no value for the EmailAddress attribute) the application should automatically prepare a letter that informs the member that the reserved item became available or reminds the member about overdue loan. Also when the library sends any other letter to a member (for whatever reason) we want our system to automatically prepare a standard template of a letter that has library details and logo, so that the operator only fills in the text of the letter.

All outgoing letters must be registered with the system, so the system must create the instance of the OutgoingLetter object. The actual document containing the electronic copy of the letter will be stored in the LetterDocument attribute of the OutgoingLetter object.

We start by defining the templates of the letter documents we will be sending. We will create the following document templates:

1. Reservation offer letter
2. Loan overdue letter
3. Letter to member template

The last one is the general template of a letter to a member. All templates will be created as MS Word documents; however, if a target system does not have MS Word we will also prepare the alternative version of the documents in the plain text format. AwareIM will automatically use the alternative versions if MS-Word is not available or not supported on the target platform, provided that we follow the naming conventions where the name of the alternative document is the same as the name of the original document followed by the “_Alternative” postfix (see also “Adding/Editing Document Templates”).

We can prepare the document templates in MS Word and then import them into AwareIM. To import the document create the document of the MS Word type (see Documents), click on the “Import” button on the documents editor pane and select the document file. You can have a look at the prepared templates in the sample configuration of the library application located in the “samples” directory of your AwareIM installation. Note that the “Reservation offer letter” template assumes that the Reservation object is in the context and uses it inside its tags; the “Loan overdue letter” assumes that the Loan object is in the context and the “Letter to member” template assumes that the OutgoingLetter object is in the context.

Now we need to add business rules to prepare reservation offer letter and reminder letter if a member does not have e-mail address. We add the “Reservation offer letter” business rule to the Reservation object (see Loan Object):

IF Reservation.Status WAS CHANGED TO 'Offered' AND Reservation.Member.EmailAddress IS UNDEFINED THEN 
 CREATE OutgoingLetter WITH 
   OutgoingLetter.Subject = 'Reservation offer letter',
   OutgoingLetter.Correspondent = Reservation.Member,
   OutgoingLetter.Text = 'See document',
   OutgoingLetter.LetterDocument = 'Reservation offer letter' 

The initialization of the “LetterDocument” attribute in the above rule is especially interesting. This attribute of the “Document” type is initialized with the name of the document template. AwareIM will automatically replace the contents of the tags used in the template with values of attributes of the OutgoingLetter object and store the resulting document in the LetterDocument attribute (see also the “Document Generation” section).

We also need to add the “Reminder letter” business rule to the Loan object (see Loan Object):

IF Loan.OverdueFeeChargedOn WAS CHANGED AND Loan.Member.EmailAddress IS UNDEFINED THEN
 CREATE OutgoingLetter WITH 
    OutgoingLetter.Subject = 'Item overdue',
    OutgoingLetter.Correspondent = Loan.Member,
    OutgoingLetter.Text = 'See document',
    OutgoingLetter.LetterDocument = 'Loan overdue letter' 

Finally we need to make sure that when the operator prepares a letter to a member the letter is created according to the format of the “Letter to member template”. When the operator prepares the letter the system will be creating an instance of the OutgoingLetter object. The operator will be entering the text of the letter in the “Text” attribute of the OutgoingLetter object. The entered text will be transferred to the template (if you look at the template you will see the ‹‹OutgoingLetter.Text›› as the text of the letter). We only need to make sure that the LetterDocument attribute of the OutgoingLetter object is set to the name of the template. In fact, we can do this by setting the initial value of this attribute to the name of the “Letter to member” template. So all we have to do is set the initial value of the LetterDocument attribute to “Letter to member template”.

We can get our application to automatically receive and register incoming e-mails that arrive to a certain e-mail address (our library will advise members to send their e-mails to this address).

To do this, double click on the node representing the business space version in the Elements Tree and click on the Incoming Emails property in the property list of the version. The Incoming e-mails dialog will be displayed. Select the The system will handle incoming e-mails radio button, select the Use values from SystemSettings object radio button (we will look at this object in System Initialization) and click on the OK button. The Automatic Elements dialog will be displayed. Tick the I want to automatically register all incoming e-mails checkbox and click on the OK button.

If we now look at the Elements Tree we will see that the Configuration Tool automatically added the IncomingEmail notification representing the incoming e-mail and the ReceivedEmail business object to store received e-mails. It has also added the rules that create and initialize the instance of the ReceivedEmail object when an incoming e-mail is received (see also the “Incoming Email” section).

As the ReceivedEmail object represents communication with a member we will add this object to the Communication business object group and add the following attributes to this object:

• Correspondent (reference to the Member object that we received the e-mail from)
• State (with choices Read and Unread with the initial value Unread)

We will also modify business rules automatically created by AwareIM to register incoming e-mails to set the value of the Correspondent attribute. To do this we open the IncomingEmail notification for editing and go to the Rules(received) tab at the bottom. We see the automatically created rule in the rule editor. We add the action that finds the member by the from address and we modify the CREATE action to initialize the Correspondent attribute with the found member. The resulting rule looks like this:

FIND Member WHERE IncomingEmail.FromAddress CONTAINS Member.EmailAddress 
 CREATE ReceivedEmail WITH 
   ReceivedEmail.Correspondent=Member,
   ReceivedEmail.Subject=IncomingEmail.Subject,
   ReceivedEmail.Message=IncomingEmail.Message,
   ReceivedEmail.SentOn=IncomingEmail.SentDate,
   ReceivedEmail.ToAddress=IncomingEmail.ToAddress,
   ReceivedEmail.FromAddress=IncomingEmail.FromAddress,
   ReceivedEmail.CC=IncomingEmail.CC,
   ReceivedEmail.BCC=IncomingEmail.BCC,
   ReceivedEmail.Attachment1=IncomingEmail.Attachment1,
   ReceivedEmail.Attachment2=IncomingEmail.Attachment2,
   ReceivedEmail.Attachment3=IncomingEmail.Attachment3