Using the FC

This FC provides you a handler object for calling and managing AssemblyLines on either the local or a remote Server.

You configure this FC by choosing the AL to call, the Server on which this AL is defined and should run on (blank or "local" indicating that the AL runs on this Server which is running the FC), as well as the Config Instance that the AL belongs to. Again, a blank parameter value means that this AL is in the same Config Instance as the one containing the FC itself.

You also choose the Execution Mode (see "AL Cycle Mode" in Configuring Directory Integrator for more information). Although there are three Execution Modes (Run and wait for completion, Run in background and Manual cycle mode), the first two options are the standard methods of starting an AL from script with or without calling the AL join() method.

These first two modes cause the target AL to run on its own (stand alone) in its own thread. The third mode, cycle mode, means that the target AL is controlled by the FC which will execute it one cycle at a time for each time the FC is invoked. When the FC runs an AssemblyLine in stand-alone mode, the FC keeps a reference to the target AL – just like you get when you call main.startAL(). The FC can also return the status of the running/terminated ALs. You obtain this status by calling the FC's perform() method with a null or empty Entry parameter. The returned Entry object contains the reference to the target AL in an attribute called "value". If you pass a null value to the FC, the return value is the actual reference to the target AL (again, like making a main.startAL() call).

You can also call the FC with specific string command values to obtain info about the target AL:

perform("target")	returns the object reference of the target AL.
perform("active")	returns either "active", "aborted" or "terminated" depending on the target AL status.
perform("error")	returns the java.lang.Exception object when the status is "aborted".
perform("result")	returns the current result Entry object.
perform("stop")	tries to terminate an active target AL, and will throw an error if the call does not succeed.

Note that if you have specified the "Run and wait for completion" Execution Mode, then each call to perform() starts the target AL and returns the complete status for the execution (for example, reference to the target as well as status and error object). In this case, the initialize() method does NOT start the target AL as it does in all other cases. When the FC is called in this mode with an Entry object, the Entry object can contain one or more of the above keywords in an attribute called command (as described in the list above, and concatenated in a comma-separated list). The returned Entry object is then populated with the same values as described above. So, rather than calling perform() several times with each required command, you can create an Entry with all keywords as attributes in the Entry object and get away with one call to perform():

var e = system.newEntry(); 
e.setAttribute("command", "target, status"); 
// In this example, fc references a Function Interface.
// If this was an AL Function instead, then fc.callreply(e)
// would be done.
var res = fc.perform(e); 
task.logmsg("The status is: " + res.getString("status"));

When the FC runs an AL in manual mode, each call with an Entry object causes one cycle to be executed in the target AL. The returned Entry object is the work entry result at the end of the cycle. When the target AL has completed, a null entry is returned. If the cycle execution causes an error, then that error is re-thrown by the FC (so you should use a try-catch block in your script).

The target AL can be supplied with parameters, in two different ways.

By means of a Task Call Block (TCB)

You can use the method fc.getTCB() and set parameters in the returned TCB object. This object will be used the next time an AssemblyLine is started by this FC. Only connector parameters should be set in the returned TCB as this FC will potentially overwrite the runmode and initial work entry.

By means of special attributes

Another way to set TCB parameters is by using the output attribute map where variables should be defined with the specific prefix "$tcb.". When these attributes are found in the entry they will be moved to the TCB and removed from the entry. This will only work when the FC runs an AssemblyLine each time the FC is called (that is, run and await completion). The attribute name "$tcb.accumulator" is used to set the accumulator.

You can use the following $tcb.* attributes in the output map for the AL FC:

Component parameter $tcb.connectorName.paramName, where connectorName is the name of the AssemblyLine component, and paramName is the internal name of a configuration parameter. For example, if you have a File Connector named FileConnector, and you want to set the File Path, you can map the attribute $tcb.FileConnector.filePath.
The accumulator $tcb.accumulator specifies an accumulator to use to collect the work entries that are generated by the AssemblyLine.

The Query ("Quick Discovery") button in the FC Input and Output Map tabs will try the following methods for determining the schema of the AL to be called:

If the Operation parameter is set the FC will get any attributes that are defined in the Input and Output maps of that operation.
If the AL has a defined schema (AL Call/Return tab), then this will be used.
Otherwise the FC examines the Input and Output maps of all Connectors in the AL to be called in order to "guess" its schema.

In the target AL you can define an operation called "querySchema"; if this is the case the Input and Output attributes of this operation are used to supply the AL FC (or the AssemblyLine Connector) with the schema.

Passing parameters to AssemblyLines

The following example shows how to pass parameters to different AssemblyLines using the AssemblyLine Function Component.

In the Before Call Hook of the AssemblyLine Function Component, declare a TCB as shown:

tcb = thisComponent.getFunction().getTCB(); 
// gets the current TCB of the running AssemblyLine. 
tcb.setALSetting("dn", work.getString("$dn")); 
// dn is the attribute name that TCB holds. The second parameter in 
// tcb.setALSetting(<>,<>) is the actual value that needs to be passed to the target AssemblyLine.

In the Configuration Editor, select the Use TCB Attributes check box.

At the target AssemblyLine, for a mapped variable (input map), use the following code to retrieve the passed parameter:

var mydn = task.getConfigStr("dn"); 
//task.getConfigStr(<transfer_name>), the transfer_name should match the name used in Step 1.

Using the FC

Passing parameters to AssemblyLines

See Also