Start-RbJob: Run One Script From Another

Owned by Stephen Biro
Last updated: Jun 22, 2022
6 min read

Start-RbJob is used to launch other tasks asynchronously from a running task in readibots. These tasks can be used to refresh data that has already been retrieved by readibots (e.g. I’ve created or updated a user, and want to make sure that my users list and user license assignment reports are current), or they can be used to run another task to retrieve or modify data (e.g. I’m provisioning a new user, and as part of that user provisioning process I’m going to create the user account in AD, assign the user’s manager and notify that manager, and assign software licenses to the user, using other tasks that I have already created that can do these things independently of one another). This capability opens up a lot of new opportunities for what you can do with tasks in the readibots platform.

Start-RbJob leverages the job framework that is native to PowerShell. When you start a readibots job using Start-RbJob, a new thread is created that will manage the execution of, and optionally the retrieval of data from, a readibots task. The task is still run in readibots, with all of the auditing, change monitoring, and verification of permissions that readibots provides, but the task is launched asynchronously from the readibots job thread and monitored until it has finished running, at which point data will be retrieved from the run instance if data was requested in the Start-RbJob invocation.

Once the job is launched, Start-RbJob returns a readibots job object that can then be used with the native Wait-Job, Receive-Job, and Remove-Job cmdlets to wait for the job to finish execution, receive data from the job, and remove the job from the job manager, respectively. You can use Wait-Job or Receive-Job -Wait to block your current task and wait for one or more readibots jobs to finish running, also retrieving results from the jobs if you used the Receive-Job cmdlet, and Remove-Job to remove jobs that you are finished with from the job manager. Other native PowerShell *-Job cmdlets are not supported with readibots jobs at this time.

There is no limit on the number of jobs that you can launch at one time, and a task launched by one readibots job may in turn start additional readibots jobs that launch other tasks, and so on.

To give you an idea how this can work, imagine that you want to launch 3 tasks in parallel, wait for those tasks to complete, and then launch a fourth task. That would be done something like this:

# Launch three tasks at the same time, in parallel $job1 = Start-RbJob … $job2 = Start-RbJob … $job3 = Start-RbJob … # Wait for those tasks to complete, so that you can # launch a fourth task in sequence after the first three Wait-Job -Job $job1,$job2,$job3 # Launch the fourth task, without waiting for it to complete Start-RbJob …

There are two main choices that you need to make when you consider how you will launch as task as part of a start a job with Start-RbJob:

  1. Am I refreshing data in an existing dataset that was retrieved by another task? Or am I simply launching another task in my job that I want run in addition to my current task?

  2. Do I care when the job finishes, and if so, do I want to retrieve data from the completed job? Or do I simply want to launch a task and then forget about it?

Based on how you answer those two questions, you’ll be able to choose how you need to invoke Start-RbJob.

Task-level requirements

Tasks require specific configuration in order to be invocable using Start-RbJob. 

In order to run a task using Start-RbJob, whether you are doing a refresh or not, the following requirements must be met:

  1. The Start-RbJob cmdlet must be invoked from a running readibots task.

  2. The path for the task you want to run must be valid.

  3. The task you want to run must be configured to allow remote execution from readibots jobs launched from tasks in the same workspace or environment.

If you are refreshing data, the following additional requirements must be met:

  1. The task must have a single default dataset (view). Additional derived views may be included, but only one default view is allowed.

  2. The task must contain a parameter of type RbDataRefresh.

  3. Change monitoring must be enabled in the default view.

  4. At least one property must be identified as a unique key in the change monitoring configuration.

  5. All unique keys must be assigned in each dictionary passed into the -ArgumentList parameter.

If you are retrieving the output from the task, the following additional requirements must be met:

  1. The task you are retrieving data from must be configured to allow remote data retrieval from readibots jobs launched from tasks in the same workspace or environment. 

Syntax

Start-RbJob provides four syntaxes that allow you to invoke it according to your needs. As with all PowerShell syntax definitions, parameter names and values that are not enclosed in square brackets are required. The syntaxes available to you are as follows: 

Launch any task in readibots, without retrieving data produced by the run instance

Start-RbJob [-TaskName] <string> [-ArgumentList <IDictionary[]>] [-Name <string>] [<CommonParameters>]

Launch any task in readibots, and retrieve data (that is optionally filtered and limited to specific columns) produced by the run instance

Start-RbJob [-TaskName] <string> [-ArgumentList <IDictionary[]>] -DataSetName <string> [-Filter <string>] [-Property <string[]>] [-Name <string>] [<CommonParameters>]

Launch a refresh task in readibots to refresh (add or update, update is the default) specific items in a dataset

Start-RbJob [-TaskName] <string> -Refresh -ArgumentList <IDictionary[]> [-RefreshType <Add|Update>] [-Name <string>] [<CommonParameters>]

Launch a refresh task in readibots to refresh (add or update, update is the default) specific items in a dataset, and wait for the retrieve data (that is optionally filtered and limited to specific columns) produced by the refresh run instance

Start-RbJob [-TaskName] <string> -Refresh -ArgumentList <IDictionary[]> [-RefreshType <Add|Update>] -RetrieveData [-Filter <string>] [-Property <string[]>] [-Name <string>] [<CommonParameters>]

Here is a breakdown of each parameter and what they are used for:

Parameter

Description

Default value

TaskName

The path of the task that you want to run. If a relative path is used, it will be relative from the location of the current task in readibots. Note that using “..” at the beginning of a relative path is currently treated as if you used “.” (known issue).

 

ArgumentList

An array of hashtables or dictionaries identifying the parameters that you want to pass into the task that you want to run. If you are doing a refresh, the values used in a dictionary must match the unique keys configured in that task’s change monitoring settings, each row identified by the values in a single dictionary will be refreshed, and the RbDataRefresh parameter in the task being invoked will receive these dictionaries. If you are not doing a refresh, the task will be invoked sequentially once for each dictionary that you pass in, with the dictionary values splatted into the task invocation.

 

DataSetName

The name of the dataset (view) that you want to retrieve results from once the task has completed running.

 

Filter

A string filter that you want to apply to the data returned from the dataset, so that you only retrieve matching rows.

 

Property

One or more properties (columns) that you want to retrieve from the dataset.

 

Refresh

Indicates that the task will be invoked as a refresh task.

 

RefreshType

The type of refresh that is being invoked. Valid values include Add and Update.

Update

RetrieveData

Indicates that you want to retrieve data from the default view that is refreshed (tasks that support refresh can only return a single default view, so there is no need to identify it by name).

 

Name

Specifies a friendly name for the new job. You can use the name to identify the job to other job cmdlets, such as the Receive-Job cmdlet. 

The default friendly name is Job#, where # is an ordinal number that is incremented for each job.

Examples

Below are a few examples showing how you might use this Start-RbJob in practice.

Refresh the users dataset

Start-RbJob -TaskName .\..\Users -Refresh -ArgumentList @{ObjectId = $user1ObjectId},@{ObjectId = $user2ObjectId}

Run a bot and retrieve all data from one of the data grids (views)

$job = Start-RbJob -TaskName './getcurrentsessions' -DataSetName 'Sessions' $data = Receive-Job -Job $job -Wait -AutoRemoveJob

Refresh the users dataset and retrieve the user principal name, first name and last name from the results

 Run the assign manager task that is located in the same folder, and wait for the task to complete before continuing

 Run the disable user task that is located in the same folder for a set of users