Using the TaskCentre API
August 30, 2010 3 Comments
The TaskCentre API is very rich in what it lets you do to run a Task from another application, but cutting through the detailed on-line help can be confusing. So how can you queue a task on-demand from another application?
Here’s the “well I don’t need to read the manual” way to do it. But reader beware, this code should be thoroughly tested in your environment before use.
But first, the most important thing to note about using this script is the use of the “TaskID”. Internally TaskCentre uses a unique ID to identify a task, not the Task Name. So it is this ID that is used in the calling script. But, and this is a big but (no pun intended), if you export/import a task, the ID changes so you may have to edit the ID if you move tasks around.
Here’s the code snippet (you may need to copy & paste it in to a text editor):
Const logonTaskcentre = 1 Const logonWindows = 2 Dim TCAPI, ServerName, UserID, UserPW, Session, Task, TaskID ServerName = "localhost" UserID = "administrator" UserPW = "password" TaskID = nn 'Set to required Task ID 'If calling from outside TaskCentre, you need the next line and you may want to include the following If/End. 'Set TCAPI = GetObject("Iwcltcp.tcapi") 'If TCAPI Is Nothing Then Set TCAPI = CreateObject("Iwcltcp.tcapi") 'End If Set Session = TCAPI.Logon(logonTaskcentre, ServerName, UserID, UserPW) Set Task = Session.OpenTaskItem(TaskID) If Task.Disabled = False Then Task.QueueTask Else thisstep.Logwarn "Task ID: " & TaskID & " is Disabled" 'Don't do this if calling outside TaskCentre, use MsgBox instead. End If
The interesting thing is that you can use this same code to have one task call another. Just follow the comments (in green).
Please make sure you review the on-line help carefully (you’ll find you can access task variables, for example) and test before rolling this out.
About Paul
Hi Paul, Great information. I was also wondering but have not had time to read the Manual yet
can you find out the folder name a task is running in a VBSCript within a task, if so I can move my tasks more easily from Test to Production and have that fact change my needed varaibles?
Best, Brian
I think so. To be honest I am not sure.
There is a Folders collection that can list the tasks and you can probably deduce from there which is the containing folder. There is also so a Variables collection.
Go to the product’s on-line help and browse to the TaskCentre API under General. It’s all there.
Hello. This is my first post so I hope it is helpful.
We have written in house a system which soak tests tasks and checks results of runs. It is written entirely in Taskcentre steps and tasks.
During that process we needed to list tasks from folders and so on. Here are some snippets of code which may help you along.
‘ listAllTasks
Function listAllTasks(ByVal FolderName, ByVal RecurseFlag, ByVal fileOut)
‘ Check if there are any tasks in this folder
If FolderName.contents.Count >0 Then
‘ … for each of these …
For thisItem = 0 To FolderName.contents.Count – 1
‘ … run the task
Set thisTask = FolderName.contents.item(thisItem)
‘NOTE
‘ by changing this function in only a few ways – you can get it to queue all tasks from a particular folder and downwards
‘ if you use runsync instead of queue you get a sequential runnign of all tasks
‘ beware that sequential has nothign to do with the order in the client view but is related to the creation order of tasks
‘only list the task if it has not been disabled – NOTE THIS WAS MY REQUIREMENT
If thisTask.Disabled=False Then
fileOut.WriteLine( thisTask.TaskID & “,” & thisTask.name & “,” & FolderName.name)
ThisStep.ProgressText = “Writing ” & thisTask.name
‘ Else
‘ fileOut.WriteLine( Chr(9) & thisTask.name & Chr(9) & “Disabled”)
End If
Next
End If
‘ We have done the first folder but do we need to recurse its children?
If CBool(RecurseFlag) = True Then
‘ If so – check if there are any folders
If FolderName.childfolders.count >0 Then
‘ And for each of these call this function again
For i = 0 To FolderName.childfolders.count -1
listAllTasks FolderName.childfolders.item(i), True, fileOut
Next
End If
End If
End Function
‘
‘
Function Run_VB_Script()
Dim TCAPI, Session, Folders, TasksFolder
Const LogonTaskcentre = 1
Const LogonWindows = 2
‘ Start by setting the general environment
‘On Error resume Next
‘ Create the API interface
Set TCAPI = CreateObject(“Iwcltcp.TCAPI”)
‘ Yes, there should be error handling here but I just want to demonstrate the principles
‘ Now we want to output to a file so …
‘ Get the file system object
Set FSO = CreateObject(“Scripting.filesystemobject”)
‘ And tell it to create a file for reading
Set fileOut = FSO.OpenTextFile(“c:\temp\list tasks.txt”, 2, True)
‘ Now use our login credentials to connect to TC Store
Set Session = TCAPI.Logon(LogonTaskcentre, “localhost”, “Administrator”, “p@@@@”)
‘ And get the master folders list
Set Folders = Session.Folders
‘ Now find the Root Tasks folder as an object
Set TasksFolder = Folders(“Tasks”)
‘ Now we want to list all tasks in this folder
‘ The params are
‘ TaskFolder - the root folder to start listing from
‘ True or false - whether to recurse sub-folders
‘ fileout - The file to output to
ListAllTasks TasksFolder, True, fileOut
‘ Since this is recursive we need make no more calls
‘ Also the file system and API objects will disappear after the task run
‘ So we do nto have to delete them explicitly – though it is good practice
End Function
‘ Another FUN function
‘ findfolder
Function findfolder(ByVal FolderName, FolderTree)
‘ FolderName is what we are searching for
‘ FolderTree is the root Folder to start at
‘ Returns nothing as folder if it doesn’t find it
‘ or the actual folder as an object if it does find it
Set findfolder = Nothing
For i = 0 To FolderTree.Count -1
If FolderTree.item(i).name = FolderName Then
Set findfolder = FolderTree.item(i)
Exit Function
Else
Set findfolder = findfolder(FolderName, FolderTree.item(i).childfolders)
If Not findfolder Is Nothing Then
Exit For
End If
End If
Next
End Function