Recurring Object
Combodo's customers only
- name:
- Recurring Object
- description:
- Recurring Object
- version:
- 1.1.1
- release:
- 2023-07-13
- itop-version-min:
- 2.3.0
- code:
- combodo-series
- state:
- stable
- diffusion:
- Client Store
- php-version-max:
- PHP 8.1
Automate creation of recurring objects, such as a recurrent Task. No need to clone your object manually every day, week or month, this extension will do it automatically for you.
Features
This extension allow you to define a recurrence on a object, so it will be automatically repeated on a defined frequency.
-
Classes on which recurrence can be defined are configurable.
-
The frequency can be every x days, every x weeks on defined weekdays, every x months on a particular day or yearly, where x is usually 1, but can be any positive number
-
The repetition can be limited by an ending date, a number of occurrences or unlimited
-
The initial object fields' values will be saved in the
template
of the series and used for automatic object creation. -
The template values can be modified to alter future creation of objects. Existing objects within the Series can be bulk-modified at the same time, this is iTop native.
Background Task
-
The repetition could have no time limit, nevertheless, it does not make sense to create an infinite number of objects from the beginning, so the configuration define an ahead window in days, beyond which objects aren't created upfront.
-
The cron will check daily if any new objects need to be created in the Series, according to the configuration parameters.
-
For creating the new object, the cron uses the values stored in the Series
template
.
Revision History
Date | Version | Description |
---|---|---|
2023-07-13 | 1.1.1 | * Add compatibility with iTop 3.1 modals creation |
2021-12-27 | 1.1.0 | * Add iTop 3 compatibility |
2019-05-31 | 1.0.5 | * Fix issues with iTop 2.5 and lower * Default hour for a serie is now correctly copied from object's start date attribute |
2019-05-16 | 1.0.4 | * Fix copy of n-n links * Add support for non-MySQL date format * Allow OQL JOIN on obj_class/obj_key * Fix regression introduced 1.0.3 : wrong repeat interval set |
2019-04-04 | 1.0.3 | Code hardening for corrupted data |
2019-03-29 | 1.0.0 | First version |
Limitations
-
Only one date is following the frequency, so if you have more than one field which should follow it, either:
-
Do not copy that field assuming it is not mandatory at creation = add it to the excluded fields of the configuration
-
Modify your dataModel. In the example of WorkOrder, add a duration field and remove the end_date or make it automatically computed based on duration.
-
-
A Series copy fields such as:
-
text: String, HTML, Text,…
-
number: Integer, Decimal,…
-
date: Date & DateTime
-
all scalar attribute should be supported
-
n:n relationships: AttributeLinkedSetIndirect
-
-
A Series does not copy fields such as:
-
Image, File, Caselog, Stopwatch,…
-
n:1 relationship: AttributeLinkedSet,
-
Attachments,
-
Consider non-listed type of attribute as not working.
-
Once a Series is created, it's not possible to modify its frequency. You have to
Edit the series…
thenDelete…
and create a new one. -
You cannot create a Series starting from an existing object. It's only possible during object creation.
-
While modifying a Series, you cannot modify n:n relationships
-
The default configuration does not generates a nice result, as it keep the same
Ticket
and the sameEnd date
Requirements
The cron must be running on your iTop to create daily the missing objects on active Series.
Installation
Use the Standard installation process as for any extension.
Configuration
This extension requires a configuration.
Here is the default one:
'combodo-series' => array ( 'create_chunk_size' => 8, 'create_ahead_max_days' => 60, 'targets' => array ( 0 => array ( 'class' => 'WorkOrder', 'date_attcode' => 'start_date', 'excluded_attributes' => array ( ), ), ), ),
parameter | Description |
---|---|
create_chunk_size | Max number of objects that will be created ahead of today |
create_ahead_max_days | Last created object has a date before (now + this parameter) |
The two parameters above, apply to all series. On first creation
and when the cron runs, the extension create new objects, as long
as the next object to be created is before (now +
create_ahead_max_days
* days) and there are less than
create_chunk_size
objects created in advance.
parameter | Description |
---|---|
class | Name of a class |
date_attcode | code of a field of that class, of type Date or
DateTime This field will be set according to the recurrence |
holidays_query | Any OQL returning objects of the class Holiday |
excluded_attributes | array of codes of fields of that class which should not be copied using the series template |
Usage
Creating a Series
Assuming in your iTop configuration, WorkOrder is configured for recurrence, then create a Work Order:
Check the checkbox and it pops-up a recurrence form:
You can set a weekly recurrence, with one or multiple days within a week
You can set monthly recurrence, with 2 options
Assuming the starting date of the recurrence is the Tuesday 2nd of
April 2019
-
day of month
means “Every 2nd of each month” -
day of week
means “Every first Tuesday of each month”
You can also set
-
a daily recurrence, every other day, or every x days.
-
or a yearly recurrence, always on the same date of the year (29th of February might leads to unpredictable results)
If you change the date in the pop-up recurrence form, it will
copy the changed date on the object creation form under it.
Be cautious, if you do the opposite, it does not refresh the
recurrence starting date, which remains as you set it.
Example: daily recurrence with start date on 2019-04-10, then you
modify the created object to 2019-04-05 and submit. The series will
start with those dates:
If you have defined linked objects (n:n relations) within the
object creation, then they will be part of the template, if you
modify them after the creation, then they won't be in the Series
template
. Linked objects defined in the
template
cannot be modified later, see Limitations.
Modifying a Series
Display any object member of a given series. When an object is part of a Series, there is a little icon just after its name which display a tooltip:
and in the actions, select the Edit the series…
In the new screen, you can set a starting date, so you will modify the Series template and bulk modify all objects of the series after that date:
In the above example, one of the created object was manually deleted, which explain why 9 where created and we are going to modify 4 out of 8
The Modify…
button display a bulk modify screen of
the selected objects
Stop a Series
Display any object member of a given series, and in the actions,
select the Edit the series…
In the new screen, set the date after which the Series will be stopped, and press the “Delete…”
-
It may suppress already created objects or not, depending on when you decided to end it.
-
Once you have “deleted” a series, even if you did not delete any object, the Series is stopped and no further objects will be created on that Series.
Exclude Holidays
If you add the parameter holidays_query in the configuration file, a new check box 'Exceptions“ will appear for each series definition allowing you to exclude holidays
Troubleshooting / Q&A
Q: Objects are not automatically created.
A: Is the cron running and when is the
next_run_date for the Background Task
SeriesOfflineCreation
?
SELECT * FROM `priv_backgroundtask` WHERE class_name='SeriesOfflineCreation'
When running test, you can delete this row to force that Task to run again immediately, as long as your cron is running.
Q: I have modified the first (or the last,
or the next to come) object of my Series, but the
newly created objects aren't taking into account my
change.
A: To change the to-be-created objects, you have to modify the
Series, through the action Edit the series…
Q: I have delete the last object of my Series, will it
be recreated by the cron?
A: No, the Series knows the date of the last object it has created
and whatever you do with this last created object, deletion or date
modification, it will continue the Series as if you had done
nothing.
Q: What if there is a uniqueness constrains on a field
which is part of the Series template?
A: We haven't tested yet, but in theory only the first object will
be created and the Series will fail with error message(s), the cron
hopefully will not fail and just log error messages, to be checked
Q: As an Administrator, can I check all active
Series?
A: Yes, this can be done in OQL. The content of the
recurrence
and the template
are in json,
but it's more or less human readable.
SELECT SeriesDefinition WHERE complete=0 AND target_class='WorkOrder'
Q: The background task SeriesOfflineCreation has not
been running for a long period, how to restart object creation from
today only, without creating object in the past
A: This needs to be done in SQL. In the below example, I am asking
all series to start again from 2019-04-16, replace by yesterday's
date.
UPDATE `series_definition` SET `created_last` = '2019-04-16' WHERE `series_definition`.`complete` = 0
Then start again the background task and your cron.php if it wasn't running either.
Q: How to retrieve all the Objects associated with an
active series
A: This can only be done in SQL for now. Example for WorkOrders
part of an active series starting after a given date.
SELECT * FROM workorder AS w JOIN series_occurrence AS o ON o.obj_key=w.id JOIN series_definition AS s ON o.series_id = s.id WHERE s.complete=0 AND w.start_date > '2019-04-14'
Since 1.0.4 you can use the below OQL
SELECT WorkOrder AS W JOIN SeriesOccurrence AS O ON O.obj_key = W.id JOIN SeriesDefinition AS S ON O.series_id= S.id WHERE S.complete='no' AND O.obj_class='WorkOrder'
Before 1.0.4 the OQL will fail with this error.
An error occured while running the query: Unknown key in join condition (left expression), found 'obj_key' in: [...], expecting {series_id}