Saving an Execution Plan -- API

Synthetic Blackouts in versions 11.3.02 and later
  • Starting from version 11.3.02, the Blackout configuration is no longer part of the Execution Plan APIs. You can use the dedicated Synthetic Blackout and Synthetic Time Frames APIs for that purpose.
  • If you are using version 11.3.01 or earlier, you can continue to use the Execution Plan APIs to access the Blackouts.

The PUT method of the executionplans API saves an Execution Plan.

Before you begin

You must obtain an authToken by using the login API. The token authenticates the user performing the operation. For details, see TSWS authentication.

Synthetic configuration APIs

Notes:

  • If you have upgraded to version 11.3.02, you can access the Synthetic Blackout and Synthetic Time Frames APIs listed in this table.
  • If you are using version 11.3.01 or earlier, you can continue to use the Execution Plan APIs to access the Blackouts.

API

Method

Description

Applications

GET

Retrieve the details of applications

PUT

Update an existing application

POST

Create a new application

DELETE

Delete an application

Execution Plans



GET

Retrieve the details of Execution Plans

PUT

DELETE

Delete an Execution Plan

Scripts

GET

Retrieve the details of scripts

Locations

GET

Retrieve the details of all locations

Blackouts

POST

Retrieve the details of Blackouts

PUT

POST

Activate the Blackout

POST

Deactivate the Blackout

POST

Delete a Blackout

Time Frames

POST

Retrieve the details of Time Frames

PUT

POST

Delete Time Frames

To save an Execution Plan

The executionplan API uses the PUT method to save an Execution Plan.

Request syntax

•For 11.3.02 or later
https://<PresentationServerHostName>/tsws/10.0/api/appvis/executionplan/save
•For 11.3.01 or earlier
https://<PresentationServerHostName>/tsws/10.0/api/appvis/synthetic/api/executionplans/save


In the above example, <PresentationServerHostName> indicates the host name of the TrueSight Presentation Server.

Request with REST client

After accessing the REST client, perform the following steps:

  1. Enter the URL for API.
    An example of a request for a single Execution Plan is:

    https://localhost/tsws/10.0/api/appvis/synthetic/api/executionplans/save

  2. Add a new header row and select Authorization as the header type.
  3. Enter the text authToken followed by the authToken generated through the login API.
  4. Make sure you have a Content-Type header row with the value application/json.
  5. Insert the JSON code in the request body.
  6. Click Send.

Request parameters

Element

Description

authToken

Value of authToken

Request body (applicable to versions 11.3.02 and later)

For versions 11.3.02 and later

The following code is an example of the JSON code to send with the request.

Note

This functionality requires that you send the entire JSON for the Execution Plan you want to save. Sending only the fields you want to update is not sufficient.


{
"executionPlanId": 379,
"executionPlanName": "example",
"scriptFileId": 3,
"description": "",
"selectedApplicationName": null,
"scheduler":

{ "triggerType": "CONTINUOUS", "startAt": "0", "startAtTimeOffset": "UTC", "typeOfStart": "SPECIFIC_TIME", "multipleOfMinutesInHour": 1, "specificTime": "30:00", "randomDelayEnabled": true, "startAtWithRandomDelay": 5, "intervalInMinutes": 5, "transactionTimeout": 15, "daysOfWeek": null, "daysOfMonth": null, "daysOfRunFromHour": "0:00", "daysOfRunTillHour": "0:00", "terminateAt": "0" }
,
"inactive_by": [],
"applications":

{ "1": "demo", "110": "new" }
,
"selectedApplicationId": 1,
"agentGroups":

{ "1": "Israel" }
,
"selectedAgentGroups": [
1
],
"attributes": [
{ "name": "Data Size", "description": "Size of the data package to be sent in bytes", "type": "number", "defaultValue": "32", "value": "32", "length": "4", "encryptionType": 0, "encrypted": 0, "order": 3 }
,
{ "name": "Host", "description": "The host being monitored", "type": "string", "defaultValue": "", "value": "564654", "length": "0", "encryptionType": 0, "encrypted": 0, "order": 0 }
,
{ "name": "Number of Pings", "description": "Number of pings to be sent", "type": "number", "defaultValue": "1", "value": "1", "length": "4", "encryptionType": 0, "encrypted": 0, "order": 2 }
,
{ "name": "Timer Name", "description": "Name of the ICMP Ping Timer", "type": "string", "defaultValue": "Sv_ICMP Ping", "value": "Sv_ICMP Ping", "length": "12", "encryptionType": 0, "encrypted": 0, "order": 4 }
,

{ "name": "Ping Timeout", "description": "Timeout value for the ping in seconds", "type": "float", "defaultValue": "1.000000000", "value": "1.000000000", "length": "8", "encryptionType": 0, "encrypted": 0, "order": 1 }
],
"scripts":

{ "1": "FtpPinger.ltz", "2": "LdapPinger.ltz", "3": "Pinger.ltz", "4": "Pop3Pinger.ltz", "5": "SmtpPinger.ltz", "6": "URLChecker.ltz" }
,
"userStatus": 1,
"executionLogSetting": "ON_ERROR"
}

Request body parameters (applicable to versions 11.3.02 and later)

Parameter

Description

Value

executionPlanId

ID of the Execution Plan

  • To create a new Execution Plan use 0.
  • To update a specific Execution Plan use the execution plan ID.

String representing a numeric value

executionPlanName

Name of the Execution Plan

String

scriptFileId

ID of the script used by the Execution Plan

  • When creating a new Execution Plan, you must enter a scriptFileId.

When updating an existing Execution Plan, this cannot be modified

String representing a numeric value

description

Description of the Execution Plan

String

selectedApplicationName

(Mandatory) appID of the application on the Presentation Server. Can be retrieved by the details of applications

String

scheduler

Schedule defined for the Execution Plan


  typeOfStart

Start executing the Execution Plan

One of the following:

MULTIPLE_OF_MINUTES and SPECIFIC_TIME
Default value is - MULTIPLE_OF_MINUTES

  specificTime

Set the Execution to start at the exact specified time.

When SPECIFIC_TIME is selected as typeOfStart.
The value must be String and the format is mm:ss (minutes:seconds). The range is between 00:00 and 59:59. The default value is 30:00

  mulipleOfMinutesInHour

Set the start time in multiples of specified minutes within the hour. The first run occurs in the next valid multiple of specified minute within the hour at the time Execution Plan is created, updated, or restarted.

When MULTIPLE_OF_MINUTES is selected as typeOfStart.
The value is an integer (int) whole number. The range is between 1 and 30 minutes. The default value is 1

  randomDelayEnabled

(Optional) Set this to the maximum range of delay before the Execution Plan starts. A different delay value is randomly set for each location where the Execution Plan runs. In each location, the Execution Plan runs at start time as configured in Initial Execution Schedule + the random delay set for the Execution Plan in that location. You can skip this option if you do not want a random delay.

It is optional. The value is boolean (true or false). The default value is true.

  startAtWithRandomDelay

Range, in minutes, within which the Execution Plan starts

This is optional and based on whether the randomDelayEnabled field is set to true or false. String representing a numeric value as follows:

  • Minimum is 1 minute.
  • Maximum is 60 minutes.
  • Default is 5 minutes.

  startAtTimeOffset

Clock used for calculating the schedule

  • UTC—Universal Coordinated Time
  • LOCAL—Local time on the computer where the TEA Agent is installed

  terminateAt

Date from when the schedule is no longer used

One of the following:

  • Date in format: YYYY-MM-DDThh:mm:ss
    Example: 2017-12-31T12:00:00
  • 0—Indicates that the schedule never expires

  daysOfRunTillHour

Not implemented

0:00

  daysOfRunFromHour

Not implemented

0:00

  daysOfMonth

Not implemented

null

  transactionTimeout

Number of minutes a transaction is allowed to run before it is automatically timed out

String representing a numeric value

  startAtWithRandomDelay

Range, in minutes, within which the Execution Plan starts


  triggerType

Not implemented

CONTINUOUS

  daysOfWeek

Not implemented

null

  startAt

Date from when the schedule is in use

One of the following:

  • Date in format: YYYY-MM-DDThh:mm:ss
    Example: 2016-01-05T12:00:00
  • 0—Indicates that the schedule period is effective immediately

  intervalInMinutes

Number of minutes between runs of the Execution Plan

String representing a numeric value

inactive_by

Array of values indicating if the Execution Plan is inactive at the Execution Plan level ({inactiveBy: "USER"}), or at the Application level ({inactiveBy: "APPLICATION"}). Blank array( [] ) means active at both level. Should be in sync with parameter “userstatus”

Valid values:

[{inactiveBy: "APPLICATION"}]

[{inactiveBy: "USER"}]

applications

List of all the application in the form of pair of id and application name. Example: {"1": "demo", "110": "new"}.

Default value null

selectedApplicationId

(Mandatory) ID of the application on the Presentation Server

String representing a numeric value

agentGroups

Locations defined for the Execution Plan in the pair of id and name. Example: {"1": "Israel"}

Default value: null

  name

Name of the Location

String

  id

ID of the Location

Number

selectedAgentGroups

Array of the location id(s) of the agent groups. 

Number

attributes

Attributes of the script run by the Execution Plan (can be multiple)

You can obtain a list of attributes in a script from the Retrieving-script-details-API.


  encrypted

Indicates whether or not the attribute is encrypted

0—False

1—True; used for a password attribute

  length

Length of the attribute. The length is calculated by the Server

0—default length

You can type 0 (zero) as an input to the API.

  defaultValue

Default value of the attribute

Varies, depending on the attribute

  name

Name of the attribute

String

  encryptionType

Indicates whether the value parameter for the attribute is encoded

0—value is not encoded

1—value is encoded; used when you are setting a password attribute

  description

Description of the attribute

String

  type

Data type of the attribute

  • boolean
  • float
  • number
  • string

  value

Value of the attribute

Varies, depending on the attribute

For a password enter the Base64 encoded value, and set encryptionType to 1.

  order

Serial number of the appearance of the attribute in the user interface

Number

scripts

List of scripts available on the Presentation Server in the pair of id and name. Example: {"1": "FtpPinger.ltz", "2": "LdapPinger.ltz"}

Default value: null

    id

ID of the script

Number

   name

Name of the script

String

userStatus

Active\Inactive status at the Execution Plan level

0—value is Inactive

1—value is Active

executionLogSetting

Whether the Execution Log is saved.

  • ALWAYS
  • ON_ERROR
  • NEVER

Request body (applicable to versions 11.3.01 and earlier)

For versions 11.3.01 and earlier

The following code is an example of the JSON code to send with the request.

Note

This functionality requires that you send the entire JSON for the Execution Plan you want to save. Sending only the fields you want to update is not sufficient.


{
"executionPlanId" : 102,
"blackOuts" : [{
"startAtTimeOffset" : "UTC",
       "terminateAt": "2030-01-05T12:00:00",
"daysOfRunTillHour" : "17:00",
"daysOfRunFromHour" : "08:00",
"daysOfMonth" : null,
"triggerType" : "DAYS_OF_WEEK_BLACKOUT",
"daysOfWeek" : "1,2",
"blackoutName" : null,
"startAt" : "0"
}, {
"startAtTimeOffset" : "UTC",
"terminateAt" : "2030-02-25T08:10:00",
"daysOfRunTillHour" : "17:00",
"daysOfRunFromHour" : "08:00",
"daysOfMonth" : null,
"triggerType" : "DAYS_OF_WEEK_BLACKOUT",
"daysOfWeek" : "1,2",
"blackoutName" : null,
"startAt" : "2018-02-23T08:10:00"
           }
],
"projectType" : 0,
"scriptFileName" : "Pinger.ltz",
"description" : "",
"executionPlanName" : "ep_dot_auto",
"version" : 4,
"scriptFileCRC" : 1112554905,
"scheduler" : {
"startAtTimeOffset" : "UTC",
"terminateAt" : "0",
"daysOfRunTillHour" : "0:00",
"daysOfRunFromHour" : "0:00",
"daysOfMonth" : null,
"transactionTimeout" : 15,
"startAtWithRandomDelay" : 5,
"triggerType" : "CONTINUOUS",
"daysOfWeek" : null,
"startAt" : "0",
"intervalInMinutes" : 5
},
"scriptId" : 3,
"agentGroups" : [],
"scriptFileSize" : 67346,
"activeStatus" : 1,
"useGlobalScheduler" : false,
"attributeChangedEnvelopVersion" : 4,
"activeBy" : [true, true],
"attributes" : [{
"encrypted" : 0,
"defaultValue" : "1",
"name" : "Number of Pings",
"encryptionType" : 0,
"description" : "Number of pings to be sent",
"type" : "number",
"value" : "1",
"order" : 2
}, {
"encrypted" : 0,
"defaultValue" : "Sv_ICMP Ping",
"name" : "Timer Name",
"encryptionType" : 0,
"description" : "Name of the ICMP Ping Timer",
"type" : "string",
"value" : "Sv_ICMP Ping",
"order" : 4
}, {
"encrypted" : 0,
"defaultValue" : "",
"name" : "Host",
"encryptionType" : 0,
"description" : "The host being monitored",
"type" : "string",
"value" : "1.1.1.1",
"order" : 0
}, {
"encrypted" : 0,
"defaultValue" : "1.000000000",
"name" : "Ping Timeout",
"encryptionType" : 0,
"description" : "Timeout value for the ping in seconds",
"type" : "float",
"value" : "1.000000000",
"order" : 1
}, {
"encrypted" : 0,
"defaultValue" : "32",
"name" : "Data Size",
"encryptionType" : 0,
"description" : "\n        Size of the data package to be sent in bytes\n      ",
"type" : "number",
"value" : "32",
"order" : 3
}
],
"useGlobalBlackout" : false,
"applicationId" : 5,
   "syntheticApplicationId" : 3,
"syntheticApplicationName" : null,
"attributeChangedScriptVersion" : 1,
"executionLogSetting": "ON_ERROR"
}

Request body parameters (applicable to versions 11.3.01 and earlier)

Parameter

Description

Value

executionPlanId

ID of the Execution Plan

  • To create a new Execution Plan use 0.
  • To update a specific Execution Plan use the execution plan ID.

String representing a numeric value

blackOuts

Blackout periods defined for the Execution Plan (can be multiple)


     startAtTimeOffset

Clock used for calculating the blackout period

  • UTC—Universal Coordinated Time
  • LOCAL—Local time on the computer where the TEA Agent is installed

     terminateAt

Date from when the blackout period is no longer used

One of the following:

  • Date in format: YYYY-MM-DDThh:mm:ss
    Example: 2017-12-31T12:00:00
  • 0—Indicates that the blackout period never expires

     daysOfRunTillHour

End time for the blackout period

Format: hh:mm

Example: 21:00

     daysOfRunFromHour

Start time for the blackout period

Format: hh:mm

Example: 17:00

     daysOfMonth

Not implemented

null

     triggerType

Trigger for the blackout period

DAYS_OF_WEEK_BLACKOUT

     daysOfWeek

Days of the week when the blackout period is in effect

Comma-separated numeric values (0-6).

Example: 0,2,5 indicates that the blackout is in effect on Sunday, Tuesday, and Friday.

     blackoutName

Name of the blackout period

String

Name given to the blackout period

     startAt

Date from when the blackout period is in use

One of the following:

  • Date in format: YYYY-MM-DDThh:mm:ss
    Example: 2016-01-05T12:00:00
  • 0—Indicates that the blackout period is effective immediately

projectType

Type of Silk Performer project

String representing a numeric value

scriptFileName

Name of the script run by the Execution Plan

Content of this parameter is ignored.

String

description

Description of the Execution Plan

String

executionPlanName

Name of the Execution Plan

String

version

Execution Plan version

This number is updated every time the Execution Plan is updated.

Number

scriptFileCRC

Cyclic Redundancy Check of the script file

Content of this parameter is ignored.

String representing a numeric value

scheduler

Schedule defined for the Execution Plan


    startAtTimeOffset

Clock used for calculating the schedule

  • UTC—Universal Coordinated Time
  • LOCAL—Local time on the computer where the TEA Agent is installed

    terminateAt

Date from when the schedule is no longer used

One of the following:

  • Date in format: YYYY-MM-DDThh:mm:ss
    Example: 2017-12-31T12:00:00
  • 0—Indicates that the schedule never expires

    daysOfRunTillHour

Not implemented

0:00

    daysOfRunFromHour

Not implemented

0:00

    daysOfMonth

Not implemented

null

    transactionTimeout

Number of minutes a transaction is allowed to run before it is automatically timed out

String representing a numeric value

    startAtWithRandomDelay

Range, in minutes, within which the Execution Plan starts

String representing a numeric value

    triggerType

Not implemented

CONTINUOUS

    daysOfWeek

Not implemented

null

    startAt

Date from when the schedule is in use

One of the following:

  • Date in format: YYYY-MM-DDThh:mm:ss
    Example: 2016-01-05T12:00:00
  • 0—Indicates that the schedule period is effective immediately

    intervalInMinutes

Number of minutes between runs of the Execution Plan

String representing a numeric value

scriptId

ID of the script used by the Execution Plan

  • When creating a new Execution Plan, you must enter a scriptId.
  • When updating an existing Execution Plan, this cannot be modified.

String representing a numeric value

agentGroups

Locations defined for the Execution Plan


    name

Name of the Location

String

    id

ID of the Location

Number

scriptFileSize

Size of the script file used by the Execution Plan in bytes

Content of this parameter is ignored.

String representing a numeric value

activeStatus

Indication if the Execution Plan is active or not

String representing a numeric value

Valid values:

0—False

1—True

useGlobalScheduler

Not implemented

false

attributeChangedEnvelopVersion

Version number that is incremented each time there is a change in blackouts, schedule, or Execution Plan name

String representing a numeric value

activeBy

Array of two Boolean values indicating if the Execution Plan is active at the Execution Plan level, and at the Application level

Array

executionPlanName      

Name of the Execution Plan

String

attributes

Attributes of the script run by the Execution Plan (can be multiple)

You can obtain a list of attributes in a script from the Retrieving-script-details-API.


    encrypted

Indicates whether or not the attribute is encrypted

0—False

1—True; used for a password attribute

    defaultValue

Default value of the attribute

Varies, depending on the attribute

    name

Name of the attribute

String

    encryptionType

Indicates whether the value parameter for the attribute is encoded

0—value is not encoded

1—value is encoded; used when you are setting a password attribute

    description

Description of the attribute

String

    type

Data type of the attribute

  • boolean
  • float
  • number
  • string

    value

Value of the attribute

Varies, depending on the attribute

For a password enter the Base64 encoded value, and set encryptionType to 1.

    order

Serial number of the appearance of the attribute in the user interface

Number

useGlobalBlackout

Not implemented

false

applicationId

(Mandatory) ID of the application on the Presentation Server

String representing a numeric value

syntheticApplicationId

Synthetic application ID

This parameter is not updated by this API request.

String representing a numeric value

syntheticApplicationName

Name of the application

String

attributeChangedScriptVersion

Version number that is incremented each time there is a change in script attributes

String representing a numeric value

executionLogSetting

Whether the Execution Log is saved.

  • ALWAYS
  • ON_ERROR
  • NEVER

Related topics

Retrieving-Execution-Plans-API

Deleting-an-Execution-Plan-API

Developing

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*