Server-based Steps
Server-based steps were designed to allow the workflow developer to interrogate the vast knowledge that Avantra obtains about a managed object to control the flow of subsequent steps or to update Avantra based on the result of a workflow.
Consider a workflow example that has specific steps for Microsoft Windows vs Ubuntu installations. This can be guarded by an IF step to execute only the needed steps for the platform and a server-based step can be used to get the criteria needed to determine which branch to execute.
|
Not all APIs are available for server-based steps compared to regular steps
running on an agent. We provide the Additionally, the |
Code Walkthrough
Creating a server-based JavaScript step is easily accomplished from the Step Library. Simply select the 'Run on Avantra Server' checkbox in the step properties.
Interrogating managed objects
Server-based steps have access to a rich API of information Avantra has collected about managed objects. This API is accessible via the global object avantra and the sub-object systems. From there you should select which type of object you wish to interrogate e.g. servers, databases or sapsystems. Each of these has two methods of retrieving an object:
-
Pass the name of the object, as recorded in Avantra, to get the managed object result.
-
Pass the Avantra ID to retrieve the requested result. The Avantra ID can be found in the UI or is available when a system is used as input.
|
It is possible for multiple objects to share the same name for some managed object types. Always prefer using getById(..) if possible. |
The returned object has properties containing information that can be used to control subsequent steps by outputting additional information to the workflow variables that are used as input to following steps or as input to IF/LOOPS to make the workflow generic. Let’s see this in action:
const s1 = avantra.systems.servers.getByName("eiger")
const d1 = avantra.systems.databases.getById(1148)
// Conditional logic based on memory assigned to server
if (s1.physicalMemory < 32 * 1024 * 1024) {
// Low memory system, perform different logic...
log.debug("low mem")
action.output.low_mem = true
} else {
// Standard logic
log.debug("high mem")
action.output.low_mem = false
}
// Format version information
log.debug(d1.databaseType + " " + d1.version)
// Interrogate the server of the database
action.output.server_id = d1.server.systemId
// d1.server is a server object and contains all the same information as
// a server retrieved by avantra.systems.server.getByName(..)
log.debug("Memory of database server: " + d1.server.physicalMemory)Interrogating check results
Check data can be interrogated from server-based steps also and there are multiple ways to do this depending on the use case. This API is accessible via the global object avantra and the sub-object checks. There are two method calls that can be used to list checks:
-
Pass the name of the check, as configured in Avantra, to get the all check results caused by a check with that name.
-
Pass the check ID to retrieve the check result with this ID. If both a daily check and RTM check exist with the same ID, the RTM result is returned.
Let’s take a look at an example where we ask for a specific check, in this case
the built in check CPULOAD, filter on a specific status, and then output the
result as a selector. This result would then be directly used as a variable for
a loop and perform maintenance or additional processing on each system.
const allCPU = avantra.checks.getByName("CPULOAD")
log.debug("Total number of CPULOAD checks: " + allCPU.length)
action.output.warning_checks = allCPU
// Filter the list for only those with a specific status
.filter(cpu => cpu.status == avantra.Status.WARNING)
// Collect only the systemIds for processing in the workflow
.map(cpuCheck => cpuCheck.system.systemId)
// Debug: output the list of failed statuses
action.output.warning_checks.forEach(cpu => log.debug(cpu))|
The Avantra server-based API respects the customer chosen when executing the workflow. This means that the results will be limited to those systems/checks within that execution customer. |
As you’ve seen above, you can read the system from the check result. This
object contains the same information and properties as the systems API.
Additionally, you can read the checks linked to a system using similar APIs o
the system object using the getCheckByName(..) method
or all checks via getChecks(..).
Evaluating system selectors
System selectors are also available in server-based steps and can be accessed by via the global object avantra and the sub-object systems. There are then three options to retrieve a selector:
-
Retrieve a system selector by it’s ID. The ID can be found in the Avantra UI. This method is preferred as it doesn’t rely on the name or duplicate named selectors not existing.
-
If you need to retrieve the system selector by it’s name only, you can do so using this method. However there might be multiple selectors with the same name depending on how the workflow is executed and this method returns a list of matching selectors.
-
findFirstSystemSelectorsByName(..)
If you need to retrieve the system selector by it’s name and you are only interested in the first item, this method will do that or return null if there are no matches.
A system selector can optionally be queried for customer, description, name etc. that would be entered in the UI. See SystemSelector for more information.
Ultimately, you can execute the system selector to return a list of system objects with the same properties as querying systems individually as well as their check information. In this way you can provide custom, enhanced system selector logic for subsequent steps in the workflow.
const abapSysSelector = avantra.systems.findFirstSystemSelectorsByName("ABAP Systems")
if (abapSysSelector) {
const sysList = abapSysSelector.list()
log.debug("Number of systems found by selector: " + sysList.length)
// Give me all the systems in this selector that have the system role "Education"
// OR, have a NumberRanges check that is CRITICAL
action.output.abap_list = sysList
.filter(abap => abap.systemRoleName == "Education" ||
(abap.getCheckByName("NumberRanges").length > 0 &&
abap.getCheckByName("NumberRanges")[0].status == avantra.Status.CRITICAL))
.map(abap => abap.systemId)
action.output.abap_list
.forEach(abap => log.debug(abap))
} else {
// System selector not found!!
action.output.abap_list = []
action.success = false
action.message = "No system selector found!!"
}Creating external check results
External check results can be created through the server-based steps as a result
of previous steps or using information from external sources such as the web
API.
An external check result is created via the global object avantra, the sub-object checks and the createExternalCheck(..) function by passing the name of the external check to be created.
const myExternalCheck = avantra.checks.createExternalCheck("External check name")Other information can then be attached to the external check object returned, such as the status and any message you wish to display in the UI.
myExternalCheck.message = "This was not successful!!!"
myExternalCheck.status = avantra.Status.WARNINGThe external check is then attached to a system object retrieved by one of the various methods described so far (by ID, check, selector etc.). For example:
avantra.systems.getById(182).attachExternalCheck(myExternalCheck)External checks can also be removed from an object with a similar API call:
avantra.systems.getById(182).detachExternalCheck("External check name")A more complete example would be:
const myExternalCheck = avantra.checks.createExternalCheck("External check name")
myExternalCheck.message = action.input.check_message
myExternalCheck.status = avantra.Status.WARNING
avantra.systems.getById(action.input.system).attachExternalCheck(myExternalCheck)API Reference
Global Variable avantra
Avantra Server Script API
applicationVersion( )
applicationVersion(): stringReturns the current version of the application.
- Since
-
24.1
- Returns
-
string
an instance of String
currentTimeMillis( )
currentTimeMillis(): numberReturns the current time in milliseconds.
- Since
-
24.1
- Returns
-
number
an instance of long
currentTimestamp( )
currentTimestamp(): stringReturns the current timestamp in format: YYYY-MM-dd HH:mm:ss
- Since
-
24.1
- Returns
-
string
an instance of String
NoteImplementationStatus
readonly NoteImplementationStatus: NoteImplementationStatus- Type
- Modifiers
-
Readonly
Class AbapSoftwareComponent
software component
Class Check
check
isNotificationDisabled( )
isNotificationDisabled(): Boolean- Since
-
24.2
- Returns
-
Boolean
true if notification is disabled
- See Also
checkedWhileMonitoringOff
checkedWhileMonitoringOff: Booleanchecked while monitoring off
- Type
-
Boolean
- Since
-
24.2
confirmationDateMillis
confirmationDateMillis: numberconfirmation date (milliseconds)
- Type
-
number
- Since
-
24.2
confirmationUntilMillis
confirmationUntilMillis: numberconfirmation until (milliseconds)
- Type
-
number
- Since
-
24.2
notificationDisabled
readonly notificationDisabled: Boolean- See Also
- Type
-
Boolean
- Modifiers
-
Readonly
- Since
-
24.2
Class CloudInfo
cloud info
asAwsCloudInfo( )
asAwsCloudInfo(): AwsCloudInfoCast to aws cloud info. Returns null if not possible.
- Since
-
24.3
- Returns
-
aws cloud info
asAzureCloudInfo( )
asAzureCloudInfo(): AzureCloudInfoCast to azure cloud info. Returns null if not possible.
- Since
-
24.3
- Returns
-
azure cloud info
asFakeCloudInfo( )
asFakeCloudInfo(): FakeCloudInfoCast to fake cloud info. Returns null if not possible.
- Since
-
24.3
- Returns
-
fake cloud info
asGoogleCloudInfo( )
asGoogleCloudInfo(): GoogleCloudInfoCast to google cloud info. Returns null if not possible.
- Since
-
24.3
- Returns
-
google cloud info
asVmWareCloudInfo( )
asVmWareCloudInfo(): VmWareCloudInfoCast to VMware cloud info. Returns null if not possible.
- Since
-
24.3
- Returns
-
VMware cloud info
Class Database
database
getBusinessObjects( )
getBusinessObjects(): SapBusinessObject[]business object from the database
- Since
-
24.2
- See Also
businessObjects
readonly businessObjects: SapBusinessObject[]business object from the database
- See Also
- Type
-
SapBusinessObject[]
- Modifiers
-
Readonly
- Since
-
24.2
Class MonitoredSystem
monitored system
attachExternalCheck(..)
attachExternalCheck(externalCheck: ExternalCheck): void- Since
-
24.2
- Parameters
-
-
externalCheck: ExternalCheckthe external check to attach to the system
-
detachExternalCheck(..)
detachExternalCheck(checkName: string): void- Since
-
24.2
- Parameters
-
-
checkName: stringname of external check to detach from the system
-
getAdministrator( )
getAdministrator(): User- Since
-
24.2
- Returns
-
administrator of the system
- See Also
getApplicationTypeName( )
getApplicationTypeName(): string- Since
-
24.2
- Returns
-
string
application type name
- See Also
getCheckByName(..)
getCheckByName(name: string): Check[]- Since
-
24.2
- Parameters
-
-
name: stringcheck name
-
- Returns
-
Check[]
check of the system
getMoniParam(..)
getMoniParam(name: string): stringRetrieve the monitoring parameter by name for this system.
- Since
-
24.3
- Parameters
-
-
name: stringthe name of the monitored parameter to retrieve
-
- Returns
-
string
the monitored parameter or null if not found
getSystemRoleName( )
getSystemRoleName(): string- Since
-
24.2
- Returns
-
string
system role name
- See Also
applicationTypeName
readonly applicationTypeName: string- See Also
- Type
-
string
- Modifiers
-
Readonly
- Since
-
24.2
monitoringOffReasons
monitoringOffReasons: MonitoringOffReason[]monitoring off reasons
- Type
-
MonitoringOffReason[]
- Since
-
24.2
Class NamespaceChecks
createExternalCheck(..)
createExternalCheck(name: string): ExternalCheck- Since
-
24.2
- Parameters
-
-
name: stringname of external check
-
- Returns
-
instance of new external check
getById(..)
getById(checkId: any): Check- Since
-
24.2
- Parameters
-
-
checkId: anycheck id
-
- Returns
-
a check (rtm or daily, if id has both rtm check is returned)
getById(..)
getById(checkId: any, rtmFirst: boolean): Check- Since
-
24.2
- Parameters
-
-
checkId: anycheck id
-
rtmFirst: booleanOnly if check is a rtm and daily check, true returns the rtm check and false return the daily check
-
- Returns
-
a check (rtm or daily)
Class NamespaceDatabases
getById(..)
getById(systemId: any): Database- Since
-
24.2
- Parameters
-
-
systemId: anysystem id
-
- Returns
-
a database
Class NamespaceSapInstances
getById(..)
getById(systemId: any): SapInstance- Since
-
24.2
- Parameters
-
-
systemId: anysystem id
-
- Returns
-
a sap instance
getByName(..)
getByName(name: string): SapInstance- Since
-
24.2
- Parameters
-
-
name: stringsap instance name
-
- Returns
-
a sap instance
Class NamespaceSapsystems
getById(..)
getById(systemId: any): SapSystem- Since
-
24.2
- Parameters
-
-
systemId: anysystem id
-
- Returns
-
a sap system
getByName(..)
getByName(name: string): SapSystem- Since
-
24.2
- Parameters
-
-
name: stringsap system name
-
- Returns
-
a sap system
Class NamespaceServers
Class NamespaceSystems
findFirstSystemSelectorsByName(..)
findFirstSystemSelectorsByName(name: any): SystemSelectorFind the first system selectors with a name. NOTE: this call only finds non-ad-hoc system selectors.
- Since
-
24.2
- Parameters
-
-
name: any
-
- Returns
-
the first system selector with the given name or null if there is no such system selector.
findSystemSelectorsByName(..)
findSystemSelectorsByName(name: any): SystemSelector[]Find all system selectors with a name. NOTE: this call only finds non-ad-hoc system selectors.
- Since
-
24.2
- Parameters
-
-
name: any
-
- Returns
-
SystemSelector[]
the list system selectors with the given name or an empty list if there is no such system selector.
getById(..)
getById(systemId: any): MonitoredSystem- Since
-
24.2
- Parameters
-
-
systemId: any
-
- Returns
-
a system
getSystemSelectorById(..)
getSystemSelectorById(id: any): SystemSelectorFind a system selector by its id.
- Since
-
24.2
- Parameters
-
-
id: any
-
- Returns
-
the system selector or null if it can not be found.
databases
readonly databases: NamespaceDatabasesNamespace: databases
- Type
- Modifiers
-
Readonly
- Since
-
24.2
sapinstances
readonly sapinstances: NamespaceSapInstancesNamespace: sapinstances
- Type
- Modifiers
-
Readonly
- Since
-
24.2
sapsystems
readonly sapsystems: NamespaceSapsystemsNamespace: sapsystems
- Type
- Modifiers
-
Readonly
- Since
-
24.2
Class SapClient
sap client
changesAndTransportsForClientSpecificObjects
changesAndTransportsForClientSpecificObjects: numberchange and transports for client specific objects
- Type
-
number
- Since
-
24.2
Class SapInstance
Class SapNoteImplementation
sap note
implementationStatus
implementationStatus: NoteImplementationStatusimplementation status
- Type
- Since
-
24.2
Class SapSystem
sap system
getAbapSoftwareComponents( )
getAbapSoftwareComponents(): AbapSoftwareComponent[]- Since
-
24.2
- Returns
-
AbapSoftwareComponent[]
a list of all abap components
- See Also
getClients( )
getClients(): SapClient[]- Since
-
24.2
- Returns
-
SapClient[]
a list of all clients
- See Also
getDatabaseMonitoringServer( )
getDatabaseMonitoringServer(): Server- Since
-
24.2
- Returns
-
database monitoring server
- See Also
getInstances( )
getInstances(): SapInstance[]- Since
-
24.2
- Returns
-
SapInstance[]
a list of all sap instances
- See Also
getJ2eeSoftwareComponents( )
getJ2eeSoftwareComponents(): J2eeSoftwareComponent[]- Since
-
24.2
- Returns
-
J2eeSoftwareComponent[]
a list of all j2ee components
- See Also
getNamespaceChangeOptions( )
getNamespaceChangeOptions(): NamespaceChangeOption[]- Since
-
24.2
- Returns
-
NamespaceChangeOption[]
a list of all namespace change options
- See Also
getRemoteMonitoringServer( )
getRemoteMonitoringServer(): Server- Since
-
24.2
- Returns
-
remote monitoring server
- See Also
getSapLicenses( )
getSapLicenses(): SapLicenseBase[]- Since
-
24.2
- Returns
-
SapLicenseBase[]
a list of all licenses
- See Also
getSapNotes(..)
getSapNotes(onlyNewest: boolean): SapNoteImplementation[]- Since
-
24.2
- Parameters
-
-
onlyNewest: boolean
-
- Returns
-
SapNoteImplementation[]
a list of all sap notes
getSoftwareChangeOptions( )
getSoftwareChangeOptions(): SoftwareChangeOption[]- Since
-
24.2
- Returns
-
SoftwareChangeOption[]
a list of all software change options
- See Also
getSolutionManager( )
getSolutionManager(): SapSystem- Since
-
24.2
- Returns
-
the solution manager
- See Also
getSolutionManagerConnectedSystems( )
getSolutionManagerConnectedSystems(): SapSystem[]- Since
-
24.2
- Returns
-
SapSystem[]
a list of all systems connected from solution manager
- See Also
J2eeSoftwareComponents
readonly J2eeSoftwareComponents: J2eeSoftwareComponent[]- See Also
- Type
-
J2eeSoftwareComponent[]
- Modifiers
-
Readonly
- Since
-
24.2
abapSoftwareComponents
readonly abapSoftwareComponents: AbapSoftwareComponent[]- See Also
- Type
-
AbapSoftwareComponent[]
- Modifiers
-
Readonly
- Since
-
24.2
avantraTransportVersion
avantraTransportVersion: stringAvantra transport version
- Type
-
string
- Since
-
24.2
avantraTransports
avantraTransports: AvantraTransport[]Avantra transports
- Type
-
AvantraTransport[]
- Since
-
24.2
databaseMonitoringServer
readonly databaseMonitoringServer: Server- See Also
- Type
- Modifiers
-
Readonly
- Since
-
24.2
databasePreventAutomaticUpdate
databasePreventAutomaticUpdate: booleanprevent automatic updates for database
- Type
-
boolean
- Since
-
24.2
instances
readonly instances: SapInstance[]- See Also
- Type
-
SapInstance[]
- Modifiers
-
Readonly
- Since
-
24.2
namespaceChangeOptions
readonly namespaceChangeOptions: NamespaceChangeOption[]- See Also
- Type
-
NamespaceChangeOption[]
- Modifiers
-
Readonly
- Since
-
24.2
remoteMonitoringEntryPoint
remoteMonitoringEntryPoint: stringremote monitoring entry point
- Type
-
string
- Since
-
24.2
remoteMonitoringServer
readonly remoteMonitoringServer: Server- See Also
- Type
- Modifiers
-
Readonly
- Since
-
24.2
sapLicenses
readonly sapLicenses: SapLicenseBase[]- See Also
- Type
-
SapLicenseBase[]
- Modifiers
-
Readonly
- Since
-
24.2
softwareChangeOptions
readonly softwareChangeOptions: SoftwareChangeOption[]- See Also
- Type
-
SoftwareChangeOption[]
- Modifiers
-
Readonly
- Since
-
24.2
Class Server
server
getDatabases( )
getDatabases(): Database[]- Since
-
24.2
- Returns
-
Database[]
a list of databases on this server
- See Also
getInstances( )
getInstances(): SapInstance[]- Since
-
24.2
- Returns
-
SapInstance[]
a list of sap instances on this server
- See Also
instances
readonly instances: SapInstance[]- See Also
- Type
-
SapInstance[]
- Modifiers
-
Readonly
- Since
-
24.2
Class SystemSelector
system selector
list( )
list(): MonitoredSystem[]evaluate system selector
- Since
-
24.2
- Returns
-
MonitoredSystem[]
system list