The scheduling service provides you with the opportunity to create scheduled tasks that automatically execute an action at the specified time in accordance with the specified conditions. With scheduled tasks you can perform such automatically triggered actions as sending e-mail, generating text files, and changing data card information. You can define the task type and when to run it with the Schedulable task editor.

As you open the Schedulable tasks view, the Edit Schedulable Tasks Table lists the tasks set up, if any. Scheduled tasks have a green icon. Tasks that have never been run, have a red icon. 

The Schedulable tasks view lets you delete idle tasks by clicking the trashcan icon. To edit an existing task, click its name. You can also create new tasks by clicking the Add a new task button.

Creation of Schedulable Tasks

To access the Schedulable task editor, open the Schedulable tasks section of the administration user interface and click Schedulable Tasks. At the top left of the Edit schedulable tasks view, click Add a new task. Select the type of task. The Schedulable task editor opens in the working area.

All schedulable tasks need to have the following information specified:

• Description – Enter a description for the task, which is displayed in the Edit schedulable tasks view. You can specify the use of the task and differentiate tasks based on the same task type.
• User – Select the user whose permissions the task is running with.
  Scheduling – Activate the task by setting the Scheduling on. If you leave the scheduling off, ESM saves the task but does not execute it.
• Run – Define when the task is executed.
  • Every day: Select every x minutes or hours the task is executed. Starting from lets you decide the starting time and also schedule different tasks to be run on different times so that they don’t overlap or at least mostly are run on a different time if you wish.
  • Every week: Select which weekdays the task is executed on. The time (@hh:mm) lets you decide the starting time and also schedule different tasks to be run on different times so that they don’t overlap or at least mostly are run on a different time if you wish.
  • Every month: Select the day of the month the task is executed on. The time (@hh:mm) lets you decide the starting time and also schedule different tasks to be run on different times so that they don’t overlap or at least mostly are run on a different time if you wish.
  • Every quarter: Select which months of the quarter (1,2,3) and which day of that month the month the task is executed on. The time (@hh:mm) lets you decide the starting time and also schedule different tasks to be run on different times so that they don’t overlap or at least mostly are run on a different time if you wish.
• Task-specific properties is also required.

The task specific Task properties are shown in the working area below the scheduling. Each task has different set of task properties.

Define the task specific properties based on the selected task type. Required properties are shown immediately when the view is opened. Optional properties can be added using the add property button. In practice, each property consists of a name–value pair that refines or alters the task behavior. Some properties have a user interface, which helps you to select the value from a dropdown menu or by clicking a radio button.

The question mark icon opens help text for the property. Deleting a property is done by clicking the delete icon (x) on the right side of the property.

Manually added property names and values are case-sensitive and must be precise. The setting names, for instance, must be denoted exactly as indicated in the help text. 

The task types are described below.

CSVImportTask (CSV connector) 

CSV connector for importing data from external systems. CSV file can be fetched from a local disk or from an SFTP server. The file must be compliant with RFC 4180 standard. Supports SFTP with public key authentication and password authentication. The file to be imported must have .csv as the file name extension. 

ChatIntegration Scheduled Task

Use this tasks in combination with Efecte Multi-Room Chat powered by Giosg Live platform. All chat conversation records can be fetched from the Giosg Live platform to Efecte Service Management for reporting and audit purposes. This scheduled task in Efecte Service Management takes care of requesting and storing the data. Select the time interval of fetching the information to be once per day, preferably during the early morning such as 04.00 to 06.00. Fetching the information from the previous business day will take some time to be imported and therefore running it more often will impact performance of the overall solution negatively. 

DateCheckerTask

With the DateCheckerTask task, you can get scheduled e-mail reports or files concerning data cards whose date fields match the criteria set. To function as intended, the task needs the properties described in required properties below. Optional properties are described in the optional properties table.

Required DateCheckerTask properties:

Optional DateCheckerTask properties:

EventTask 

To manage the execution of data card events, such as Mail and Save events, you can enable or disable event execution through this task's configuration settings. The EventTask requires a user (whose permissions are used for running the task) and scheduling rules. 

Starting with ESM 2023.3, if there are errors in searching for the event target (which determines which events the EventTask will execute), usually due to configuration issues, these errors will not hinder the task from locating and executing events that are correctly configured. In such scenarios, the event will be marked as "partially succeeded" and a notification will be displayed in the EventTask user interface:

For executing the message queue’s message sending. If there are any messages in the queue, this task triggers sending of the messages. More information in the message queue section.

MessageQueueTask

For executing the message queue’s message sending. If there are any messages in the queue, this task triggers sending of the messages. More information in the message queue section.

LicenseMonitoringTask 

A software asset management task for tracking free and used software licenses of a company. 
It sends an e-mail report of software license violations, i.e., installed software without license and software with more installations than license permits.  Required properties are described in the table below.

Technical details

LicenseMonitoringTask generates a report of all the Monitored Software Installations that do not have a License Pool. A Monitored Software Installation data card does not have a License Pool, if the data card’s attribute LicenseManagementLicenseReference does not refer to a License Pool. The report also states which the computer that has this software installed is.

The generated report also informs which of the License Pools have too many installations. This is done by finding the License Pools that have more Monitored Software Installations referring to them than the value of attribute LicenseManagementLicenseAmount.

MailTask 

MailTask is meant for creating data cards from e-mail messages. It reads email from an inbox, which has to be based on an email account (shared mailboxes are not supported), imports the email into ESM, attaches the email and attachments to a data card and then deletes the message from the mailbox.

The following tables describe the MailTask properties. 

AutoUpdateMapping Examples

This section contains a few configuration examples for autoUpdate settings. 

Example 1: In this example there’s first the configuration, then the imported mail, and at the bottom there’s a screenshot image of the created data card:

Example 2:

Example 3:

Example4:

Example 5:

ReportExportTask 

ReportExportTask can be used to export a selected report into a file in a desired format. Detailed reports with table output are supported as well as graphical reports.

The output file format for detailed reports with table output can be configured with an XSLT file. By default, CSV and HTML exports are built-in, but several other file formats are possible as well. Other modes (minimal, referrers, full) for detailed reports are not supported.

Graphical reports produce a file containing a PNG-image.

Technical Details:

XSLT transform can be used to export ESM result xml into any text based file format – for example, CSV, different xml, or html. XSLT transform supports XSLT 1.0 and XPath 1.0.

Besides normal properties, ReportExportTask can also be used to define parameters for XSLT transform. When the parameters are passed to the XSLT transform file, the xslt. prefix is stripped off from the parameter names (e.g., xslt.some.parameter will become some.parameter in XSLT transform). The parameters supported depend entirely on the XSLT used.

Data from multivalue references will be grouped on a single xml multivalue-element or in a single column in csv-file. The original reference cannot be identified.

The CSV transform implemented by ESM supports the following parameters:

TIP! The format used for CSV files is described in detail in RFC 4180, http://www.rfc-editor.org/rfc/rfc4180.txt 

For example, to define a global separator value for the CSV transformation, add a platform setting with name result.export.xslt.csv.separator.value .

Diagram of search result XML schema used in ReportExportTask:

ReportMailTask

ReportMailTask can be used to generate an email which contains multiple reports created through old Efecte Report Wizard (not recommended to be used anymore). Mail server configurations are defined by Platform Settings. Sender, receiver(s), subject and mail content are configured by task properties.

• ReportMailTask supports only reports in Efecte ITSM 6 format.
• Detailed reports with table output are supported as well as graphical reports.
• The output file format for detailed reports with table output can be configured with an XSLT file. By default, CSV and HTML exports are built-in, but several other file formats are possible as well. Other modes (minimal, referrers, full) for detailed reports are not supported.
• Graphical reports produce PNG-images.
• Group by –reports are not supported.
• Following properties are not configurable for ReportMailTask: report.id, target.file.dir, target.file.name

Configuration is very similar to ReportExportTask. Following tables contains only additional options.

DataCardsArchiverTask

DataCardsArchiverTask is meant for exporting data cards to the file system or directly to an external system by using https request method. Both methods (file and https request) use Efecte ESM standard XML-format, which might need to be converted to the target system data model format.

Only Efecte Administrators can save list views to the Archive section of the working space. List reports that are saved to the Archive section can be archived by using the DataCardsArchiverTask scheduled task.

The archiver task does not archive file attachments or emails that are linked to the archived data cards. Even if the data cards are deleted, the files (emails and file attachments) of the deleted data cards will remain in the file system unless they are deleted with another scheduled task: CleanRemovedFilesTask. Please note also that the file archiving nor the https request method do not send file attachments nor emails to the defined folder structure or to the third-party system.

Example when connection to another ESM

• External system address e.g. https://environment.efectecloud.com/api/itsm/dataCardImport.ws?folderCode=alerts&createDataCards=true&updateDataCards=true&createEmptyReferences=true
• External system connection parameters e.g. 
  • acceptSelfSignedCertificates=true ,connectionRequestTimeout=60,connectTimeout=60,socketTimeout=60

Archive type: file

When using the file in Archive type, the created ESM entity XML file is stored in the server file system. Property File location must point to the existing directory where the ESM permission has access to write a data. A filename is generated as [task_id]_[time_stamp]_[report_name].xml. Files are not deleted.

Archive type: https request

When using https request, the generated ESM entity XML file will be sent to a third-party system as https request. Please check the table (Table: Required DataCardArchiverTask properties, when Archive type is ‘https request’) of required properties when using https request archiving type.

The https request method uses MessageQueue. Once the DataCardArchiverTask is executed, the XML to third-party system is sent immediately. If the transmission of the https request fails e.g. third-party system is not responding, the request is stored in the message queue and will be executed again when MessageQueueTask is running next time. In order to make https request work correctly, Efecte admin shall configure the MessageQueueTask.

Files are deleted when export is completed successfully.

External system expected response

The property External system expected response defines the combination of expected response codes and messages from the external system.

Expected Response Code: The code indicates the responded code from the external system whether the request is accepted or declined. e.g. 200, 404.

Expected Response Message: ESM checks response message from received responses. The checking of message content is handled by regular expressions.

Used format is:

code1=message1,code2=message2 (using comma as delimiter)

Example 1: 200=,404=Nothing to be archived

Both 200 and 404 are accepted as response code. For code 200, the response message should be empty or null. For code 404, text "Nothing to be archived" should be included in the response message.

Example 2: 200=.+

Only 200 is accepted as response code. Any content in the response message is accepted.

Logging

DataCardsArchiverTask logs its activities in info and debug level to the itsm.log. For getting out more detailed communication between task and the external system you can set also log level debug for package com.efecte.queue.

CleanRemovedFilesTask

CleanRemovedFilesTask is meant for cleaning unreferenced / orphaned files such as emails and attachments from the filesystem. If this task is not run, those resources will remain in the filesystem using up the disk space even after a data card referring to the resources is deleted.

This schedulable task is enabled and run daily by default. The task scheduling can be either rescheduled or disabled by Efecte administrator from Scheduled tasks.

Please note: This function does not delete orphan files that have been in the system before the update into ESM version 2018.3.2.

Editing and Deleting Scheduled Tasks

You can view and modify all created tasks in the Edit schedulable tasks view. To navigate to the view, open the General tab in the Maintenance view and click Schedulable Tasks. In the view, click the name of the task you wish to edit.

The Edit schedulable tasks view opens in the working area, including the Schedulable task editor and the Task properties view. Make the modification to the existing information and click Save to save the modified scheduled task.

You can delete idle tasks from the Edit schedulable tasks view. Select the Remove checkboxes next to the task(s) you want to delete and click the Remove button to complete the action.

Provisioning Tasks

Provisioning tasks are automated, schedulable tasks meant for importing user identity data into Efecte Service Management Tool using either the Lightweight Directory Access Protocol (LDAP) interface for Active Directory, OpenLDAP, IBM LDAP, FreeIPA or either Microsoft Graph API for Microsoft Azure AD. Efecte Provisioning Engine (EPE) within our IGA solution, accelerating the provisioning of users (also called fulfilment in the area of Identity and Governance Administration). EPE will work as a true parallel processing method allowing multiple scheduled and event-based access right changes.

Note! Since ESM 2023.3, the provisioning tasks are located on the IGA tab – not anymore on the Schedulable tasks tab.

The imported configurations are stored in the EPE-Master database (Efecte Provisioning Engine - Master), not in the Efecte Service Management (ESM) database. Identity Attribute Mapping and Access Rights Mapping are stored in ESM and are affected by changing templates and folders in ESM.

To connect the Efecte Service Management tool and Efecte Provisioning Engine, it is necessary to configure several settings in the Platform Settings in Administration UI.

By default, the properties which needed to connect to Efecte Provisioning Engine are fetched from consul. This is why you have to set consul.enabled property to true. Then you can make sure, that “provisioning.configuration.consul” is enabled as well. 

 When Consul is enabled all the needed configurations are defined for the Efecte Provisioning Engine:

 Provisioning task configuration for Active Directory

The Efecte Provisioning Engine uses Lightweight Directory Access Protocol (LDAP) interface for Active Directory and OpenLDAP, IBM LDAP and Redhat LDAP (FreeIPA). Properties are named according to the directory in question. Otherwise the needed configurations are same.

Identity Attribute Mapping
As a result from the provisioning task, the Efecte Service Management Tool receives user identity data from each Active Directory. This information needs to be mapped into the Efecte Service Management Tool data structures.

The Identity Attribute Mappings in the picture above, describes how the items and attributes are mapped between the Efecte Service Management Tool and the target Active Directory. Identity Attribute Mapping defines the Active Directory user object attributes and the user attributes which are mapped. The left column in the UI (the picture above) indicates the fields that the Provisioning Engine will extract from the Active Directory. The right column in the UI indicates the folder/template/attribute in ESM that the field extracted from the Active Directory which will be inserted/updated. When there is a need to fetch AD attribute which has more than one value, like 'memberOf' - that needs to be mapped to multi-valued attribute of ESM's Template as well'

Required properties are shown immediately when the view is opened. Optional properties can be added using the add property button. In practice, each property consists of a name–value pair that refines or alters the task behavior. Some properties have a user interface, which helps you to select the value from a dropdown menu or by clicking a radio button.

Deleting a property is done by clicking the delete icon (x) on the right side of the property. Manually added property names and values are case-sensitive and must be precise. The setting names, for instance, must be denoted exactly as indicated in the help text.

Access Rights Mapping

Access Rights in the Efecte Provisioning Engine are typically expressed as LDAP groups, in the AD typically as either a security or distribution group. As a result, from the provisioning task, the Efecte Service Management Tool receives Access Rights from each Active Directory. This information needs to be mapped into the Efecte Service Management Tool data structures. Access Rights Mapping defines specific properties for the provisioning engine task type.

“Target template code” and “Folder code” properties are shown immediately when the view is opened, also mappings at least for distinguishedName, objectGUID and datasourceid are also required and those 3 fields are shown automatically. Optional properties can be added using the add property button. In practice, each property consists of a name–value pair that refines or alters the task behavior. Some properties have a user interface, which helps you to select the value from a dropdown menu or by clicking a radio button. When there is a need to fetch AD attribute which has more than one value, like 'memberOf' - that needs to be mapped to multi-valued attribute of ESM's Template as well'

From the EPE version 2021.1, we allow to specify list of excluded DNs of Groups when exporting data to ESM. This improvement provide possibility to exclude dedicated Groups of the export to ESM.

Efecte Provisioning Engine supports several different LDAP directories, which supports LDAP user interface. The configuration view contains different names on the properties names depending of the choses directory. The required identity – or access rights mappings may differs depending on the chosen directory. 
 

Provisioning task configuration for Azure AD

Azure AD provisioning task configuration view:

Efecte Provisioning Engine is using Microsoft Graph API to connect Microsoft Azure AD. If there is a need to fetch just a part of the users from Azure AD that can be achieved by using filters. Link to learn more of API filters can be view from Microsoft’s documentation: https://docs.microsoft.com/en-us/graph/api/overview?view=graph-rest-1.0 

Identity Attribute Mapping for Azure AD

As a result from the provisioning task, the Efecte Service Management Tool receives user identity data from each Azure Active Directory. This information needs to be mapped into the Efecte Service Management Tool data structures.

The Identity Attribute Mappings in the picture above, describes how the items and attributes are mapped between the Efecte Service Management Tool and the target Azure AD. Identity Attribute Mapping defines the Azure AD user or group object attributes and the user or role attributes which are mapped. The left column in the UI (the picture above) indicates the fields that the Provisioning Engine will extract from the Azure AD. The right column in the UI indicates the folder/template/attribute in ESM that the field extracted from the Azure AD which will be inserted/updated.

Required properties are shown immediately when the view is opened. Optional properties can be added using the add property button. In practice, each property consists of a name–value pair that refines or alters the task behavior. Some properties have a user interface, which helps you to select the value from a dropdown menu or by clicking a radio button.

Deleting a property is done by clicking the delete icon (x) on the right side of the property. Manually added property names and values are case-sensitive and must be precise. The setting names, for instance, must be denoted exactly as indicated in the help text.

Access Rights Mapping for Azure AD

Access Rights in the Efecte Provisioning Engine are typically expressed as Azure AD groups, in the Azure typically as either a security or Office 365 (O365) group. Security Groups are used for controlling user access to in-app resources and O365 groups for facilitating user collaboration with shared Microsoft online resources. As a result, from the provisioning task, the Efecte Service Management Tool receives Access Rights from each Azure AD. This information needs to be mapped into the Efecte Service Management Tool data structures. Access Rights Mapping defines specific properties for the provisioning engine task type.

“Target template code” and “Folder code” properties are shown immediately when the view is opened, also mappings at least for id and datasourceid are also required and those 3 fields are shown automatically. Optional properties can be added using the add property button. In practice, each property consists of a name–value pair that refines or alters the task behavior. Some properties have a user interface, which helps you to select the value from a dropdown menu or by clicking a radio button.

Provisioning task status information

Administrators have visibility to Extract and Load status for all supported user repository provisioning tasks. If needed, administrators are also able to download user and group files for reviewing more information. Extract status provide information of how data were fetched from the source and Load status provide information, how EPE were able to load data to ESM. Extract/Load Status tables are not refreshed in real-time, when needed, user can click 'Update' button at the page header. This page is also updated, after you re-open it.

Importing / Exporting the Provisioning tasks 

From the Efecte Provisioning version 2021.1 forward we provide possibility to Import / Export capabilities for provisioning tasks. This gives the possibility to export existing provisioning tasks. It is possible to choose which of the existing provisioning tasks will be exported.

Import / Export -buttons are shown in the left-hand side on the Scheduled tasks view.

When the user clicks the “Export” -button, they will be provided all of the potential tasks, where they can flexibly select the appropriate tasks.

When the user clicks the “Ok” -button, provisioning tasks are exported into the XML file. The exported XML file can be then use for importing provisioning tasks to chosen environment. If you want to import them to the same environment, it’s recommended to modify two properties in the XML file. For each exported task you have the two properties; “UniqueIdentifierId”, “TaskName” and if you are planning to import them to existing environment it’s recommended to change in order to avoid errors during the import.