Application-Bus-Time2 commands

Read this topic to know about the available Business Time application commands.

Application-Bus-Time2-Add

The Application-Bus-Time2-Add command adds the requested offset to the start time and returns a timestamp representing the time calculated. Use this command to recalculate time into the future.

Important

The Application-Bus-Time2-Add command returns 1/1/1970 if the input date does not fall within Business Time Segment start and end date range. 

For example, the date 1/1/1970  is returned if you enter a date after the end date of the last business segment.

Related topics

Business-Time-2-0-commands

Old-Business-Time-commands

Syntax

Application-Bus-Time2-Add *"*startTime" ["<amount>" ["<amountUnits>" ["<businessTimeSegmentName1>" " <businessTimeSegmentName2>" . . . ]]] 

Description of parameters

  • startTime—Required parameter. It is the starting time to which to add business time. It must be a value such as a field reference ($<fieldName>$). Other fields are optional and use the default value if not provided. You can specify multiple business activity names.
  • amount—Specifies an amount of time to offset the start time by. It can be an integer value of 0 or greater. If not specified, this parameter defaults to 1. You can use 0 to indicate the next available time. For example, if your business hours are 8:00 A.M. to 5:00 P.M. and the Start Time in Application-Bus-Time2-Add, Application-Bus-Time2-Assoc-Add, and Application-Bus-Time-Add commands is 7:00 A.M., the return value is 8:00 A.M.In the previous versions, this parameter was known as <offset>.
  • amountUnits—The unit of time, which can be set to 1 for seconds, 2 for minutes, 3 for hours, or 4 for days. Any other setting reverts to hours (3).
  • businessTimeSegmentName—Indicates which entry in the Business Time Segment form contains a definition for the activity to use for this calculation. You can specify multiple business activity names. Omitting this value specifies that no business activity is used for this calculation.

Example

To add one day, use the following calculation: $PROCESS$ Application-Bus-Time2-Add "$<fieldName>$" "<amount>" "<amountUnits>"

This adds one day to the value in <fieldName>. In the example, <fieldName> is <startTime>. <amount> (offset) is set to 1, and <amountUnits> is set to 4 (representing days), thus adding 1 day to the calculation.

The final syntax looks like the following:

$PROCESS$ Application-Bus-Time2-Add "$8/26/2004$" "1" "4"

Application-Bus-Time2-Diff

The Application-Bus-Time2-Diff command computes the difference between the start time and the end time. It returns an integer representing the difference in seconds. Use this command to compare two different times (start time and end time) to get the actual business time.

Syntax

Application-Bus-Time2-Diff "<startTime>" "<endTime>" ["<businessTimeSegmentName1>" "<businessTimeSegmentName2>" . . . ]]

Description of parameters

  • startTime—Required parameter. It is the starting time to which to add business time. It must be a value such as a field reference ($<fieldName>$). Other fields are optional and use the default value if not provided. You can specify multiple business activity names.
  • endTime—Required parameter. It is the ending time of the interval of which to calculate the difference. Other fields are optional and use the default value if not provided. You can specify multiple business activity names.
  • businessTimeSegmentName—Indicates which entry in the Business Time Segment form contains a definition for the activity to use for this calculation. You can specify multiple business activity names. Omitting this value specifies that no business activity is used for this calculation.

Application-Bus-Time2-Subtract

The Application-Bus-Time2-Subtract command subtracts the requested offset from the start time and returns a timestamp representing the time calculated. Use this command to recalculate the time in the past.

Important

The Application-Bus-Time2-Subtract command returns 1/1/1970 if the input date does not fall within Business Time Segment start and end date range. 

For example, the date 1/1/1970  is returned if you enter the date before the start date of the earliest business time range.

Syntax

Application-Bus-Time2-Subtract "<startTime>" ["<amount>" ["<amountUnits>" ["<businessTimeSegmentName1>" "<businessTimeSegmentName2>" . . . ]]] 

Description of parameters

  • startTime—Required parameter. It is the starting time from which to subtract business time. It must be a value such as a field reference ($<fieldName>$). Other fields are optional and use the default value if not provided. You can specify multiple business activity names.
  • amount—Specifies an amount of time to offset the start time by. It can be an integer value of 0 or greater. If not specified, this parameter defaults to 1. You can use 0 to indicate the next available time. For example, if your open hours are 8:00 A.M. to 5:00 P.M. and the Start Time in Application-Bus-Time2-Add, Application-Bus-Time2-Assoc-Add, and Application-Bus-Time-Add commands is 7:00 A.M., the return value is 8:00 A.M.In the previous versions, this parameter was known as <offset>.
  • amountUnits—The unit of time, which can be set to 1 for seconds, 2 for minutes, 3 for hours, or 4 for days. Any other setting reverts to hours (3).
  • businessTimeSegmentName—Indicates which entry in the Business Time Segment form contains a definition for the activity to use for this calculation. You can specify multiple business activity names. Omitting this value specifies that no business activity is used for this calculation.

Example

To subtract one day, use the following calculation: $PROCESS$ Application-Bus-Time2-Subtract "$<fieldName>$" "<amount>" "<amountUnits>"

This subtracts one day from the value in <fieldName>.

In the example, <fieldName> is <startTime>. <amount> (offset) is set to 1, and <amountUnits> is set to 4 (representing days), thus subtracting 1 day from the calculation.

The final syntax looks like the following:

$PROCESS$ Application-Bus-Time2-Subtract "$8/26/2004$" "1" "4"

Application-Bus-Time2-Get-Next-Window

The Application-Bus-Time2-Get-Next-Window command returns the start of the next available or unavailable time segment that is <duration> seconds long. If <duration> is 0 (the default), the command returns the start of the available time segment or the start of unavailable the time segment.

Additionally, depending on the <windowFlag>, the command returns one-time segment or all the time segments between <startTimeRange> and <endTimeRange>. 

Syntax

Application-Bus-Time2-Get-Next-Window "<startTimeRange>" "<endTimeRange>" ["<duration>"] ["<windowFlag>"] ["<businessTimeSegmentName1>" "<businessTimeSegmentName2>" . . . ]

Description of parameters

  • startTimeRange—A date and time value that defines the start of a search for a time window.
  • endTimeRange—A date and time value that defines the end of a search for a time window.
  • duration—Specifies the size of the time segment in seconds. Specify 0 to return the next time segment.
  • windowFlag—A bitmask value with Bit 0 and Bit 1.
    Bit 0 indicates the beginning of an available or unavailable time segment. The values are 1 (available) and 0 (unavailable).
    Bit 1 indicates whether to retrieve just one segment or all the segments between the start and end times. The values are 1 (retrieve all segments) and 0 (retrieve one segment). The value returned in this case is a semicolon-separated list of values.
  • businessTimeSegmentNameIndicates which entry in the Business Time Segment form contains a definition for the activity to use for this calculation. You can specify multiple business activity names. Omitting this value specifies that no business activity is used for this calculation.

Application-Bus-Time2-Get-Free-Window

The Application-Bus-Time2-Get-Free-Window command returns the start of the next available or unavailable free time segment at the same level or a higher level that is <duration> seconds long.

A free time segment at Level <level> and Duration <duration> is one where no other time segment at the same or higher level as <level> overlaps, or starts or ends in the <duration> of this time segment.

After a free time segment is obtained, it can be created as available or unavailable. The default value for <duration> is 0, which returns the next available time segment.

This command considers all Business Time Segments at a certain level or above and treats them as unavailable, regardless of whether they are available or unavailable. If Level 1 and 2 time segments are present, they are always considered and are taken as available and unavailable, respectively. For more scenarios, see Application-Bus-Time2-Get-Free-Window-scenarios.

Syntax

Application-Bus-Time2-Get-Free-Window "<startTimeRange>" "<endTimeRange>" ["<level>"] ["<duration>"] ["<earliestStartTime>"] ["<latestEndTime>"] ["<businessTimeSegmentName1>" "<businessTimeSegmentName2>" . . . ]

Description of parameters

  • startTimeRange—A date and time value that defines the start of a search for a time window.
  • endTimeRange—A date and time value that defines the end of a search for a time window.
  • level—Indicates the level of the time segment to be scheduled. The value can be an integer from 1 through 1000.
  • duration—Specifies the size of the time segment in seconds. Specify 0 to return the next time segment.
  • earliestStartTime—Working in conjunction with the <latestEndTime>, specifies the time range within which the free window should exist. The specified duration (<duration> parameter) must be less than this range.
    For example, if the earliest time is 4:00 P.M. and the latest end time is 10:00 P.M., a window is returned that is <duration> seconds long and starts after 4:00 P.M., even if a window exists before 4:00 P.M. If the duration is greater than the specified time range, no value is returned. If the <earliestStartTime> is not specified, the default of 0 hours (the beginning of the day) is used.
  • latestEndTime—Working in conjunction with the <earliestStartTime>, specifies the time range within which the free window should exist. The specified duration (<duration> parameter) must be less than this range. For example, if the earliest time is 4:00 P.M. and the latest end time is 10:00 P.M., a window is returned that is <duration> seconds long and starts after 4:00 P.M., even if a window exists before 4:00 P.M. If the duration is greater than the specified time range, no value is returned. If the <latestEndTime> is not specified, the default of 24 hours (midnight) is used.
  • businessTimeSegmentName—Indicates which entry in the Business Time Segment form contains a definition for the activity to use for this calculation. You can specify multiple business activity names. Omitting this value specifies that no business activity is used for this calculation.

Business Segment-Entity Association commands

If the Business Segment-Entity Association form contains entries for time segments, you can use the following commands in place of the Application commands described in the previous section. The following commands contain EntityID parameters so that you do not need to query the Business Segment-Entity Association form.

Application-Bus-Time2-Assoc-Add

Use the following syntax for the Application-Bus-Time2-Assoc-Add calculation:

Application-Bus-Time2-Assoc-Add "<startTime>" ["<amount>" ["<amountUnits>" ["<businessTimeSegmentName1>" "<businessTimeSegmentName2>" . . . [-e "EntityID1" "EntityID2"... ]]]]

Application-Bus-Time2-Assoc-Diff

Use the following syntax for the Application-Bus-Time2-Assoc-Diff calculation:

Application-Bus-Time2-Assoc-Diff "<startTime>" "<endTime>" ["<businessTimeSegmentName1>" "<businessTimeSegmentName2>" . . . [-e "EntityID1" "EntityID2"... ]]

Application-Bus-Time2-Assoc-Subtract

Use the following syntax for the Application-Bus-Time2-Assoc-Subtract calculation:

Application-Bus-Time2-Assoc-Subtract "<startTime>" ["<amount>" ["<amountUnits>" ["<businessTimeSegmentName1>" "<businessTimeSegmentName2>" . . . [-e "EntityID1" "EntityID2"... ]]]]

Application-Bus-Time2-Assoc-Get-Next-Window

Use the following syntax for the Application-Bus-Time2-Assoc-Get-Next-Window calculation:

Application-Bus-Time2-Assoc-Get-Next-Window "<startTimeRange>" "<endTimeRange>" "<duration>" "<windowFlag>" ["<businessTimeSegmentName1>" " <businessTimeSegmentName2>" . . . [-e "EntityID1" "EntityID2" . . . ]]

Application-Bus-Time2-Assoc-Get-Free-Window

Use the following syntax for the Application-Bus-Time2-Assoc-Get-Free-Window calculation:

Application-Bus-Time2-Assoc--Get-Free-Window "<startTimeRange>" "<endTimeRange>" "<level>" "<duration>" "<earliestStartTime>" "<latestEndTime>" ["<businessTimeSegmentName1>" "<businessTimeSegmentName2>" . . . [-e "EntityID1" "EntityID2" .. . ]]

Business Time command parameters

Following are the parameters for the Business Time commands. Each parameter must be set apart in double quotation marks.

Parameter

Definition

businessTimeSegmentName

Indicates which entry in the Business Time Segment form contains a definition for the activity to use for this calculation. You can specify multiple business activity names. Omitting this value specifies that no business activity is used for this calculation.

duration

Specifies the size of the time segment in seconds. Specify 0 to return the next time segment.

earliestStartTime

Working in conjunction with the <latestStartTime>, specifies the time range within which the free window should exist. The specified duration (<duration> parameter) must be less than this range. For example, if the earliest time is 4:00 P.M. and the latest end time is 10:00 P.M., a window is returned that is <duration> seconds long and starts after 4:00 P.M., even if a window exists before 4:00 P.M. If the duration is greater than the specified time range, no value is returned. If the <earliestStartTime> is not specified, the default of 0 hours (the beginning of the day) is used.

endTime

Indicates the ending time of the interval to calculate the difference.

endTimeRange

Defines the end of a search for a time window in a date and time value format.

entity

Indicates an entity linked to a schedule. It can be an asset, individual, group, company, location, or anything you want to link a schedule to.

holidayScheduleName

For old Business Time commands, indicates which entry in the Business Time Holidays form contains a definition for the holiday schedule to use for this calculation. Omitting this value specifies no holidays.

latestEndTime

Working in conjunction with the <earliestStartTime>, specifies the time range within which the free window should exist. The specified duration (<duration> parameter) must be less than this range. For example, if the earliest time is 4:00 P.M. and the latest end time is 10:00 P.M., a window is returned that is <duration> seconds long and starts after 4:00 P.M., even if a window exists before 4:00 P.M. If the duration is greater than the specified time range, no value is returned. If the <latestEndTime> is not specified, the default of 24 hours (midnight) is used.

level

Indicates the level of the time segment to be scheduled. The value can be an integer from 1 through 1000.

amount

Specifies an amount of time to offset the start time by. The amount> can be an integer value of 0 or greater. If not specified, <amount> defaults to 1. You can use 0 to indicate the next available time. For example, if your open hours are 8:00 A.M. to 5:00 P.M. and the Start Time in Application-Bus-Time2-Add, Application-Bus-Time2-Assoc-Add, and Application-Bus-Time-Add commands is 7:00 A.M., the return value is 8:00 A.M.

In previous versions, <amount> was known as <offset>.

amountUnits

Specifies the unit of time, which can be set to 1 for seconds, 2 for minutes, 3 for hours, or 4 for days. Any other setting reverts to hours (3).

startTime

Indicates the starting time to which to add business time.

startTimeRange

Defines the start of a search for a time window, which is indicated by a date and time value.

windowFlag

Indicates a bitmask value with:

  • Bit 0—Indicates the beginning of an available or unavailable time segment. The values are 1 (available) and 0 (unavailable).
  • Bit 1—Indicates whether to retrieve just one segment or all the segments between the start and end times. The values are 1 (retrieve all segments) and 0 (retrieve one segment). The value returned in this case is a semicolon-separated list of values.
workdayScheduleName

For old Business Time commands, the identifier indicates which entry in the Business Time Workdays form contains a definition for the work schedule to use for this calculation. Omitting this value specifies open 7 days a week, 24 hours a day.

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*