The following plugin provides functionality available through Pipeline-compatible steps. Read more about how to integrate steps into your Pipeline in the Steps section of the Pipeline Syntax page.

For a list of other such plugins, see the Pipeline Steps Reference page.

Cadence vManager Plugin for Jenkins

vmanagerLaunch: Cadence vManager Session Launcher

  • vAPIUrl
    vManager expose a REST API interface for API. The REST API is a dedicated process for serving remote http requests - vAPI.
    Starting 14.1 s005 The vAPI process is served automatically by the vManager Server process, and as such you need to supply the following url:
    https://[VMANAGER_HOST:VMANAGER_PORT]/vmgr/vapi
    For vmanager 14.1 s002, the vAPI process need to get started manually, as such, the url syntaxt is:
    http://[VAPI_HOST:VAPI_PORT]/vmgr

    • Type: String
  • vAPIUser
    In case of a secure mode, the userId will be shown as the user who perform the operation within vManager tool.
    In case of open mode, the default userid that will be used is "vapi".
    • Type: String
  • vAPIPassword
    In case of a secure mode, a password is needed
    Please contact vManager documentation for further info.
    • Type: String
  • vSIFName
    • Type: String
  • vSIFInputFile
    In case of a need in dynamically selecting the vsif files to get launched per job, the pre-job should place into the workspace directory a file with the full paths of the relevant vsif files to be launched, new line for each additional vsif file.
    The input file should be place into the working directory. In case this field is empty, The file name need to be: ${BUILD_NUMBER}.${BUILD_ID}.vsif.input
    Please fill this field only in case, you want to hard code the input file name, to be consist across all builds.
    The output of all IDs of the launched sessions can be found at: ${BUILD_NUMBER}.${BUILD_ID}.session_launch.output
    • Type: String
  • credentialInputFile
    Supported only from 16.1 and above.
    vManager can execute jobs in one of two modes:
  • Same user permissions (the account permission where the vManager server is installed) for all jobs launched by the vAPI/Jenkins.
  • Use the Linux account permissions of the actual user who is doing the launch operation.

  • Default (unchecked above) is for the vManager to launch job by using the account permissions where the server is installed.
    When this box is checked, user can choose between using the same credentials used within the authentication section above, or supply a file with user/password in plain text containing only two lines:
    username
    password

    For this (dynamic user/password), a pre-job should place any file into its working directory, and supply the full path to it.
    In case this field is empty, The file name need to be: ${BUILD_NUMBER}.${BUILD_ID}.credential.input, and should be place in the working directory of the current running build.
    Please fill this field only in case you want to hard code the input file name, to be consist across all builds.
  • Type: String
  • deleteInputFile
    • Type: boolean
  • deleteCredentialInputFile
    • Type: boolean
  • useUserOnFarm
    • Type: boolean
  • authRequired
    vManager vAPI can operate in one of two modes:
  • Secured by user/secret key
  • Open
  • In case of a secure mode, the userId (vAPI User) will be shown as the user who perform the operation within vManager tool.
    In case of open mode, the default userid that will be used is "vapi".
  • vsifType
    • Type: String
  • userFarmType
    • Type: String
  • dynamicUserId
    In case of a need in dynamically selecting the user name per job, the pre-job should place into the workspace directory a file with single line that contains the userid to be used.
    The file name should be: ${BUILD_NUMBER}.${BUILD_ID}.user.input"
    The job will pick the userid which is in the file, and connect to vAPI using this userid and the vAPI secret key.
    • Type: boolean
  • advConfig
    • Type: boolean
  • connTimeout
    Connection Timeout is the time (in minutes) for the Jenkins executor to wait till it establish a connection with the vManager server. It is usually very fast, so no need to change the default (1 minute).
    Setting the time to 0 means an unlimited time. In case it is taking too long to establish a connection, and the time passed is more than the Connection Timeout set, the connection to the vManager server will be closed, and the Jenkins executor will be able to continue. The vAPI operation will fail (it will not start), and the build will be marked as failed.
    If no Connection timeout is set, the default is 1 minutes.
    • Type: int
  • readTimeout
    Read Timeout is the time (in minutes) for the Jenkins executor to wait for vManager server to end the current operation. In heavy operations such as collect compact or ranking, the time to response back can vary, and might even take an hour or so depends on the load the vManager server is experiencing.
    Setting the time to 0 means an unlimited time. In case the vAPI call is taking too long, and is more than the Read Timeout set, the connection to the vManager server will be closed, and the Jenkins executor will be able to continue. The vAPI operation will not fail, but the build will be marked as failed.
    If no Read timeout is set, the default is 30 minutes.
    • Type: int
  • envVarible
    • Type: boolean
  • envVaribleFile
    Supported by vManager 15.1 and above only
    In case of a need in adding the vsif environment variables, the pre-job should place into the workspace directory a file with a list of relevant environment variables in json keys format.
    Example:
    "MY_REGRESSION_AREA": "/home/dan/regression",
    "MY_DUT" : "top"
    (Note the comma seperator at the end of each line, to exclude the last line.)
    The input file should be place into the working directory. In case this field is empty, The file name need to be: ${BUILD_NUMBER}.${BUILD_ID}.environment.input
    Please fill this field only in case, you want to hard code the input file name, to be consist across all builds.
    • Type: String
  • inaccessibleResolver
    The following setup allow you to select how the build will behave in each of the state where the session stop from running.

    Continue
    In case you select to continue, the build will assume (on the chosen state) for a given session that it can continue and finish the wait on this specific session.
    Please note that in case there are multiple sessions that are being executed by this step, the build will wait till all sessions got into a state that allow it to continue.

    Ignore
    In case you select to continue, the build will assume (on the chosen state) for a given session that it can ignore the chosen state and keep waiting for other state (until get the 'completed' state).

    Fail
    In case you select to fail, the build will assume (on the chosen state) for a given session that it should mark this build as a failure build. Note: If you have multiple sessions on this build step, it is enough for one single session to be marked as 'failed' in order to mark the entire build as a failed build.

    Other Waiting Considerations
    1. When all sessions on this build step are having the state 'completed' the build will be marked as success.
    2. When the vManager server goes down, the build step will keep waiting till the server will go back up. The build step will only change its state based on sessions state changes.
    3. If the session was manually deleted on the vManager server, before reaching into final state, the build will be marked as a failure build.
    4. In any case, if the number of minutes waiting is bigger than the timeout set here, the build will marked as a failed build.
    • Type: String
  • stoppedResolver
    • Type: String
  • failedResolver
    • Type: String
  • doneResolver
    • Type: String
  • suspendedResolver
    • Type: String
  • waitTillSessionEnds
    • Type: boolean
  • stepSessionTimeout
    • Type: int
  • generateJUnitXML
    • Type: boolean
  • extraAttributesForFailures
    • Type: boolean
  • staticAttributeList
    • Type: String
  • markBuildAsFailedIfAllRunFailed
    • Type: boolean
  • failJobIfAllRunFailed
    • Type: boolean
  • envSourceInputFile
    Supported by vManager 17.10 and above only
    In case of a need in adding the vsif environment variables, users can create a list of aliases and store them within a file. The job will 'source' that file prior of reading the vsif.
    Note that this can also serve for any pre stage execution, not just for aliases.
    Relative path is also supported (aka ~/doSomething.sh).
    Script must be in bash.

    The file should be place into a directory with a read permission for the user who launches the regression.
    In case this field is empty, this field is ignored
    • Type: String
  • vMGRBuildArchive
    • Type: boolean
  • deleteAlsoSessionDirectory
    Choosing to delete vManager session during build removal, will trigger an operation during manual/automatic deletion of a build, to deal with the remote session/sessions that were created during that build on the vManager DB.
    When this option is enabled the build will place an instruction file (sdi.properties) within the job directory that specify the sessions to get deleted, as well as other parameters - that will be used during the delete operation.

    Builds that runs while this option is turned off, will not get effected during removal, and will keep their sessions.

    You can choose between two methodologies:

    Sync Delete Methodology (built-in)
    In case you select the sync methodology, the plugin will call vManager vAPI during the build removal process for deleting the sessions that were created during that same build.
    With this option you can also supply a generic user/password to be used for the delete operation, otherwise, the same user that was used during the build will be picked automatically.
    Please note that the sync methodology is lacking two main aspects:
    1. Since Jenkins ignores any exception thrown within the callback functions of RunListener, the build will get deleted even if the session failed to get deleted from vManager DB.
    2. When the vAPI is down, it can take up to 20 seconds to finish the operation (as it needs to wait till vAPI will be available) - the UX at that time, might appear sluggish to the end user.

    Async Delete Methodology (externally)
    In case you want to introduce a more robust approach (promise session deletion even if vManager Server is down, as well as faster UX), you should use the async methodology.
    When Async Methodology is used, the callback function will not try to delete the session, but instead will copy the sdi.properties file into an external location of your choice.
    You should create an additional job, one that is triggered every 1 minute for scanning that directory (and trying to delete the relevant sessions within these sdi files). To exclude the copy of the sdi files during build removal, this flow is not managed by the plugin.
    Please note - defining an external directory location (in windows) requires the use of forward slash instead of backslash.
    • Type: boolean
  • genericCredentialForSessionDelete
    • Type: boolean
  • archiveUser
    • Type: String
  • archivePassword
    • Type: String
  • famMode
    • Type: String
  • famModeLocation
    • Type: String
  • noAppendSeed
    • Type: boolean
  • pipelineNodes
    • Type: boolean
  • masterWorkspaceLocation
    In case of master/nodes setup, in which the job is running on the nodes, the workspace location is of the nodes, not the master.
    The vManager plugins stores run's data at the master location, and as such need to know the full path for the master workspace per build.

    Example:
    (pipelineNodes: true, masterWorkspaceLocation: c:/jenkins/workspace)
    • Type: String
  • markBuildAsPassedIfAllRunPassed
    • Type: boolean
  • failJobUnlessAllRunPassed
    • Type: boolean
  • userPrivateSSHKey
    • Type: boolean
  • attrValues
    • Type: boolean
  • attrValuesFile
    Supported by vManager 17.1 and above only
    In case of a need in setting the vsif attribute values, the pre-job should place into the workspace directory a file with a list of relevant attributes and their values (one line per each attribute) in the following format.
    Line 1: attribute_name,attribute_value,attribute_type
    Line 2: attribute_name,attribute_value,attribute_type

    attribute type can be 1 of 3:
    P_SESSION for session type attributes
    P_TEST for test type attributes
    P_GROUP for group type attributes
    Example:
    home_location,/home/dan/regression,P_SESSION
    owner,dan,P_TEST
    (Note the comma seperator within the lines. Do not place comma at the end of the lines.)
    The input file should be place into the working directory. In case this field is empty, The file name need to be: ${BUILD_NUMBER}.${BUILD_ID}.attr.values.input
    Please fill this field only in case, you want to hard code the input file name, to be consist across all builds.
    • Type: String
  • executionType
    • Type: String
  • sessionsInputFile
    This option is useful for those who wish to take benefit of their own environment and scripts for launching sessions using batch, but still want the benefit of having the Job waiting for the execution to end, generates JUnit report, produce triage link, real time view of the run's progress, summary report, etc'.
    This option is also useful for those who wish to take advantage of this plugin, but are not using the vManager Runner, and uses "collect" mode instead. For such flow they can still benefit from generated JUnit report, triage link, real time view of the run's progress, summary report, etc'.
    In this option, there is an assumption that a pre-step (usually from shell type) is taking over the session launch operation (or collect), and as such, in order for this plugin to continue monitoring those sessions - the session names need to be exchange between the shell step and this step.

    In case of a need to launch the sessions using batch as a pre-step to this one (or collect), the pre-step should place into the workspace directory a file with the session or session names that were launched/collected - new line for each session name.
    The input file should be place into the working directory. In case this field is empty, The file name need to be: ${BUILD_NUMBER}.${BUILD_ID}.sessions.input
    Please fill this field only in case, you want to hard code the input file name, to be consist across all builds.

    the vManager plugin will look for any of the input files mentioned above, and query the server for their respective id automatically. From that point and on, the flow continues as if the sessions were launched/collected by this plugin.

    The output of all IDs of the launched/collected sessions can be found at: ${BUILD_NUMBER}.${BUILD_ID}.session_launch.output
    • Type: String
  • deleteSessionInputFile
    • Type: boolean
  • vmanagerPostBuildActions: vManager Post Build Actions

  • advConfig
  • dynamicUserId
    In case of a need in dynamically selecting the user name per job, the pre-job should place into the workspace directory a file with single line that contains the userid to be used.
    The file name should be: ${BUILD_NUMBER}.${BUILD_ID}.user.input"
    The job will pick the userid which is in the file, and connect to vAPI using this userid and the vAPI secret key.
  • connTimeout
    Connection Timeout is the time (in minutes) for the Jenkins executor to wait till it establish a connection with the vManager server. It is usually very fast, so no need to change the default (1 minute).
    Setting the time to 0 means an unlimited time. In case it is taking too long to establish a connection, and the time passed is more than the Connection Timeout set, the connection to the vManager server will be closed, and the Jenkins executor will be able to continue. The vAPI operation will fail (it will not start), and the build will be marked as failed.
    If no Connection timeout is set, the default is 1 minutes.
  • readTimeout
    Read Timeout is the time (in minutes) for the Jenkins executor to wait for vManager server to end the current operation. In heavy operations such as collect compact or ranking, the time to response back can vary, and might even take an hour or so depends on the load the vManager server is experiencing.
    Setting the time to 0 means an unlimited time. In case the vAPI call is taking too long, and is more than the Read Timeout set, the connection to the vManager server will be closed, and the Jenkins executor will be able to continue. The vAPI operation will not fail, but the build will be marked as failed.
    If no Read timeout is set, the default is 30 minutes.
  • advancedFunctions
  • retrieveSummaryReport
  • runReport
  • metricsReport
  • vPlanReport
  • testsViewName
  • metricsViewName
  • vplanViewName
  • testsDepth
  • metricsDepth
  • vPlanDepth
  • metricsInputType
  • metricsAdvanceInput
    In case of a need to take advantage of the full summary report flags, you can use a json structure to define the rest of the flags the vAPI supports.
    The following structure addresses the flags relevant for the metrics part only (for more information, check the full vAPI electronic docs on the web):
    {
    "depth": 4,
    "instances": true,
    "types": true,
    "extended": true,
    "path": "string",
    "scope": "string"
    }

    depth: integer ($int32) (Metrics tree level depth. Default value is the whole tree)
    scope: string (Metrics verification scope)
    path: string (Full Path to entity in Metrics tree.)
    instances: boolean (Specify if vPlan entity is in the instances hierarchy)
    types: boolean (Specify if vPlan entity is in the types hierarchy)
    extended: boolean (Enables or disables extended metrics report, if not specified the report would be extended according to metrics configuration)

    None of the fields are mandatory to exclude "depth".
  • vPlanInputType
  • vPlanAdvanceInput
    In case of a need to take advantage of the full summary report flags, you can use a json structure to define the rest of the flags the vAPI supports.
    The following structure addresses the flags relevant for the vPlan part only (for more information, check the full vAPI electronic docs on the web):
    {
    "depth": 4,
    "perspective": "string",
    "multiPerspectives": [array - look for more information within the documentation] "instances": true,
    "types": true,
    "extended": true,
    "path": "string",
    "vplanNode": "string"
    }

    { "depth": 20, "perspective": "APB_UART", "instances": true, "types": true, "extended": true } depth: integer ($int32) (vPlan tree level depth. Default value is the whole tree)
    perspective: string (Perspective to report. if not specified the default plan perspective would be used)
    multiPerspectives: [...]
    vplanNode: string (Full Path to perspective/section/port in vPlan tree.)
    path: string (specify if to use vplanNode, instances or types for vPlan entity. If not specified the perspective is used)
    instances: boolean (Specify if vPlan entity is in the instances hierarchy)
    types: boolean (Specify if vPlan entity is in the types hierarchy)
    extended: boolean (Enables or disables extended vplan report. if not specified the report would be extended according to vplan configuration)

    None of the fields are mandatory to exclude "depth".
  • vPlanxFileName
  • summaryType
  • ctxInput
  • ctxAdvanceInput
    In case of a need to take advantage of the full summary report flags, you can use a json structure to define the rest of the flags the vAPI supports.
    The following structure addresses the flags relevant for the vPlan and Metrics parts and gives you more control over refinements (for more information, check the full vAPI electronic docs on the web):
    {
    "depth": 4,
    "refinementFile": "string",
    "vplanFile": "string",
    "vplanRefinementFile": "string",
    "environment": "string",
    "multiPerspectives": [array - look for more information within the documentation],
    "multiPerspectives": [array - look for more information within the documentation],
    "multiPerspectives": [array - look for more information within the documentation]
    }

    None of the fields are mandatory, however - please note that adding "vplanFile" here, will overwrite anything you placed within "vPlanx file name".
    ("vPlanx file name" field is not mandatory in case you choose to use the advanced context input)
  • freeVAPISyntax
    In case of a need in taking full control over the vAPI parameters of the summary report, the pre-job should place into the workspace directory a file with the json input for the /reports/generate-summary-report vAPI.
    The input file should be place into the working directory. In case this field is empty, The file name need to be: ${BUILD_NUMBER}.${BUILD_ID}.summary_report.input
    Please fill this field only in case, you want to hard code the input file name, to be consist across all builds.
    Please exclude the "rs" section from this json. This plugin will automatically fill in the "rs" based on the sessions launched during the build process.
  • deleteReportSyntaxInputFile
  • vManagerVersion
  • sendEmail
  • emailList
  • emailType
  • emailInputFile
    In case of a need in providing a dynamic list of email addresses, the pre-job should place into the workspace directory a file with the relevant emails, one email address per line (without a comma between).
    The input file should be place into the working directory. In case this field is empty, The file name need to be: ${BUILD_NUMBER}.${BUILD_ID}.emails.input
    Please fill this field only in case, you want to hard code the input file name, to be consist across all builds.
    Disclaimer: In case you choose to work with the "free vAPI syntax" option, you have the option to supply the list of emails as part of the free vAPI json structure (optionally) - in such cases, this field will be ignored.
  • deleteEmailInputFile
  • summaryMode
  • ignoreSSLError
    This option is only relevant if you choose vManager Version < 19.09.
    If the vManager version is smaller than 19.09, the report is being retrieved by parsing the html web page of the report generated using http connection.
    Since vManager Web Server is having by default a self-signed certificate, normal http connection will fail to get validated and the connection will get rejected.
    If you replaced the server certificate with a signed one of your own, you can leave it as default. Unless, if you are using the default vManager installed self-signed certificate - the only way to overcome its SSL validation is to allow the connection from the Jenkins to the vManager server at the time of the report retrieval only to skip validation.

  • Was this page helpful?

    Please submit your feedback about this page through this quick form.

    Alternatively, if you don't wish to complete the quick form, you can simply indicate if you found this page helpful?

        


    See existing feedback here.