.. image:: ../img/tile_feeder_configuration.png
   :align: right

.. index:: !Time Slices

.. _Time Slices:

Time Slices
================================================================================

- :ref:`TS Configuration`
    - :ref:`TS Scheduling`
    - :ref:`TS Date Behavior`
    - :ref:`Value Manipulation In Future Time Slice (Migration) <TS Manipulation>`
    - :ref:`Value Change In Past Time Slice (Carry Forward) <TS Change Past>`


- :ref:`TS Auto Import`
- :ref:`TS Auto Export`

--------------------------------------------------------------------------------

.. _TS Frontend:

How do you know that the time slices feature is enabled..
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If at least one time slice was configured by a system administrator,
you may find the name and a **Current** indicator in the top right corner of the front end view. 

|image4|

--------------------------------------------------------------------------------

At any time, time slices can be switched by clicking the underlined name.
A window will pop up, where a drop down menu will list all configured slices.
Clicking **Use** will effectuate the switch to the selected time slice.

|image5|

--------------------------------------------------------------------------------

.. _TS Configuration:

Time Slice Configuration
--------------------------------------------------------------------------------

Time slices can be configured in the :ref:`Feeder Configuration`.

|image1|

.. hint::
	The number of time slices is not limited. Please note that
	with an increasing number of time slices, hardware demands increase as well.


--------------------------------------------------------------------------------

Clicking ``Create new time slice`` will bring up a window, where the settings are made.

|image2|

--------------------------------------------------------------------------------

The Name
  Should be self-explanatory and hint at the period covered (May 2017) or the time slice start date.

--------------------------------------------------------------------------------

The Creation Date
  Can be left empty. If so the time slice will be created right away.
  At creation the data of the hitherto most current timeslice is copied into the new time slice.

--------------------------------------------------------------------------------

The Default View From
  Can be left empty. Provides an opportunity to delay the display of the most current time slice (s. section below).

--------------------------------------------------------------------------------

.. _sorry:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. important::
  **The very first time slice must not have a default view in the future.** Simply leave the field empty.
  Otherwise this error window will show, as soon as you try to open the object / tile.
  
|image33|

.. hint::
	This screen may also show if the :ref:`Refresh Elasticsearch <object config refresh es>` button has not been clicked in v2! 

--------------------------------------------------------------------------------

Clicking ``Save`` will list the new time slice in the "Time Slices" category of the Feeder Configuration.

|image3|

--------------------------------------------------------------------------------

.. _TS Scheduling:

Planning the Automatic Time Slice Creation for the Future
--------------------------------------------------------------------------------

For this, please choose a **creation date in the future**.
Feeder will create the new time slice as soon as the given date is reached.
You will notice the planning in the time slice overview, as the particular time slice will have **a cross symbol** in the column **Already Created**.

.. _TS Default View:

Why the Default View field is quite handy
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Sometimes it is necessary that the *penultimate* time slice remains visible in the front end -
thus it remains flagged as the "Current" time slice - even though a consecutive time slice has already been created.
This may be the use case when  e.g. payroll data is delivered only at the end of a month (time slice) and still needs to be entered in Feeder.
To prevent the entry into the wrong (consecutive) time slice, system administrators can specify a custom date in the Default View field.

.. rubric:: Example

The current date is May 12th, 2017. In Feeder, various time slices are available.
The de-facto current time slice is the time slice of May (201705).
For this time slice, the system administrator entered a date into the Default View field: May 15th 2017.
This means that the time slice displayed in the front end by default is still the time slice of April (201704).
It is only as of May 15th, that the time slice of May will be displayed by default.

.. hint::
  In the front end, the current time slice is always flagged by a **Current** indication.

--------------------------------------------------------------------------------

.. _TS Date Behavior:

Display of Dates
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

When opening the time slices category, an overview of (scheduled) time slices with their start and creation dates will show.
As Feeder users happen to be geographically dispersed around the globe, it is important to guarantee **date relevance independent of time zones**.
Thus, Feeder adheres to the following date display rules.

  1. If a time slice creation date is in the **future**, the sole date information shows
  2. If a time slice creation date is in the **past**, the date will include additional time indication
  3. Since version 1.7, this time indication is set to be **00:00:00** to avoid "day gaps"

|image8|

.. rubric:: Background

Imagine a scenario where a time slice was created in Europe e.g. on January 13th 2015 at midnight in CET time zone.
For an American user - in **western** EST time zone - simultaneously working with Feeder, this creation date is display as if it were created on January 12th 2015 at 18:00 o'clock.
Due to 6 hours time shift, a "day gap" emerges.
In order to provide the American user with the actual true date as well, Feeder zeros the time indications and neglects the time zone indication.
In this way, web browsers will always display the correct date.

.. important::
  In case of older records and time slices in Feeder, these will still carry an old, detailed time stamp which would have to be corrected by an update.
  Users being in **eastern** time zones of the original creation time zone may happen to have a wrong date displayed. This can happen and is **not a bug**.


--------------------------------------------------------------------------------

.. index:: Time Slice Value Manipulation

.. _TS Manipulation:

Rule-based Value Changes In Future Time Slice
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

During the actual time slice creation process, the term *manipulation* refers to either *(re-)setting* attribute values.
To access this feature, settings can be found in the :ref:`Object Configuration <Object Config Basic Configuration>`.

|image6|

--------------------------------------------------------------------------------

A click on the cogwheel opens the Migration Script window.

|image7|

--------------------------------------------------------------------------------

.. rubric:: Sample Migration Script

.. code:: javascript

 	var tsStartDate = toDate(currentTimeSlice.getStartDate());
	var tDate = toDate(obj.get('TerminationDate'));

	if (tDate != null && tDate.getTime() < tsStartDate.getTime()) {

		return false; // deletes values
	}
	// resets values
	obj.set('ATTRIBUTE', null);


The sample Migration Script compares the time slice's start date with an object's (e.g. an SF_User's) termination date. If the employee left the company before the time slice's start date, the corres- ponding record is *deleted*. Otherwise the record will be kept in the system.
A targeted *reset* of a particular attribute can be done by obj.set('ATTRIBUTE', null);

--------------------------------------------------------------------------------

.. _TS Change Past:

Value Changes In Past Time Slice
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. rubric:: Scenario and System Behavior

Three time slices for May, June and July have been configured. The current month shall be June. Changing values of an employee in the past (May) will **not trigger an automatic value adaption** in the subsequent June and July time slices.

.. rubric:: Advise

Either this change can be revised manually in the subsequent time slices, which might turn out to be very cumbersome.
Or an alternative way is to use the :ref:`Carry Forward <Attribute Configuration Flagging>` attribute flag as of version 1.7.


--------------------------------------------------------------------------------

.. _TS Auto Import:

Automatic Imports to Time Slices
--------------------------------------------------------------------------------

The import of time slices is done via the **file name**:

- The file name has to begin with **TS[SLICEID]**.
- Use the time slice's start date and give it in **yyyyMMdd** format. This will be your SLICEID.

Hereafter, any file name may be given. For example:

- TS[20151101]-import.csv
- TS[20151101]import.csv

If a specified time slice does not exist, a precise error report will be sent via e-mail containing Feeder instance name, file name, used import setting, time slice, overall records processed, successful, warning, failed and duration.

.. important::

	Feeder requires a specific naming pattern to identify time slices!

|image9|

--------------------------------------------------------------------------------

To identify and import a file into all existing time slices, a generic regular expression is required. Please be aware that the opening bracket requires **masking with a backslash** to signal that Feeder is to expect a regular expression. After the closing bracket, any file name may be given (as usual):

- **TS\\[.+?]**-import.csv
- subfolder/**TS\\[.+?]**-import.csv

.. note::

	If you use **.+?-import.csv**, Feeder will import all files that end with *-import.csv*, e.g.:

	- my-import.csv
	- TS[20151201]-import.csv

--------------------------------------------------------------------------------

.. _TS Auto Export:

Automatic Exports from Time Slices
--------------------------------------------------------------------------------

The configuration of automatic exports from time slices is done by specifying the respective field in the **Auto Export tab**.

|image10|

Please note that **relative notation** is required:

- **0** 	: current time slice meaning as of the start date of a time slice
- **-1** 	: the month before
- **+1**	: the next month

Example:

If the time slices of the past 2 years shall be exported, it is required to list these explicitly and comma-separated: **0,-1,-2,...-24**. In case that *no time slice exists* e.g. when time slices only date back 1.5 years, then **no data** will be exported for *-19,-20,-21,-22,-23,-24*.

.. important::

	Use a **dynamic export name** to avoid overwriting export files! Therefore, utilize the **SLICE_ID**, e.g.: **export-[%SLICE_ID%].csv**

.. |image1| image:: ../img/feeder-mgmt/fc_category.png
.. |image2| image:: ../img/feeder-mgmt/time_slice_create_window.png
.. |image3| image:: ../img/feeder-mgmt/time_slice_listed.png
.. |image33| image:: ../img/feeder-mgmt/time_slice_error.png

.. |image4| image:: ../img/feeder-mgmt/time_slice_informatio  n.png
.. |image5| image:: ../img/feeder-mgmt/time_slice_switch.png
.. |image6| image:: ../img/feeder-mgmt/time_slice_migration_config.png
.. |image7| image:: ../img/feeder-mgmt/time_slice_migration_window.png
.. |image8| image:: ../img/feeder-mgmt/time_slice_date_behavior.png

.. |image9| image:: ../img/user-mgmt/ts_auto_import.png
.. |image10| image:: ../img/user-mgmt/ts_auto_export.png