HR-liitin käyttää Generic Python Script -liitintä tiedon lukemiseen tiedostosta. Liitin on suunniteltu käytettäväksi IGA-ratkaisujen käyttäjän elinkaaren hallinnan käyttötapauksissa. Muuhun tarkoitukseen käyttäminen edellyttää skriptin viemistä host-koneelta ja muokkaamista asiakkaan vaatimusten mukaisesti; huomaa, että on myös mahdollista luoda uusi skripti alusta alkaen ja käyttää custom script -liitintä sen validointiin ja tuontiin.

HR-liitin tukee yhtä tai useampaa työjaksoa, kunhan työjaksot on luotu ”Tiedoston luominen HR-ratkaisusta” -luvun mukaisesti.

HR-liittimen perusperiaatteet,

1. Liitin käyttää ajastuspohjaisessa provisiointitehtävässä määritettyjä lisäargumentteja tiedoston löytämiseen polusta (jos lisäargumentti puuttuu, prosessi pysähtyy)

2. Tiedostot muunnetaan JSON-muotoon (dict) ja tallennetaan JSON-muodossa

3. Jokainen tiedosto voidaan ajaa täytenä (full) tai osittaisena (partial) ajona

4. Osittainen ajo vertaa dataa aina arkistoituun tiedostoon (jos arkistotiedosto puuttuu, prosessi pysähtyy)

5. Json-muotoisessa tiedostossa kaikki mapatut attribuutit ovat pakollisia kenttiä, ja tehtävä pysäyttää tuonnin, jos joltakin tuotavalta objektilta puuttuu pakollisia attribuutteja. CSV-muoto toimii eri tavalla: sille riittää, että kaikki mapatut attribuutit löytyvät otsikkorivin sarakkeista.

6. Liitin tuo IGA-ylläpitotehtävän IGA-ratkaisuun sisältäen virheet ja JSON-tiedostot, jotka sisältävät arkistoidut ja tuodut rivit, tuonnin suorittamisen jälkeen.

Liittimen tiedostot,

HR-liitin odottaa, että tiedosto luodaan HR-ratkaisusta alla olevan logiikan mukaisesti, ja tiedosto tallennetaan asiakkaan SFTP-palvelimelle, josta liitin voi hakea tiedoston/tiedostot. Huomaa, että koodauksen täytyy olla UTF-8.

Jos käytät csv-tiedostomuotoa, HR-liittimen skriptin oletuksena käyttämä kenttäerotin on ; (puolipiste).

Tiedoston luominen vaihtelee sen mukaan, mitä HR-ratkaisua asiakas käyttää; esimerkiksi erityisesti IGA-ratkaisu edellyttää, että tietoa saadaan sekä menneisyydestä että tulevaisuudesta.

Workday-HR-ratkaisuille suositellaan mukautetun raportin luomista Workdayhin, joka raportoi tarvittavat tiedot, ja json-muodon käyttämistä kyseisen raportin datan muotoiluun.

Esimerkkejä siitä, mitä tietoa käytetään vaaditun tiedoston luomiseen,

Jos asiakas haluaa käyttää HR-liitintä usean erilaisen datatyypin tuomiseen, on suositeltavaa käyttää yhtä HR-liitintä per datatyyppi.

Esimerkiksi jos asiakas haluaa tuoda organisaatioita ja käyttäjiä, heillä tulisi olla 2 liitintä, kuten "HR connector Organizations" ja "HR connector Users".

Ja kun näiden kahden liittimen tiedostot ovat samalla ftp-palvelimella, kansiorakenne voisi olla esimerkiksi:

/sftp/iga/in/organisation

/sftp/iga/in/organization/archive

/sftp/iga/in/user

/sftp/iga/in/user/archive

Datakansiossa tulisi olla vain yksi tiedosto kerrallaan.

Tällä kansiorakenteella voit käyttää näitä skriptiparametreja HR connector Organizations -liittimessä:

“sftp_remote_path_data”:"/sftp/iga/in/organization",

“sftp_remote_path_archive”:"/sftp/iga/in/organization/archive",

“file_path”:"./organization/*.csv"

Ja vastaavasti eri skriptiparametrit HR connector Users -liittimelle.

Parametrit

Käytetään HR-liittimen asetusten määrittämiseen; asetukset validoidaan skriptin ajon yhteydessä.
Muista tallentaa salasana turvalliseen paikkaan siltä varalta, että sinun täytyy tarkastella parametreja ajastetun tehtävän tallentamisen jälkeen.

HR-liitin käyttää seuraavia parametreja,

Validointi

Validointi tarkoittaa, että HR-liitin varmistaa, että kaikki käyttäjiin liittyvät pakolliset tiedot on saatu HR-ratkaisusta, ja jos tietoa puuttuu, HR-liitin luo oletuksena IGA-ylläpitotehtävän.

Asiakas voi määrittää luettavaksi lisäattribuutteja alla olevan listan ulkopuolelta, mutta se edellyttää HR-liittimen skriptin muokkaamista (lue lisää laajennusmahdollisuudet-luvusta).

Poikkeukset

Asiakas voi määrittää, mihin malliin, kansioon ja attribuuttiin HR-liitin luo seuraavat poikkeukset,

Nämä ohjeet opastavat, miten valmiiksi konfiguroitu HR-liitin otetaan käyttöön tai miten sellainen luodaan alusta alkaen; huomaa, että skriptin muokkaaminen edellyttää Python-skriptaustaitoja.

General guidance for scheduled tasks

General guidance for scheduled tasks

How to Create New Scheduled Task to import data

For configuring scheduled-based provisioning task, you will need access to Administration / Connectors tab.

1. Open the Administration area (a cogwheel symbol).

2. Open Connectors view.

3. Choose Connector for Scheduled-based task and select New Task
   Note! If connector is not created, you have to choose first New connector and after that New task.

 

4. Continue with connector specific instructions: Native Connectors

 

 

Should I use Incremental, Full or Both?

Scheduled task can be either Incremental or Full -type.

Do not import permissions with AD and LDAP incremental task

Incremental task has issue with permissions importing. At the moment it is recommended not to import group memberships with incremental scheduled task.

On Microsoft Active Directory and OpenLDAP connectors, remove this mapping on incremental task:
 

 

 

Setting on Scheduled tasks:

Incremental type is supported only for Microsoft Active Directory, LDAP and Microsoft Graph API (formerly known as Entra ID) Connectors.

Incremental type means, that Native Connectors (EPE) fetches data from source system, using changed timestamp information, so it fetches only data which is changed or added after previous incremental task run.

When Incremental type task is run for very first time, it does a full fetch (and it marks the current timestamp to EPE database),  thereafter, task uses that timestamp to ask the data source for data that changed since that timestamp (and then EPE updates the timestamp to EPE database for next task run). Clearing task cache doesn't affect this timestamp, so Incremental task is always incremental after first run.
 

Full type is supported for all Connectors.

Full type import fetches always all data (it's configured to fetch) from source system, on every run. 
 

Tasks internal cache

Both Full and Incremental type tasks use also Task cache in EPE, which makes certain imports faster and lighter for M42 system.

Beginning from version 2026.1.1

Tasks internal cache clean scheduling was moved from properties file to Task UI.

With that change you can now also decide per scheduled task when internal cache is cleared, or if it's not cleared at all. In normal situations cache is recommended to be cleared at some point to guarantee correct data on datacards. If template and imported data doesn't contain references, cache can be cleared quite rarely. With references, it's recommended to clear cache daily or weekly to guarantee correct data on datacards.

Versions before 2026.1.1

By default that task cache is cleared ad midnight UTC time. When cache is cleared, next import after that is run without caching used to reason if data fetched should be pushed to ESM, all fetched data is pushed to ESM. But after that, next task runs until next time cache is cleared, are using EPE cache to determine if fetched data needs to be pushed to ESM or not.

You can configure at what time of day task cache is emptied, by changing global setting in EPE datapump configuration: 

/opt/epe/datapump-itsm/config/custom.properties

which is by default set to: clearCacheHours24HourFormat=0

You can also clear cache many times a day, but that needs to be thinked carefully, as it has impact on overall performance as EPE will push changes to ESM, that probably are already there, example(do not add spaces to attribute value): clearCacheHours24HourFormat=6,12

After changing this value, reboot EPE datapump container to take change into use.

Recommendations

Have always by default Full type scheduled task.

If you want to fetch changes to data fetched already by full task, more frequently than you can run full task, add also incremental task. Usually incremental task is not needed.

 

 

Recommended Scheduling Sequence

Recommended scheduling sequence, depends how much data is read from Customers system/directory to the Matrix42 Core, Pro or IGA solution and is import Incremental or Full. 

Examples for scheduling, 

Total amount of users	Total amount of groups	Full load sequence	Incremental load sequence
< 500	< 1000	Every 30 minutes if partial load is not used Four (4) times a day if partial load is used	Every 10 minutes
< 2000	< 2000	Every 60 minutes, if partial load is not used Four (4) times a day if partial load is used	Every 15 minutes
< 5000	< 3000	Every four (4) hours, if partial load is not used Twice a day if partial load is used	Every 15 minutes
< 10 000	< 5000	Maximum imports twice a day, no matter if partial load is or is not used	Every 30 minutes
< 50 000	< 7000	Maximum import once a day, no matter if partial load is or is not used	Every 60 minutes
Over 50 000	Over 7000	There might be a need for another EPE-worker, please contact Product Owner	Separately evaluated

Please note that if there are several tasks running at the same time you may need more EPE-workers. The tasks should be scheduled at different times and can be completed according to the table above. However, if there are more than 6 tasks running at the same time, the number of epeworkers should be increased. It's best practice not to schedule tasks to run at same time, if possible.

Recommendations related to performance
If the amount fo data to be imported is over 10000 concider these things:
Adjust log level of ESM and DATAPUMP to ERROR-level, to lowe the amount of logging during task run
Have as few as possible automations starting immediately for imported datacards (listeners, handlers, workflows), as those make ESM to take longer time handling new datacards.

 

 

Set removed accounts and entitlements status removed/disabled

With this functionality, you can mark account and entitlement status to e.g. Deleted or Disabled, when account or entitlement is removed from source system. Starting from version 2025.3 you can also set status to generic objects (not only to accounts/identities and entitlements/groups). 

For version 2025.3 and newer

In version 2025.3 these settings are moved from properties files to Task UI. Also you can now set these settings for Generic objects, which have not been possible before this version.

There is separate configuration for each scheduled task, and for all mapping types. Here is example of this config on task:

Unique check added on 26.2 version

When this Set value for deleted objects option is enabled, at least one of the attributes mapped to the unique id must also be marked as Unique on the target template. If none of the mapped attributes are unique, the task cannot be saved and the message "Unique id must be mapped to at least one unique attribute of template" is shown.

 

For version 2025.2 and older

This functionality is available for “full” type scheduled tasks.

Settings are on datapump dockers configuration file. To change those parameter values, you need to set those in /opt/epe/datapump-itsm/config/custom.properties file.

Configuration

To enable disabling functionality, datapump config should have these parameters set to true:

disable.unknown.esm.users=true
disable.unknown.esm.groups=true

Those 2 parameters are false by default in 2024.2 and 2025.1 versions. In 2025.2 and newer version those are true by default.

 

Next are these parameters:

personTemplateStatusCodeAttributeKey=accountStatus
personTemplateStatusAttributeDisabledValueKey=Deleted
groupTemplateStatusCodeAttributeKey=status
groupTemplateStatusAttributeDisabledValueKey=5 - Removed

First two attributes should point to the DatacardHiddenState attribute in the User template, and tell which value should be send there when the user is deleted.

By default its accountStatus and Value 5 - Removed on IGA Account template.

All these needs to match with the attribute configuration:

 

Open 1.PNG

Same thing applies for the next two paramaters, but its for Groups.'

If you need to change those parameters in properties file, do changes in Datapump container to file: /opt/epe/datapump-itsm/config/custom.properties and those changes will then survive over container reboot and will be copied on reboot to /opt/epe/datapump-itsm/config/application.properties.

Description

Tasks save their __taskid__ shown as Task Id mapping in the UI to the datacards, its then used to determine if the datacard was added by this task. In case there are multiple tasks with different sets of users.

This field was previously used as datasourceid, but since we moved to the model where connector can have multiple tasks its identifier cannot be used anymore, thats why the field was repurposed as taskid instead.

 

Taking users as an example, when task runs ESM is asked for the list of users that have its taskid in Task Id mapping field, and doesn't have a personTemplateStatusAttributeDisabledValueKey value in the personTemplateStatusCodeAttributeKey

This result is then compared to what the task fetched, and the datacards of users that were not fetched have their personTemplateStatusattribute set to value specified in the config - 5 - Removedby default.

Example log below shows described process and informs that one user was removed.

 

Open 2.PNG

Same thing applies to groups but groupTemplateStatusattributes are used instead.

Notes

• Feature works only with full fetch scheduled tasks..
• No support for generic templates yet, only identity and access
• When migrating from the previous versions where datasourceid was still used it needs to run at least once to set its taskid’s in the datacards first.
• EPE identifies Disabled users or groups as the ones that were removed from the AD, at the present we do not support statuses related to the entity beign active or not.
• EPE does not enable users back on its own.
• If more than one tasks fetches the same users or groups it may overwrite the taskid in the datacard depending on which task ran last. It is suggested that many full type tasks are not fetching same user or group.
• Always do configuration file changes to custom.properties, do not change only application.properties as those changes are lost on container reboot if you have not done same changes to custom.properties.

 

 

 

HR-liittimen ja ajastetun tehtävän konfigurointi

Liittimien hallintaan pääsemiseksi käyttäjällä täytyy olla oikeudet Platform-konfiguraatioon.

1. Avaa ratkaisun hallintanäkymä (hammasrataskuvake).
2. Avaa connectors-näkymä.
3. Valitse uusi liitin

2. Valitse Data Source -tyypiksi Custom Backend

3. Täytä tiedot

• Anna liittimelle yksilöllinen nimi, huomaa, ettei nimeä voi muuttaa jälkikäteen.
• Valitse IGAConnector.py-skripti provisiointiskripti-kentästä
• Parametrien salaussalasanaa tarvitaan parametrien piilottamiseen/paljastamiseen liittimen tallentamisen jälkeen
• WebAPI-käyttäjää tarvitaan, kun HR-liitin kirjoittaa dataa asiakkaan Pro/IGA-ratkaisuun
• WebAPI-salasanaa tarvitaan, kun HR-liitin kirjoittaa dataa asiakkaan Pro/IGA-ratkaisuun

4. Paljasta ja muokkaa parametreja asiakkaan määritysten mukaisesti

• Tallenna salaussalasana turvalliseen paikkaan, tarvitset sitä myöhemmin, jos parametreja täytyy säätää
  
  Esimerkki parametreista:
  {"objectGUID_field_name":"objectGUID", "sftp_server_fqdn":"transfer.xx.com", "sftp_server_ssh_port_number":"22", "sftp_username":"username_here", "sftp_password":"username_here", "sftp_remote_path_data":"/sftp/data", "sftp_remote_path_archive":"/sftp/archive",
"file_path":"./data/workperiod*.csv", // Path and file pattern where file is located. Mandatory value
"data_type":"workperiod", // Values: costcenter, organization, title or workperiod. Mandatory value
"run_type":"partial", // Run type specifies if comparison to previous file will be done. Values: full or partial. Optional value, default is 'partial'
"update_limit": 100, // How many updates are allowed to IGA System. Mandatory value
"override_update_limit":false, // overrides update limit, if amoun of updates is more than given limit. Values: true or false. Optional value, defaul is 'false'
"minimum_row_count": 10, // What is the minimum amount of rows, that should exist in the file. Optional value
"webapi_user": "IGA.WebAPI", // Web API user for report creation. Requires Create and Read permissions to IGA Adminisitration task. Mandatory value
"webapi_password": "aeiou", // Web API user's password. Mandatory value
"webapi_url":"https://eisdemo.efectecloud-demo.com", // URL to ESM environment. Mandatory value
"report_template_code":"IGAWorkflowTaskInformation", // Target template code. Mandatory value
"report_folder_code":"iga_tasks", // Target folder code. Mandatory value
"debug": false, // Enables debug logging. Values: true of false. Optional value, default is 'false'
"language": "en" // Sets IGA Administration Task report language. Optional value, default is 'en'
}

5. Luo uusi ajastettu tehtävä HR-liittimelle

6. Täytä tehtävän tiedot

• Liittimelle yksilöllinen tehtävän nimi, huomaa, ettei nimeä voi muuttaa jälkikäteen.
• Task usage asetetaan arvoon scheduled
• Mappings type asetetaan arvoon generic (yksi malli)

• Objectguid-attribuutin nimi. Kirjoita syöttödatasi sarakkeen/attribuutin nimi, joka sisältää rivin yksilöllisen tunnisteen. Esimerkiksi: objectGUID

7. Täytä epäonnistumistiedot

Valinnaiset asetukset virhetilanteiden käsittelyyn: jos ajastettu tehtävä epäonnistuu, se voi luoda tietokortin, joka näyttää virheen. Jos epäonnistumisasetukset on määritetty, ylläpitäjän ei tarvitse manuaalisesti tarkistaa ajastettujen tehtävien tilaa.

• Failure template - Valitse tietokortin malli, joka luodaan mahdollisten virheiden yhteydessä provisioinnin aikana (yhteys tietolähteisiin, aikakatkaisut jne.)
• Failure folder - Valitse kansio, johon epäonnistumistietokortti tallennetaan.
• Failure attribute - Valitse attribuutti, johon virhetieto tallennetaan Failure Templatessa.

8. Täytä geneerisen mallin mappaukset

Geneeristä dataa luetaan mihin tahansa malliin, jonka käyttäjä haluaa, ja on pakollista asettaa kohdekansio, datasourceid ja yksilölliset arvot, joita käytetään datan tunnistamiseen asiakkaan HR:n ja Matrix42 Pro/IGA-ratkaisun välillä.

• Target template - Valitse malli, jolla määritetään attribuuttimappaukset
  Select a template to define attribute mappings
• Target folder - Valitse kansio kansioluettelosta. Luettelo rajautuu vastaamaan valitun mallin kanssa yhteensopivia kansioita.
• Data Source Type mapping - valinnainen. Sisältää Generic Python Script -liittimen tyypin vakiomuotoisen merkkijonon
• Task Id mapping - pakollista mapata esimerkiksi datasourceid- tai taskid-attribuuttiin. Tätä käyttää ”Set value to datacard for objects deleted from source system” -ominaisuus. Saman attribuutin täytyy löytyä myös mappaustaulukosta. Tämän täytyy olla ei-yksilöllinen attribuutti.
• Attribuuttimappaukset
  1. HR attribute (External attribute) - mikä tiedoston attribuutti mapataan Pro/IGA:han
  2. Local attribute - mihin Pro/IGA:n attribuuttiin data mapataan

9. Jos varsinaista skriptiä täytyy muokata, se täytyy ladata asiakkaan host-koneelta, muokata ja ladata uudelleen.

• Jos sinulla ei ole pääsyä host-koneeseen, ota yhteyttä Matrix42 Service Deskiin saadaksesi apua.

10. Tallenna muutokset

11. Ennen kuin ajat HR-liittimen ajastetun tehtävän,

• Tarkista, että kaikki työnkulkuihin ja asetuksiin liittyvä konfiguraatio tietokorteissa on kunnossa.
• Kun ajat ensimmäistä kertaa, varmista, että provisiointi on poistettu käytöstä hakemistoihin ja sovelluksiin päin

12. Aja tehtävä manuaalisesti tai odota, kunnes ajastettu ajo käynnistyy.

13. Varmista, että data on luettu oikeille tietokorteille ja oikeat attribuutit ovat kunnossa.

14. Vianmääritys

• Jos failure template on käytössä, tarkista oikea tietokortti
• Tarkista ajastetun tehtävän historia liittimien hallinnasta
• Tarkista lokit

Valitse HR-liitin, jos:

• HR-tiedosto on litteässä XML-, CSV- tai JSON-muodossa
• Asiakkaalla on SFTP-palvelin
• HR-tietoa saadaan sekä menneisyydestä että tulevaisuudesta
• Datatyyppi on kustannuspaikka, organisaatio, nimike tai työjakso
• Data sisältää vähintään sukunimen, etunimen, työsuhteen alkupäivämäärän, Title ID:n, Manager ID:n, organisaatioyksikön tunnisteen
• Data sisältää vähintään yhden näistä yksilöllisistä arvoista: henkilötunnus / kansallinen tunnus / työntekijänumero