Email Connector Parameters

These parameters are used in all the email connectors in the Tahiti processes. You need to set them to the appropriate values for your email server:

• emailServerAddress
• emailServerPassword
• emailServerPort
• emailServerUsername
• emailServerUseSSL

There is also a parameter, emailNotificationSender, that defines the Sender address for email sent from the Tahiti application.

Finally, there is a parameter, emailHRAddress, that defines the To address for email sent to HR.

Define each parameter as follows:

1. Select the pool and go to the Details panel, Data tab, Parameters pane.
2. Click Add. The New parameter popup opens.
3. Enter the parameter name.
4. Optionally (but recommended), enter a description.
5. Choose the data type from the Type drop-down menu, choosing the type that matches the connector input type (integer for emailServerPort, Boolean for emailServerUseSSL, text for the rest). 
6. Click “Finish & Add” to add the next parameter, or Finish to exit from the popup.

You need to define these email parameters in both the Tahiti-NewVacationRequest and the Tahiti-CancelVacationRequest processes. 

Now you can configure the email connectors. In some cases, the service task where the connector is defined is already created in the diagram. In others, you need to add the service task first.

Email Connectors in Tahiti-NewVacationRequest

This section explains how to configure the email connectors in the Tahiti-NewVacationRequest process.

Notify manager request pending

This connector sends a message to a manager when someone in their team has submitted a vacation request. It informs the manager that there is a pending request to review. The message is sent on behalf of the employee, asking the manager to review the vacation request. Add a service task, Notify manager request pending, in the Employee lane after the Deduct requested days from available days service task.

To define the email connector in the Notify manager request pending service task, follow these steps:

1. Select the service task in the whiteboard.
2. Go to the Details panel, Execution tab, Connectors In pane.
3. Click Add. A connector definition wizard opens.
4. In the list of Categories, choose Messaging.
5. In the list of Connector definitions, choose Email, and then click Next.
6. Enter a name for the connector, emailNotifyManagerRequestPending.
7. Optionally, enter a description.
8. Specify the behavior if the connector fails by selecting an option from the dropdown menu. If you have an email server and account that you can use for testing, choose “Put in failed state.” Otherwise, choose “Ignore error and continue process,” so that the process does not wait for the email to be sent. Then click Next.

9. Configure the connection information. This is where you will use the parameters that you have defined:

   • For the Security & SSL field, click “Switch editor to create a condition.” Then click the pencil icon, choose Parameters from the Expression type list, and choose emailServerUseSSL.

   • For the other fields, click the pencil icon, go to the Parameters list, and choose the relevant parameter:

     Field	Parameter
     SMTP Host	emailServerAddress
     SMTP Port	emailServerPort
     Authentication > Username	emailServerUsername
     Authentication > Password	emailServerPassword

10. Click Next, which takes you to the screen to configure addressing information.
11. In the From field, choose the parameter emailNotificationSender.

12. The To field defines the address to which the email will be sent. This is the manager of the employee who submitted the vacation request. This information depends on the request, and could change during the lifetime of the application if the organization reporting structure changes, so the value is defined with a script, as follows:

    1. Click the pencil icon next to the To field. This opens the expression editor.
    2. In the Expression type list, choose Script.
    3. Enter the script name, setReviewerEmailAddress.

    4. Enter this script:

       import org.bonitasoft.engine.identity.ContactData
       import org.bonitasoft.engine.identity.User
       
       User requesterUserInfo =
        BonitaUsers.getUser(apiAccessor,
         vacationRequest.requesterBonitaBPMId)
       
       ContactData managerProfessionalContactInfo =
        BonitaUsers.getUserProfessionalContactInfo(apiAccessor,
         requesterUserInfo.managerUserId)
       
       return managerProfessionalContactInfo.email
       

13. Click OK to save the script and close the expression editor. Then click Next.
14. Enter the email subject: Vacation request to review.
15. Enter the message text: Please go to the Tahiti application and review this pending request from a member of your team. It is also possible to define the message content with a script and use variables, for example, to include the employee name, but for simplicity here you will use a static message.
16. Click Finish.

The email connector for this service task is now configured. An icon is added to the service task showing that it contains a connector. This part of the Tahiti-NewVacationRequest diagram now looks something like Figure 12-1:

Figure 12-1. Service task for informing manager of a vacation request for review

import org.bonitasoft.engine.identity.ContactData
import org.bonitasoft.engine.identity.User

User requesterUserInfo =
 BonitaUsers.getUser(apiAccessor,
  vacationRequest.bonitaEmployeeId)

ContactData managerProfessionalContactInfo =
 BonitaUsers.getUserProfessionalContactInfo(apiAccessor,
  requesterUserInfo.managerUserId)

return managerProfessionalContactInfo.email

return BonitaUsers.getProcessInstanceInitiatorProfessionalContactInfo(
 apiAccessor, processInstanceId).email

return BonitaUsers.getProcessInstanceInitiatorProfessionalContactInfo(
 apiAccessor, processInstanceId).email

import java.text.SimpleDateFormat

import org.bonitasoft.engine.api.IdentityAPI
import org.bonitasoft.engine.identity.User

// Create a date formatter that will format the date stored in
// business data to a user readable format
SimpleDateFormat formatter = new SimpleDateFormat("MM-dd-yyyy",
 Locale.US)
formatter.timezone = TimeZone.getTimeZone("UTC")

// Get a reference to IdentityAPI in order to retrieve user
// information using user id
IdentityAPI identityAPI = apiAccessor.identityAPI

// Requester user information
User requester = identityAPI.getUser(
 vacationRequest.requesterBonitaBPMId)

// Reviewer user information
User reviewer = identityAPI.getUser(
 vacationRequest.reviewerBonitaBPMId)

return "The vacation request submitted by 
 ${requester.getFirstName()} ${requester.getLastName()} 
 for ${formatter.format(vacationRequest.getStartDate())} to 
 ${formatter.format(vacationRequest.getReturnDate())} 
 (${vacationRequest.getNumberOfDays()} days) 
 has been rejected by ${reviewer.getFirstName()} 
 ${reviewer.getLastName()} 
 with the following comment: ${vacationRequest.getComments()}"

Email Connectors in Tahiti-CancelVacationRequest 

This section explains how to configure the email connectors in the Tahiti-CancelVacationRequest process. First add these service tasks for the connectors:

• Notify manager cancellation request to review in the Employee lane after the Set vacation request status to “processing cancellation” service task
• Notify employee cancellation approved in the Manager lane on the Yes flow out of the Cancellation approved? gateway
• Notify employee cancellation refused in the Manager lane on the No flow out of the Cancellation approved? gateway

When you have added these service tasks, this part of the diagram will look something like Figure 12-2:

Figure 12-2. Service tasks for sending an email notification when cancelling a vacation request

import org.bonitasoft.engine.identity.ContactData
import org.bonitasoft.engine.identity.User

User requesterUserInfo =
 BonitaUsers.getUser(apiAccessor,
  vacationRequest.bonitaEmployeeId)

ContactData managerProfessionalContactInfo =
 BonitaUsers.getUserProfessionalContactInfo(apiAccessor,
  requesterUserInfo.managerUserId)

return managerProfessionalContactInfo.email

return BonitaUsers.getProcessInstanceInitiatorProfessionalContactInfo(
 apiAccessor, processInstanceId).email

return BonitaUsers.getProcessInstanceInitiatorProfessionalContactInfo(
 apiAccessor, processInstanceId).email

Calendar Connector Parameters

Use parameters to make it easier to configure the calendar connectors, to avoid repeating information, and to make it easier to update settings later. Define the following parameters:

calendarApplicationName

A unique name used to identify the calling application. For example, TahitiVacationManagement.

calendarCalendarId

The email address that identifies the calendar to be accessed. For example, [email protected].

calendarServiceAccountId

The email address of the Google client that you noted when you created the service account. For example, 012345678901-g454gcfxj4jb5@developer.gserviceaccount.com.

calendarServiceAccountP12File

The full path to the private key file that you saved when you created the service account. For example, C:/my/folder/path/tahitiApps-54vhc5fgh1.p12.

calendarServiceAccountUser

The email address of the user accessing the calendar. This account must have appropriate rights to modify the calendar. You could use the calendar owner, for example, [email protected].

You need to define these calendar parameters in the Tahiti-newVacationRequest, Tahiti-ModifyPendingVacationRequest, and Tahiti-CancelVacationRequest processes.

Date Formatter Groovy Script

Google Calendar APIs require a specific date format: yyyy-MM-dd.

This means that you need to convert between the format used in the business data and the one required by the Google Calendar APIs. The conversion needs to happen when providing start and end dates in the Calendar connectors.

We will use a Groovy script to define this format conversion. The same conversion is needed each time we configure a Calendar connector, so we will define a Groovy script that can be used by all processes defined in the workspace:

1. Go to the Development menu, Manage Groovy scripts... menu entry.
2. Click Create.
3. Enter a name for the new script, DateTimeScripts, and click OK.
4. In the list, select the newly created script and then click Open.

5. Enter the following script content:

   public static String formatForGoogle(Date date) {
    // Create a date formatter that will format the date stored
    // in business data to the format expected by
    // Google Calendar API
    java.text.SimpleDateFormat formatter =
     new java.text.SimpleDateFormat("yyyy-MM-dd", Locale.US)
    
    formatter.timeZone = TimeZone.getTimeZone("UTC")
      
    // Returns the formatted date
    return formatter.format(date)
   }
   

6. Click OK to save the script definition, and then click Cancel to close the popup window.

Update calendar request pending

After an employee submits a vacation request, there needs to be a service task that creates a vacation calendar entry, so that the request is visible to the whole team. In the Tahiti-NewVacationRequest diagram, add a service task called Update calendar request pending. Your diagram will look something like Figure 12-3.

Figure 12-3. Service task for creating a new calendar event for a pending vacation request

To configure the calendar connector, follow these steps:

1. Select the Update calendar request pending task, and go to the Details panel, Execution tab, Connectors in pane.
2. Click Add. This opens the connector configuration wizard.
3. In the Categories list, expand the Calendar category and choose Google Calendar (API v3).
4. In the Connector definitions list, choose Create Event, and then click Next.
5. Enter a name for this connector, calRegisterVacationEvent.
6. Set the failure behavior to “Ignore error and continue process,” and then click Next.

7. Configure the connection information. This is where you will use the parameters that you have defined. For each field, click the arrow to open the drop-down list and choose the relevant parameter:

   Field	Parameter
   Application name	calendarApplicationName
   Calendar ID	calendarCalendarId
   Service Account ID	calendarServiceAccountId
   Service Account P12 file	calendarServiceAccountP12File
   Service Account User	calendarServiceAccountUser

8. Click Next to go to the event parameters screen. Enter the following information:

   1. Summary: The title of the event that is displayed in the calendar. Specify this as a Groovy script called Requester first name and last name + pending status, with the following content:

      import org.bonitasoft.engine.api.IdentityAPI
      import org.bonitasoft.engine.identity.User
      
      // Get reference to IdentityAPI to access user's first and
      // last name using the user id stored in the VacationRequest
      IdentityAPI identityAPI = apiAccessor.identityAPI
      
      // Retrieve user information using the API and user id stored
      // in business data
      User user = identityAPI.getUser(
       vacationRequest.requesterBonitaBPMId)
      
      // Aggregate user first and last name and return the result
      return user.firstName + " " + user.lastName + " " +
       vacationRequest.status
      

   2. Start Date: The first date of the requested vacation. Specify this as a Groovy script called format start date, with the following content:

      DateTimeScripts.formatForGoogle(vacationRequest.startDate)
      

   3. Start Time Timezone: Set this to UTC (you can type the value in the field).
   4. Check the box for All Day.

   5. End Date: The return to work day (because a Google Calendar end date is exclusive). Specify this as a Groovy script called format return date, with the following content:

      DateTimeScripts.formatForGoogle(vacationRequest.returnDate)

   6. End Time Timezone: Set this to UTC.
   7. Click Next.

9. In the Extra Event Parameters screen, specify the Attendee, as follows:

   1. Click Add row.
   2. Click in the empty new row. The pencil icon appears.
   3. Click the pencil icon to open the expression editor.
   4. Create a script expression called return requester email address with the following content:

      import org.bonitasoft.engine.identity.ContactData
      
      Long userId = vacationRequest.requesterBonitaBPMId
      
      ContactData professionalContactInfo =
       BonitaUsers.getUserProfessionalContactInfo(apiAccessor, userId)
      
      return professionalContactInfo.email
      

10. Click Next twice to get to the Output operations screen.

11. In the Output operations screen, define an operation to store the calendar event ID in the vacation request, as follows:

    1. In the Select target drop-down menu, double-click vacationRequest.
    2. Click “Takes value of.” This opens the Select operator popup.
    3. In the popup, select “Use a Java method.” This opens a list of methods.
    4. Choose setCalendarEventId from the list and click OK.
    5. Click the pencil icon next to the right field. This opens the expression editor.
    6. Set the Expression type to Connector output.
    7. In the list of outputs, choose ID, and then click OK.
    8. Optionally you can remove default output operations: for each operation click the button with the red cross icon.
12. Click Finish.

Update calendar request modified

If a user modifies a vacation request, the associated calendar event needs to be updated. In the Tahiti-ModifyPendingRequest diagram, add the service task Update calendar to update the calendar event with the new dates. Your diagram will look something like Figure 12-4.

Figure 12-4. Service task for updating the calendar for a modified vacation request

Configure a calendar connector on this service task to modify the calendar event. Follow the same steps as for the “Update calendar request pending”, with the following differences:

• Connector definition: Update Event.
• Name: calUpdateEventDetails.

• Event ID: The ID of the calendar event, specified as follows:

  1. Beside the Event ID field, click the pencil icon to open the expression editor.
  2. In the Expression type list, choose Java.
  3. In the Name list, choose vacationRequest.
  4. In the browse box, choose getCalendarEventId().
  5. Click OK.

• Start Date: The new start date for the vacation request, specified as follows:

  1. Beside the Start Date field, click the pencil icon to open the expression editor.
  2. In the Expression type list, choose Script.
  3. In the Name field, type formatStartDate.

  4. Enter the following script:

     DateTimeScripts.formatForGoogle(vacationRequest.startDate)
     

  5. Click OK to close the expression editor.
  6. Start Time Timezone: Set this to UTC (you can type the value in the field).
  7. Check the box for All Day.

• End Date: The new end date for the vacation request, specified as follows:

  1. Beside the End Date field, click the pencil icon to open the expression editor.
  2. In the Expression type list, choose Script.
  3. In the Name field, type formatReturnDate.

  4. Enter the following script:

     DateTimeScripts.formatForGoogle(vacationRequest.returnDate)
     

  5. Click OK to close the expression editor.
  6. Ent Time Timezone: Set this to UTC (you can type the value in the field).

Update calendar approved

When a manager approves a vacation request, the associated calendar event needs to be updated to show that the request is no longer pending but is approved. In the Tahiti-NewVacationRequest diagram, add a service task called Update calendar request approved on the yes flow from the Request approved? gateway (see Figure 12-5).

Figure 12-5. Service task for updating the calendar for an approved vacation request

On this service task, configure a calendar connector to update the calendar event to change the status from pending to approved.

Follow the same steps as for the “Update calendar request pending”, with the following differences:

• Connector definition: Update Event
• Name: calUpdateVacationEventName.

• Event ID: The ID of the calendar event, specified as follows:

  1. Beside the Event ID field, click the pencil icon to open the expression editor.
  2. In the Expression type list, choose Java.
  3. In the Name list, choose vacationRequest.
  4. In the browse box, choose getCalendarEventId().
  5. Click OK.

• Summary: The updated event title. Specify this as a Groovy script called new status approved, with the following content:

  import org.bonitasoft.engine.api.IdentityAPI
  import org.bonitasoft.engine.identity.User
  
  // Get reference to IdentityAPI to access user's first and last
  // name using the user id stored in the VacationRequest
  IdentityAPI identityAPI = apiAccessor.identityAPI
  
  // Retrieve user information using the API and user id stored in
  // business data
  User user = identityAPI.getUser(
   vacationRequest.requesterBonitaBPMId)
  
  // Aggregate user first and last name and return the result
  return user.firstName + " " + user.lastName + " " +
   vacationRequest.status
  

• You do not need to specify the attendee or an output operation. You do not need to specify the vacation request details such as the start date, because these have not changed.

Update calendar request refused

When a manager refuses a vacation request, the associated calendar event needs to be removed from the calendar. In the Tahiti-NewVacationRequest diagram, add a service task called Update calendar request refused on the no flow from the Request approved? gateway (see Figure 12-6).

Figure 12-6. Service task for removing a refused request from the calendar

Configure a calendar Delete event connector called calRemoveRefusedVacationEvent. Define the Event ID as in the previous section.

Update calendar request cancelled

If a vacation request is cancelled, it must be removed from the calendar. In the Tahiti-CancelVacationRequest process diagram, add a service task called Update calendar request cancelled before the gateway at the end of the flow handling a successful cancellation (see Figure 12-7).

Figure 12-7. Service task for removing a cancelled request from the calendar

Configure a Delete event connector called calRemoveCancelledVacationEvent. Define the Event ID as in the previous section using the vacationRequestToCancel object.