Recurring Object

🤦 🤦 🤦 Combodo's customers only 😎 😎 😎

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.

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.

• 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.

• 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 FIXME
  • 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… then Delete… 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 same End date

The cron must be running on your iTop to create daily the missing objects on active Series.

Use the Standard installation process as for any extension.

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 (
                ),
            ),
        ),
    ),

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.

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.

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

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.

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

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 FIXME

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}