Scripting basics: Using Initialization/Termination/Entry Scripts in IdM-passes

[terovirta]

During the later part of last year had to develop a set of quick&dirty reports in a proof of concept project where the ETL-cababilites of IdM were demonstrated. I used the Initialization/Termination/Entry scripts and it gave me an idea to write a blog about using them. I am not sure how the basic IdM training course by SAP addresses these topics but if it doesn't and since not all the new IdM'ers participate the training, so maybe this helps someone in getting started or gives some ideas.

In IdM passes you can define the following types of custom scripts to be triggered upon execution of the pass:

1. Initialization Script
2. Termination Script
3. Entry Script

The toGeneric pass has also three additional types of custom scripts:

1. Open destination
2. Next data entry
3. Close destination

Consider following dummy toGeneric pass as an example. It runs a dummy SQL-statement in Source-tab that returns static text as a result set which gets passed to Destination-tab. The passed entries are "processed" by the scripts in Destination-tab.

Source:

The Source-tab’s SQL-statement returns two dummy rows (or records, or entries depending how you want to see them) to the Destination-tab.

Destination:

The Destination-tab calls all the 3 types of scripts possible in toGeneric-pass plus getCount-script in the attribute mapping. What ever is returned by getCount-script gets inserted into it's place in the table cell and is passed to the Next Data Entry script among the other attributes defined in the mapping.

Execution Order
Let’s examine the job log and see the execution order plus what the output was. All the scripts in the example output their name plus what was passed as parameter.

So the execution order is:

1. Initialization Script
2. Open Destination Script
3. Entry Script
4. Next Data Entry Script
5. Close Destination Script
6. Termination Script

Initialization Script

The Initialization Script was called first and from the output it’s visible that while it received the parameters in Par-object none of the macros were executed. All the values appear as they were typed in the Destination-tab.

In the example we have one custom variable called “theCount” and as it is introduced outside the function definition it becomes global variable and can be used in any other scripts in the pass as long as the other script also defines the same global variable. Variable theCount is set to initial value 0 in the Initialization Script.

I’ve used Initialization Script mostly in two ways:

1. Setting the initial values for attributes in pass (or in whole job if the pass is before where the value is later used)
2. When using delta-functionality in a way that entris no longer present in the source would be automatically deleted in IdStore. Here the initialization script is handy in checking if the data source has lesser number of rows than expected. For example if some data transfer has failed and the source is empty, using delta to mark entries to be deleted could be fatal without any checks.

Like the name suggests and output displays the Initialization Script is called once.

Open Destination Script

The Open Destination Script is called next based on the output it does not even get the Par-hash table. Open Destination is typically used like the name suggests, in opening a connection, for example an JCo-connection in provisioning task. In JCo-call scenario Next Data Entry Script could do the actual call and Close Destination could close the opened connection. Based on the output Open Destination got called once.

Entry Script

The Entry Script in Source-tab is called next. Based on the output the hash table "Par" has it’s elements fully translated to data contents. The example uses Entry Script in growing the counter variable by one and storing the new value to Par to be used in the Destination tab. (BTW, for some reason having an underscore in the element name, for example “THE_COUNT”, crashed the pass.)

The Entry Script is called as many times as the Source-tab definition returns rows.

Next data entry Script

The Next Data Entry Script in Destination-tab is called next and again it is called as many times as the Source-definition returns records. It receives the full Par-hash table and it’s correct values along with the values we just manipulated in the Entry Script.

Close destination Script

The Close Destination was called as second to last.

Termination Script

The Termination Script was the last script to be called.

HTML-file generation using Initialization/Termination/Entry scripts

The example job has two passes; first one that loads data from CSV-file to temp-table and another pass that reads the contents of the table and writes them to HTML-file.

Populating temp table

Source:

Destination:

The destination has just file vs. table attribute mapping. I always name the columns in files after the IdM-attributes so it simplifies the “interface” and it sort of documents itself.

Writing HTML

Writing plain text file or file with CSV-structure is pretty easy from IdM as all that needs to be done for the formatting are the column/attribute-mapping and defining the CSV-delimiter, headings etc.

HTML is slightly trickier as all it’s possible to output in the Destination-tab are the repeatable elements meaning just table cells. The start and end of the HTML document plus start and end of the table must come from somewhere and this is where Termination Script is handy.

Source

The source SQL reads the entries from the temp table. Note that it’s possible to have a JavaScript in the SQL-statement.

The JavaScript is executed first and whatever is returned by mySQLFilter gets embedded into SQL. Good exampe on how to use the JavaScript within SQL can be found from the BW-interface and how IdM sends the data to SAP BW via LDAP push.

Initialization Script

Initialization Script is used to generate the somewhat unique filename from timestamp. Name of the file is stored to global variable so that the name is accessible for other scripts. The colons are removed from the file name with uReplaceString-function. The Initialization Script also sets the counter that is used in counting the rows to zero.

Entry Script

Entry Script just grows the counter like in previous example.

Termination Script

As the previous example showed the Termination Script is called in the end. So, Termination Script is called after the table cells are written into the file and here it reads the table cells into a string plus adds the start and end of the HMTL-page around the table cells.

The HTML-page uses a style sheet that is returned from script just to demonstrate that there can be more than one script in the script “file”.

Destination

The destination has simple attribute mapping that writes the HTML-table rows to the file.

The output filename is returned by a script getHtmlFileName, which just returns the value from global variable.

The result