Many business situations require date comparisons and calculations. This section provide some examples on how to perform the most common date operations:
•Assign today's date to an attribute
•Subtract dates based on the Working time schema of a User
•Add dates based on the Working time schema
•Add dates based on a User's Working time schema
•Verify if a date is a working day
•Verify if a date is a working day for user
•Verify if a date is a working minute
•Verify if a date is a working minute for user
•Convert a date from user time zone to server time zone
To illustrate how to perform date operations let's take the following example: A Vacations Request Process manages the necessary activities to request and approve vacations for employees. When an employee creates a request, he/she must enter the leave and return dates. Using these values, the system calculates the number of days requested.
In this example, we will use date operations in order to:
•Assigns today's date to the request date (RequestDate attribute).
•Set the duration of Activities.
•Verify that the Vacation's Returning date is greater than the Vacation's Leaving date. If not, display a validation message.
•Calculate the number or days requested.
The data model of the Process is as follows:
Assign Today's Date to an Attribute
To assign today’s date to the Request Date attribute, go to the fourth step of the Bizagi Process Wizard and select Activity Actions.
Click the Task in which this action will be performed and create an Expression.
Add an expression module and select the attribute to which today's date will be assigned.
Use the Data Model option to navigate the Data Model.
Assign today’s date to the attribute using the Today function found in the Date & Time Category.
The expression would be as follows:
<VacationRequest.RequestDate>=DateTime.Today;
Click OK to save the changes.
We have to validate that the Vacation's Returning date is greater than the Vacation´s Leaving date. If not, a validation message must be displayed to the end user. To do this, we have to establish a comparison between these dates.
1. On the fourth step of the Bizagi Process Wizard select Activity Actions.
Click the Task where this action will be performed and create an expression.
.
2. In an expression module, create the comparison by using the less than, greater than or equals to operators (<,> or =).
3. Create an IF condition to compare the attributes.
An error message will be displayed to the end user if the Leaving Date is greater than the Returning Date.
Use the Throw validation error function found in the Data Validation Category to configure the validation.
The expression would be as follows:
//If the leaving date is greater than or equal to the returning date, display an error message
if (<VacationRequest.LeavingDate>>=<VacationsRequest.ReturningDate>)
{
CHelper.ThrowValidationError("Returning Date cannot be less than the Leaving Date");
}
4. Save the rule by clicking OK.
The rule can now be tested. If you entered a Leaving Date greater that the Returning Date, the message will display as follows:
Verify if a Date is a Working day
Suppose we wish to verify that the returning date in a trip is a working day. If it is not working day, a warning message must be displayed. Otherwise, the application can continue with the next activity.
1. On the fourth step of the Bizagi Process Wizard, select Activity Actions.
Click the Task where this action will be performed and create an Expression.
2. In an expression module use an If condition. Evaluate if the returning date is a working date by using the IsWorkingDay function which can be found in the Date & Time function category.
Use as input parameter the returning date (ReturningDate) of the model.
The IsWorkingDay function will return True if the returning date is a working day, otherwise it will return False.
//Evaluate if the date is non-working
if (CHelper.IsWorkingDay(Me,<TravelRequest.ReturningDate>)==false)
{
CHelper.ThrowValidationError("Returning day is non working.");
}
Click OK to save the changes.
Verify if a Date is a Working day for a specific user
In a Travel Request process, you can start a case in the Register Travel Request Task. You must enter the Departure Date. If the departure day is a not working day for the user, a validation must appear showing this situation. Otherwise, the application can continue with the next activity.
To know if the Departure Date is a working day for the user, you can use the CHelper.IsWorkingDayForUser function. This method returns true if a specific day is a working day according to the user's working schedule. Otherwise, returns false.
This function uses two parameters:
•idUser: Id of the user for which the working day is evaluated.
•dtDate: Date to evaluate.
The correct syntax is:
CHelper.IsWorkingDayForUser(idUser,dtDate)
Create an expression at the On Exit of the Register Travel Request Task.
Use the IsWorkingDayForUser function and use as input parameter the Departure Date of the case and the Id of the Case creator.
//Obtain creator id
var Creator=Me.Case.Creator.Id;
//Evaluate if the Depart date is working day for the user
if (CHelper.IsWorkingDayForUser(Creator,<TravelRequest.LeavingDate>)==false)
{
CHelper.ThrowValidationError("Depart day is non working.");
}
Verify if a date is a Working hour
Suppose you have a Process in which there is the need to set a meeting (a date and a specific hour).
You wish to validate if the date selected by the boss is a working hour for the user case creator in his/her working time schema.
To know if the Meeting hour is a working hour, you can use the CHelper.IsWorkingMinute function. This method returns true if a specific date falls under the organization's working time schema. Otherwise, it returns false.
This function uses two parameters:
•Me
•dtDate: Date to evaluate. It considers the calendar day as well as the time defined for it (hour of the day).
The syntax of the function is:
CHelper.IsWorkingMinute(Me,dtDate)
Create an expression at the On Exit of the Task were the meeting is scheduled.
Use the IsWorkingMinute function and use as input parameter the Meeting Date. Also, use a validation to notify the end user that the selected date is not a valid option (if that is the case).
//Evaluate if the Meeting hour is working hour
if (CHelper.IsWorkingMinute(Me,<Project.InitialMeeting>)==false)
{
CHelper.ThrowValidationError("Meeting hour is non working.");
}
Verify if a date is a Working hour for a specific user
Suppose you have a Process in which the user's boss needs to set a meeting with the user case creator (a date and a specific hour).
You wish to validate if the date selected by the boss is a working hour for the user case creator in our organization's working time schema.
To know if the Meeting hour is a working hour, you can use the CHelper.IsWorkingMinuteForUser function. This method returns true if a specific date falls under the given user's working time schema. Otherwise, it returns false.
This function uses two parameters:
•idUser: Id of the user for which the working minute is evaluated.
•dtDate: Date to evaluate. It considers the calendar day as well as the time defined for it (hour of the day).
The syntax of the function is:
CHelper.IsWorkingMinuteForUser(idUser,dtDate)
Create an expression at the On Exit of the Task were the meeting is scheduled.
Use the IsWorkingMinuteForUser function and use as input parameters the Case User creator and the Meeting Date. Also, use a validation to notify the end user that the selected date is not a valid option (if that is the case).
//Obtain creator id
var Creator=Me.Case.Creator.Id;
//Evaluate if the Meeting hour is in requester's working hour
if (CHelper.IsWorkingMinuteForUser(Creator,<Project.ResultsMeeting>)==false)
{
CHelper.ThrowValidationError("Meeting hour is not in requester's working time.");
}
Subtract Dates (difference between dates)
The following example illustrates how to find the difference between two dates: in days, years, hours or minutes. The function used in this example will return the time difference considering only working days.
The number of business days in a vacation request will be calculated using the vacation's leave and return dates.
1. On the fourth step of the Bizagi Process Wizard, select Activity Actions.
Select the Task where this action will be performed, and create an Expression On Save of the Activity.
2. Declare as variables the Start and Final dates of the vacation requested by clicking Variables and selecting Edit.
3. Initialize the variables with the values of the corresponding attributes.
4. The date difference will be stored in an attribute of the data model called NumberofBusinessDaysReq. Use the Data Model option to select the attribute.
5. Call the GetEffectiveDuration function to calculate the date difference. The function is found in the Date & Time Category.
The parameters of this function are: a Start date and an End date.
In this case these dates are the StartDate and FinalDate variables declared above.
//Initialize variables
Start=<VacationRequest.LeavingDate>;
End=<VacationsRequest.ReturningDate>;
//Calculate days requested and store them in an attribute
<VacationRequest.NumberofBusinessDaysReques>=CHelper.getEffectiveDuration(Me,Start,End)/480;
Note that the result of the expression above is divided by '480'.
The function returns the difference in minutes; therefore the result must be converted to days. By default, the working time schema has 8 hour working days (60 min per hour * 8 hours = 480 min). Since our result is needed in days we must divide by '480'. For a duration in minutes the division is unnecessary.
|
This calculation is done considering the organizational working time schema. |
Once the expression performs the calculation, it can be evidenced in the Number of business days requested control.
Subtract Dates based on the Working time schema of a User
The following example illustrates how to find the difference between two dates taking into account the working time schema of a specified user: in days, years, hours or minutes. The function used in this example will return the time difference considering only working days for the specified user.
The number of business days in a vacation request will be calculated using the vacation's leave and return dates.
1. On the fourth step of the Bizagi Process Wizard, select Activity Actions.
Select the Task where this action will be performed, and create an Expression On Save of the Activity.
2. Declare as variables the StartDate and FinalDate of the vacation requested by clicking Variables and selecting New.
3. Initialize the variables with the values of the corresponding attributes.
4. The date difference will be stored in an attribute of the data model called NumberofBusinessDaysReq. Use the Data Model option to select the attribute.
5. Call the GetEffectiveDurationForUser function to calculate the date difference. The function is found in the Date & Time Category.
The parameters of this function are: id of the User, a Start date and an End date.
In this case the user is the vacation requester. The StartDate and FinalDate are the variables declared above.
//Initialize variables
Start=<VacationRequest.LeavingDate>;
End=<VacationsRequest.ReturningDate>;
//Calculate days requested and store them in an attribute
<VacationRequest.NumberofBusinessDaysReques> = CHelper.getEffectiveDurationForUser(<VacationRequest.Requester.idUser>, Start, End) / 480;
Note that the result of the expression above is divided by '480'.
The function returns the difference in minutes; therefore the result must be converted to days. By default, the working time schema has 8 hour working days (60 min per hour * 8 hours = 480 min). Since our result is needed in days we must divide by '480'. For a duration in minutes the division is unnecessary.
|
This calculation is done considering the working time schema of the specified user. |
Once the expression performs the calculation, it can be evidenced in the Number of business days requested control.
Suppose that the last activity in a Vacation Request process must be completed within five days after the employee has returned from his/her vacations.
To calculate the completion due date, five days must be added to the value of the relevant data model attribute.
We will use a .NET function that allow us to add days to an attribute or variable:
ResultingDate=Date.AddDays(Value);
Other .NET date functions allow the addition of hours, months or years:
•ResultingDate=Date.AddHours(Value);
•ResultingDate=Date.AddMonths(Value);
•ResultingDate=Date.AddYears(Value);
If you wish to subtract hours, days, months or years then add negative values:
•ResultingDate=Date.AddDays(-Value);
To establish the Task duration, use the Estimated Solution date function.
1. In the fourth step of the Bizagi Process Wizard, select Activity Actions.
Click the Task where this action will be performed and create an Expression.
2. Declare two date time type variables:
•ReturningDate: Stores the date on which the employee will return from his/her vacations.
•FixedDate: Stores the derived completion due date and will be used to set the Task Duration
3. The Task duration will be calculated based on the attribute ReturningDate of the Data Model. The attribute's value is stored in the ReturningDate variable.
4. The Task due date will be set to five days after the returning date. The five days will be added to the obtained date value stored in the variable, ReturningDate.
The result will be assigned to the FixedDate variable.
5. Set the duration of the Task using the Estimated solution date function found in the Date & Time category.
The next image shows the expression:
//Obtain attribute value in a date time variable
ReturningDate=<VacationRequest.ReturningDate>;
//Calculate due date and store it in a date time variable
FixedDate=ReturningDate.AddDays(5);
//Assign duration based on the calculated date.
Me.EstimatedSolutionDate=FixedDate;
Click OK to save the changes.
Calculate a date based on the Working Time Schema
Suppose you need to calculate a date based on a given date plus a period of time. This can be done considering the Organizational Working time schema so that the addition excludes non-working periods of time.
The last activity in a Vacation Request process must be completed within a maximum time frame of five business days after the employee has returned from his/her vacations.
We will use the getEstimatedDate function, that returns a date, given an initial date (stored in the dtFromDate variable), a period of time (five days stored in the iDuration variable), and considers the Working Time Schema. The duration of this function must always be returned in minutes.
1. Follow the steps 1-4 of the previous example.
2. To calculate the new date use the getEstimatedDate function which can be found in the Date & Time function category.
The syntax for the function is:
CHelper.getEstimatedDate(Me,dtFromDate,iDuration)
This function does not consider the holidays configured for the organization. If your Business requirement need to include them, you can use the getSolutionDate function.
Both functions share the same attributes and the syntax for the function is:
CHelper.getSolutionDate(Me,dtFromDate,iDuration) |
Note that the expression above converts days into minutes.
The conversion is needed as the iDuration parameter expects the duration in minutes. By default, the Working time schema has 8 hour working days. The total minutes in five days are calculated using the formula: 60 minutes in an hour multiplied by 8 hours in a day, then multiplied by 5 days (i.e. 5*8*60)
Finally assign the task duration.
//Obtain attribute value in a date time variable
ReturningDate=<VacationRequest.ReturningDate>;
//Calculate due date and store it in a date time variable
// if you need to include the organizations's holidays use:
// FixedDate=CHelper.getSolutionDate(Me,ReturningDate,5*8*60);
FixedDate=CHelper.getEstimatedDate(Me,ReturningDate,5*8*60);
//Assign duration based on the calculated date.
Me.EstimatedSolutionDate=FixedDate;
Calculate a date based on a given user's Working Time Schema
Suppose you need to calculate the Solution date in an internal Claims & Complaints Management process, the user assigned to solve the issue has six days to send an answer according to his/her working time schema. The requester and the assigned user could have two different Working Time Schemas because the company has two divisions in two different countries and each user could belong to a different one.
To know the Answer Date, you can use the CHelper.getEstimatedDateForUser function. This method returns the end date given a start date and a number of minutes. This calculation is done by adding or subtracting the number of minutes to the start date parameter, and based on the working time schedule defined for a specific user.
This function uses three parameters:
•idUser: Id of the user for which the working time schema is evaluated.
•dtFromDate: Date to add or subtract the given number of minutes.
•iDuration: The number of minutes to add or subtract to the Start date.
The correct syntax is:
CHelper.getEstimatedDateForUser(idUser,dtFromDate,iDuration)
This function does not consider the holidays configured for the specific user. If your Business requirement need to include them, you can use the getSolutionDateForUser function.
Both functions share the same attributes and the syntax for the function is:
CHelper.getSolutionDateForUser(idUser,dtFromDate,iDuration) |
Create an expression at the On Exit of the Receive Request Task, the new expression will be last because the Assigned User is set in previous expressions.
Use the getEstimatedDateForUser function and use as input parameters the Assigned User's Id, the Opening Date and the six days represented in minutes (type 6*8*60). Add the result to the corresponding attribute in your Data model.
// Obtain the assigned user
var AssignedUser = <ClaimandComplaintRequest.Person.Id>;
// Calculate the Due date from the opening date adding 6 x 8 x 60 minutes
// if you need to include the user's holidays use:
// var AnswerDate = CHelper.getSolutionDateForUser(AssignedUser, <ClaimandComplaintRequest.OpeningDate>, 6*8*60);
var AnswerDate = CHelper.getEstimatedDateForUser(AssignedUser, <ClaimandComplaintRequest.OpeningDate>, 6*8*60);
// Set the Due date with function result
<ClaimandComplaintRequest.DueDate> = AnswerDate;
You can obtain the specific day, month and year of a date stored in an attribute. This is helpful in situations where you have to make calculations based on such specific information. For example the calculation of a person's age based on his/her birth date.
Suppose you need to calculate the age of the employee, requesting a vacation, based on the his/her birth date stored in the Employee Entity.
1. Define an expression in the activity where you wish calculate the employee's age in years.
2. In the Expressions Editor, add four variables as shown below:
3. Assign the value stored in the DateofBirth attribute to the BirthDate variable.
Likewise assign the current date to the TodayDate variable.
4. The age calculation requires the year portion of both the date of birth and today's date in number format.
Separate each date into three different segments of year, month and day.
Respectively assign the year portion of each date to the variables YearToday (Year of today's date) and YearBirth (year of birth's date).
Subtract the two years as shown below.
//Inititalize variables
BirthDate=<VacationRequest.Employee.DateofBirth>;
Todaydate=DateTime.Today;
//Separate Components
BirthDate=new DateTime(BirthDate.Year,BirthDate.Month,BirthDate.Day);
TodayDate=new DateTime(TodayDate.Year,TodayDate.Month,TodayDate.Day);
//Assign years
YearBirth=BirthDate.Year;
YearToday=TodayDate.Year;
//Calculate Age
<VacationRequest.Employee.Age>=YearToday-YearBirth;
Click OK to save the changes.
6. If you wish to validate whether today's date falls after the birth's date, you can add a condition as show below.
//Validate Birth Date
if (BirthDate<TodayDate)
{
//Calculate Age
<VacationRequest.Employee.Age>=YearToday-YearBirth;
}
When you need to use the dates in a Date-type attribute in a given string format (i,e., MM/dd/yyyy HH:mm:ss), you can use the CHelper.FormatDate function. This method returns the date in a string format given the date and a the format example. This is specially useful when you are trying to get data from Entities not related to the data model.
This function receives two parameters:
•oDate: Date attribute to be formatted.
•sFormat: this parameter contains a standard or a custom format pattern that defines the format required. For more information about Standard formats, refer to this link.
The syntax to be used is:
CHelper.FormatDate(oDate, sFormat)
Suppose you need to format the Request Date in order to fit the pattern Wednesday, November 1, 2017 11:35 AM.
1. Define an expression in the activity where you want to format the Date.
2. In the Expressions Editor, add the variables as shown below:
3. Assign the value stored in the VacationRequest.RequestDate attribute to the RequestDate variable.
4. Invoke the function using the pattern dddd, MMMM dd, yyyy hh:mm tt which matches with the required format.
Finally, assign it the result to the respective attribute in your Data Model.
//Inititalize variables
RequestDate = <VacationRequest.RequestDate>;
//Format Date
FormatedDate = CHelper.FormatDate(RequestDate, "dddd, MMMM dd, yyyy hh:mm tt");
<VacationRequest.RequestDateFormated> = FormatedDate;
Click OK to save the changes.
Convert a date from user time zone to server time zone
In global projects with users around the world, you can have users in different time zones. In some scenarios, it is important to get a date in the server's timezone compared to the user time zone. In cloud environments, for example, the server is always in UTC, therefore this function becomes handy. you can use the CHelper.ConvertUserTimeToServerTime function
This function receives two parameters:
•iIdUser: Id from the user whose timezone is used for calculation
•dDateTime: DateTime attribute to use in the calculation using the user's timezone
The syntax to be used is:
CHelper.ConvertUserTimetoServerTime(iIdUser, dDateTime)
This function returns a datetime attribute in the server timezone.
For example, you have a user in Bogota's timezone UTC -5, the user is the current logged user working on the task, and you want to get the expiry date of a product that is 72 hours from a specific date in the same timezone of the server, for example in cloud that is in UTC. So you can use the following expression:
Bizagi is built based on the Microsoft framework .Net. Therefore, SOME of the methods available from this framework can be used in Bizagi. For date operations you can use any of the following methods in your expressions:
•Add
•AddDays
•AddHours
•Addmiliseconds
•AddMinutes
•AddMonths
•AddSeconds
•AddTicks
•AddYears
•Compare
•CompareTo
•DaysInMonth
•Equals
•FromBinary
•FromFileTime
•FromFileTimeUtc
•FromOADate
•GetDateTimeFormats
•GetHasCode
•GetTypeCode
•IsLeapYear
•Parse
•ParseExact
•SpecifyKind
•Subtract
•ToBinary
•ToFileTime
•ToFileTimeUtc
•ToLocalTime
•ToLongDateString
•ToLongTimeString
•ToOADate
•ToShortDateString
•ToString
•ToUniversalTime
•TryFormat
•TryParse
•TryParseExact
All of these methods must be used using the following syntax:
date.method
For example:
//Date Time variable
var RequestDate= <CreditRequest.Customer.RequestDate>;
//Method
var NewRequestDate= RequestDate.AddMinutes(5);
|
All methods are case sensitive. Be Aware of upper and lower case letters in each method's name. |
For further information about these methods refer to the Microsoft .NET documentation (version 5.0):
https://docs.microsoft.com/en-us/dotnet/api/system.datetime?view=net-5.0#methods
Last Updated 1/6/2022 4:16:15 PM