Start Session Bot

This request is used to start a bot (with payload)

[POST] https://tap.gateway:port/StartRobot

Request headers

Content-Type: multipart/form-data'

Request body

All parameters for this request are passed via multipart form-data. The following keys are expected:

• username - the Windows username that will be used to create the session

• password - the Windows user password that will be used to create the session

• token - this is the token that is configured in the TGA (within appsettings.json); if this does not match with provided token, the response will feature a 403 Forbidden code.

• botPath - the absolute path to the target automation. This needs to be a solution file (.tap)

• ip - the ip address of the session creation host. This is usually set to 127.0.0.1 or whatever the terminal services listener is configured to.

• port - the default value is 3389, which is the default RDP protocol port. If terminal services are listening on a diferent port, this needs to be changed.

• domain - the domain name, if the server is part of one. Otherwise, this value can be left empty.

• colorDepth - default value is 32, representing the color depth for the Windows session.

• desktopHeight - the height in pixels for the resolution of the Windows session.

• desktopWidth - the width in pixels for the resolution of the Windows session.

Besides the mandatory parameters required above, you can specify an unlimited number of additional parameters which will be passed to the bot runtime once triggered.

• data1=some_value

• data2=some_other_value

• file1='@C:\file1.pdf'

• file2='@C:\file2.txt'

• ...

Returns

The TGA should reply with a code 200 and aditional runtime information as JSON:

{
	"response": {
		"message": "Robot C:\\Tailent\\Test\\Test.tap started",
		"messageType": 6,
		"metadata": ["7876"]
	},
	"guid": "2777f2d5-dbf1-41a0-ad1a-b2c9b9388baf",
	"accessTokenSet": true,
	"accessToken": "AiUAOWUjyvZSRkabP9208JguJ4NUYXktMAteQVZZDoHfRJ4FTk46CrYuBZmiK1fWkVCn39BGYItxtHoYBTKlfO8bLE8avBENhOaQ9kIk6MuEgpA3HnlT5PKRhAwCQM4U"
}

This response features important information that can be used in other REST requests.

The first section "response" offers information about what automation was started:

• message is the response from the TGA component

• messageType signals the outcome of the requested operation (6 is the code for successful remote start)

• metadata is an array with additional information regarding to the request; by default this contains the PID of the TAP.Runtime process (automation)

guid - is the unique identifier assigned at runtime to the bot instance and can be used to uniquely identify this bot.

accessTokenSet - can be true/false depending on wether the OTP (or access token generated was set correctly).

accessToken - is a OTP (one time password) generated only once for this particular bot instance. This can used (along with the guid) to interogate on the status or updates of this particular bot instance. Please note that this access token is not saved and cannot be regenerated if lost.

Example curl request

curl --request POST \
  --url https://tap.gateway:port/StartRobot \
  --header 'Content-Type: multipart/form-data' \
  --form username=TestUser \
  --form 'password=Password' \
  --form token=12345678 \
  --form 'botPath=C:\Tailent\Test\Test.tap' \
  --form ip=127.0.0.1 \
  --form port=3389 \
  --form domain= \
  --form colorDepth=32 \
  --form desktopHeight=768 \
  --form desktopWidth=1024 \
  --form data1=some_value \
  --form data2=some_other_value \
  --form 'file1=@C:\file1.pdf'
  --form 'file2=@C:\file2.txt'