Installation

The EasyVista Connector installation consists of multiple steps that are required to complete the installation successfully.

The connector requires a SMA OpCon Windows Agent to provide the connection between Notification Manager in the OpCon System and the EasyVista Connector software. It requires the OpCon Rest-API to extract the unique id of the task in the daily tables and the retrieval of the task's job log. It uses the OpCon connection to update the returned incident number in the task in the Daily tables.

Supported Software Levels

The following software levels are required to implement the Asysco AMT Connector.

OpCon Release 21.0 or higher.
Embedded Java OpenJDK 11 (part of installation).
OpCon Rest API Configured to use TLS.
OpCon Windows Agent to provide link to EasyVista Connector.
OpCon Notification Manager.
An EasyVista implementation that supports the Rest API.

Installation

The installation process consists of the following steps:

OpCon Windows Agent Installation.
EasyVista Connector Installation.
EasyVista Connector Configuration.
OpCon Notification Manager Definition

OpCon Windows Agent Installation

Copy the supplied install file SMAEasyVistaConnector-win.zip and extract it into the installation directory.

After the installation is complete, the root installation directory contains the connector executable (EasyVista.exe), the encryption software executable (Encrypt.exe), the Connector.config file and four directories, java, joblogs, templates and log. The java directory contains the java software required to execute the connector (OpenJDK 11), the joblogs directory is used to temporarily contain job logs extracted from the OpCon system, the log directory contains the connector log files and the templates directory contains the EasyVista template files.

EasyVista Connector Installation

The EasyVista connector can be installed on the OpCon Windows Server. Copy the downloaded install file SMAEasyVistaConnector-win.zip and extract it into a temp directory (c:\temp). Extract the information including sub-directories into the required directory.

Create $SCHEDULE DATE-EVIS Global Property

Create the special $SCHEDULE DATE-EVIS global property that contains the schedule date in the yyyy-MM-dd format from the standard $SCHEDULE DATE property. Set the value to yyyy-MM-dd.

EasyVista Connector Configuration

The configuration of the EasyVista Connector requires setting the OpCon connection information for the OpCon system associated with the connector.

All user and password values placed in the configuration and template files must be encrypted using the Encrypt.exe utility provided with the connector.

Encrypt Utility

The Encrypt utility uses standard 64 bit encryption.

Supports a -v argument and displays the encrypted value

On Windows, example on how to encrypt the value "abcdefg":

Encrypt.exe -v abcdefg

Connector.config configuration

Configure the Connector.config file in the installation directory setting the required information. The Connector.config contains the following values

Property Name	Value
[GENERAL]	header
JOBLOGDIR	The name of the directory where the retrieved log files are stored. After successful attachment to the EasyVista Incident, the log file is deleted. The name is a sub directory of the installation directory (default joblogs).
TEMPLATESDIR	The name of the directory where the template definitions are stored. The name is a sub directory of the installation directory (default templates).
DEBUG	The Connector supports a debug mode which can be enabled by setting the value to ON. The connector should be run with DEBUG disabled (OFF) and enabled (ON) when requested to capture an error condition. Value either ON or OFF (default OFF).
[PROXY SERVER]	header - Used to define the full URL of a proxy server if required
USES_PROXY	Indicates if this connector should use a Proxy Server connection. Values are True or False (default False).
ADDRESS	The address of the Proxy Server.
PORT	The port of the Proxy Server.
[OPCON API]	header - Used to define the connection to the OpCon API
ADDRESS	The server address of the OpCon API.
PORT	The port number used by the OpCon API server.
USES_TLS	Must be set to True.
TOKEN	An application token used for Authentication when communicating with the OpCon-API.
[TICKET DEFINITIONS]	header - Used to define information to be used when creating a ticket.
DESCRIPTION	The text that is used when creating an incident (description field). Default value OpCon Task Failure ( date {0} schedule {1} job {2} server {3} error code {4} ). The text is customizable. When a value is required in the text use the {n} syntax where n is the value of the parameter defined in the table below. 0 is the schedule date when the error occurred (resolves to [[$SCHEDULE DATE-EVIS]] value), 1 is the workflow name (resolves to [[JI.SCHED]] value), 2 is the task name (resolves to [[JI.JOB]] value), 3 is the server name where the job executed (resolves to [[JI.MACH]] value) and 4 is the termination code (resolves to [[JI.ECODE]] value).
TITLE	The text that is used when creating an incident (description field). Default value OpCon Task Failure (schedule {1} job {2}) The text is customizable. When a value is required in the text use the {n} syntax where n is the value of the parameter defined in the table below. 0 is the schedule date when the error occurred (resolves to [[$SCHEDULE DATE-EVIS]] value), 1 is the workflow name (resolves to [[JI.SCHED]] value), 2 is the task name (resolves to [[JI.JOB]] value), 3 server name where the job executed (resolves to [[JI.MACH]] value) and 4 the termination code (resolves to [[JI.ECODE]] value).

Example configuration file.

[GENERAL]
JOBLOGDIR=joblogs
TEMPLATESDIR=templates
DEBUG=OFF

[PROXY SERVER]
USES_PROXY=False
SERVER=
PORT=

[OPCON API]
SERVER=BVHTEST02
PORT=9010
USES_TLS=True
TOKEN=fc0520dc-fc93-4d3a-bf2f-7d0584c69df2

[TICKET DEFINITIONS]
DESCRIPTION=OpCon Task Failure ( date {0} schedule {1} job {2} server {3} error code {4} )
TITLE=OpCon Task Failure ( schedule {0} job {1} )

The OPCON API section provides the information about connecting to the OpCon System using the OpCon Rest-API so the job log can be retrieved from the OpCon task. The SERVER, PORT USES_TLS and TOKEN statements provide the definitions that will allow the EasyVista connector to connect to the OpCon Rest API. The TOKEN statement contains an application token (see OpCon Rest-API documentation on how to generate an application token).

Templates

Templates provide information about the EasyVista connection and the definitions that will be submitted in the JSON payload as part of the request. A default template can be found in the templates directory of the connector installation.

The template includes the address of the EasyVista instance, the credentials, the rules associated with the connector, attributes to be included and tag routing definitions.

A template includes the following definitions:

Attribute Name Name	Value
descriptionDefinition	Defines the description to use instead of the default description defined in the Connector.config. See section on Customized Description and Title Definitions.
titleDefinition	Defines the title to use instead of the default description defined in the Connector.config. See section on Customized Description and Title Definitions.
server	header - Defines the address, the company value and the template to display the incident associated with the EasyVista Instance
address	The address associated with the EasyVista instance (i.e. production, test)
usesTls	If the EasyVista instance requires TLS. Value either true or false (default true).
company	A string representing the company which is included in the URL when communicating with EasyVista.
viewIncidentUrlTemplate	The URL definition that can be used display the incident ticket in EasyVista. This url is invoked when the Incident Ticket ID of the job is selected in Solution Manager. See Generate AutoConnection Link section for information on generating this value.
rules	header - Defines what functions are supported by the connector.
includeJobLogAttachment	Indicates if the job log should be attached to the incident ticket. Value either true or false (default true).
includeTagRouting	Indicates if User defined tags should be used for incident routing purposes. Value either true or false (default false).
includeCorrelationId	Indicates if the correlation information should be included in the information submitted to EasyVista. Value either true or false (default false).
useTitleDefinitionForDescriptionDefinition	Indicates if the title definition should be used for the value of the description attribute. Value either true or false (default false).

(default false). credentials | header user | The user which has the required privileges to connect to the EasyVista System to submit requests. The name must be encrypted using the Encrypt.exe utility. password | The password of the user which has the required privileges to connect to the EasyVista System to submit requests. The password must be encrypted using the Encrypt.exe utility . ticketDefinitions | header - Defines attributes that will added to the JSON payload. indicator | A name that identifies this attribute to the connector. attribute | Defines the attribute name that will be added to the JSON payload along with the value. value | The value that will be included with the attribute. Note that a special value DescriptionDefinition can be used which will insert the generated OpCon fault message as the value for the attribute.
ticketAdditionalFields | header - Defines additional attributes that will added to the JSON payload. See EasyVista REST-API documentation for additional fields that can be included in the JSON payload. indicator | A name that identifies this attribute to the connector. attribute | Defines the attribute name that will be added to the JSON payload along with the value. value | The value that will be included with the attribute. Note that a special value DescriptionDefinition can be used which will insert the generated OpCon fault message as the value for the attribute.
tags | header - Defines information if OpCon User defined Tags are to be used to include attributes in the ServiceNow submission. This is enabled if the rule includeTagRouting is set to True. indicator | Defines what part of the tag should be used to identify the request. Supports TAG_END, TAG_START, EXIT or DEFAULT. The DEFAULT value is used if there is no TAG_END or TAG_START match and TAG Routing is enabled. indicatorValue | The value that is matched to the OpCon User defined tag (either the end or the start). attribute | Defines the attribute name that will be added to the JSON payload along with the value. value | The value associated with the attribute.

The server section of the template defines the address information associated with the EasyVista Instance. This allows a single connector the ability to submit requests to multiple EasyVista instances by simply creating multiple templates. The server section is required.

The rules section of the template defines which rules should be used for the request. Values are either true or false. The rules section is required.

The credentials section of the template defines the EasyVista user and password to be used for the connection. These values must be encrypted using the Encrypt.exe program. The credentials section is required.

The ticketDefinitions section defines required attributes that will be added to the payload. This includes either catalogueGui or catalogueCode, origin and description. The description attribute has a special value ‘DefinitionDescription’ which inserts the generated OpCon failure error message as the attribute value.

The ticketAdditionalFields section defines optional attributes that will be added to the payload.

The tags section defines incident routing information if OpCon Job User defined tags are used to route tickets. This functionality is enabled when the includeTagRouting rule is set to true. The OpCon task tag definition can therefore be used to determine the routing of the ticket within the EasyVista environment. It is possible to define multiple attributes for each tag definition (except EXIT tag).

Tag matching is performed, by first checking for an EXIT tag, followed by TAG_START and TAG_END values.

If a matching EXIT tag is found, no ticket is created. If matching TAG_END or TAG_START values are found, the associated attributes will be included in the ticket creation request. If no match is found, the DEFAULT associated attributes will be included in the ticket creation.

Tag routing is defined using the tags structure.

Indicator	Description
EXIT	Performs a match of against the complete job tag.
TAG_START	Indicates that the job tags will be checked for a matching value (Indicator Value field) from the start of each job tag in the list of tags.
TAG_END	Indicates that the job tags will be checked for a matching value (Indicator Value field) from the end of each job tag in the list of tags.
DEFAULT	Defines the attributes to used when there is no tag match.

{
  "descriptionDefnition" : "date @EV_Date job (@EV_Job) of schedule (@EV_Schedule) running on server (@EV_Agent) failed with error 
     code @EV_Errorcode",
  "titleDefinition" : "OpCon Task Failure (schedule @EV_Schedule job @EV_Job )",
  "server" : {
    "address" : "test-fr-vp-01.easyvista-training.com",
    "usesTls" : true,
    "company" : "50009",
    "viewIncidentUrlTemplate" : "https://test-fr-vp-01.easyvista-
          training.com/autoconnect_mail.php?field1=5C0F051E590F056F10&field2=&field4=%7BAF1AE6AD-FF4B-41B0-93B3- 
          99BEF6052B12%7D&field5=ViewDialog&field6={0}&field7=RFC_NUMBER"
  },
  "rules" : {
    "includeJobLogAttachment" : true,
    "includeTagRouting" : false,
    "includeCorrelationId" : true,
    "useTitleDefinitionForDescriptionDefinition" : false
  },
  "credentials" : {
    "user" : "633231686447566a61413d3d",
    "password" : "633231686447566a614449774d6a453d"
  },
  "ticketDefinitions" : [{
      "indicator" : "catalogCode",
      "attribute" : "Catalog_Code",
      "value" : "46"
    },{
      "indicator" : "origin",
      "attribute" : "Origin",
      "value" : "WEB Service"
    },{
      "indicator" : "description",
      "attribute" : "Description",
      "value" : "DefinitionDescription"
  }],
  "ticketAdditionalFields" : [{
      "indicator" : "urgencyId",
      "attribute" : "Urgency_ID",
      "value" : "1"
  }],
  "tags" : [{
      "indicator" : "TAG_END",
      "indicatorValue" : "",
      "attributes" : [{
          "attribute" : "",
          "value" : ""
      },{
          "attribute" : "",
          "value" : ""
      }]
  },{
      "indicator" : "TAG_START",
      "indicatorValue" : "",
      "attributes" : [{
          "attribute" : "",
          "value" : ""
      },{
          "attribute" : "",
          "value" : ""
      }]
  },{
      "indicator" : "DEFAULT",
      "indicatorValue" : "DEFAULT",
      "attributes" : [{
          "attribute" : "",
          "value" : ""
      },{
          "attribute" : "",
          "value" : ""
      }]
  },{
      "indicator" : "EXIT",
      "indicatorValue" : "NOTICKET",
      "attributes" : [ {
          "attribute" : "",
          "value" : ""
      }]
  }]
}

The above sample template uses environment variables for the description and title definitions. When using this implementation, a $JOB:ADD event must be used and the environment variables defined within the job being added by the event.

{
  "descriptionDefnition" : "",
  "titleDefinition" : "",
  "server" : {
    "address" : "test-fr-vp-01.easyvista-training.com",
    "usesTls" : true,
    "company" : "50009",
    "viewIncidentUrlTemplate" : "https://test-fr-vp-01.easyvista-
          training.com/autoconnect_mail.php?field1=5C0F051E590F056F10&field2=&field4=%7BAF1AE6AD-FF4B-41B0-93B3- 
          99BEF6052B12%7D&field5=ViewDialog&field6={0}&field7=RFC_NUMBER"
  },
  "rules" : {
    "includeJobLogAttachment" : true,
    "includeTagRouting" : false,
    "includeCorrelationId" : true,
    "useTitleDefinitionForDescriptionDefinition" : false
  },
  "credentials" : {
    "user" : "633231686447566a61413d3d",
    "password" : "633231686447566a614449774d6a453d"
  },
  "ticketDefinitions" : [{
      "indicator" : "catalogCode",
      "attribute" : "Catalog_Code",
      "value" : "46"
    },{
      "indicator" : "origin",
      "attribute" : "Origin",
      "value" : "WEB Service"
    },{
      "indicator" : "description",
      "attribute" : "Description",
      "value" : "DefinitionDescription"
  }],
  "ticketAdditionalFields" : [{
      "indicator" : "urgencyId",
      "attribute" : "Urgency_ID",
      "value" : "1"
  }],
  "tags" : [{
      "indicator" : "TAG_END",
      "indicatorValue" : "",
      "attributes" : [{
          "attribute" : "",
          "value" : ""
      },{
          "attribute" : "",
          "value" : ""
      }]
  },{
      "indicator" : "TAG_START",
      "indicatorValue" : "",
      "attributes" : [{
          "attribute" : "",
          "value" : ""
      },{
          "attribute" : "",
          "value" : ""
      }]
  },{
      "indicator" : "DEFAULT",
      "indicatorValue" : "DEFAULT",
      "attributes" : [{
          "attribute" : "",
          "value" : ""
      },{
          "attribute" : "",
          "value" : ""
      }]
  },{
      "indicator" : "EXIT",
      "indicatorValue" : "NOTICKET",
      "attributes" : [ {
          "attribute" : "",
          "value" : ""
      }]
  }]
}

The above sample template uses values in the config file for the description and title definitions.

Customized Description and Title Definitions

The description and title attribute values can be customized by using environment variables. If using this option, the EasyVista task must be started in Notification Manager by using a $JOB:ADD event instead of Run Command as Run Command does not support Environment Variables.

The OpCon properties are mapped to environment variables and these environment variables are then used in the message. When defining these environment variables the names must start with the value @EV indicating that the environment variable is an EasyVista environment variable. During connector startup, any environment variables starting with @EV are loaded into the mapping table. These values associated with the variables are then inserted into the values of the description and title attributes.

  "descriptionDefnition" : "date @EV_Date job (@EV_Job) of schedule (@EV_Schedule) running on server (@EV_Agent) failed with error 
     code @EV_Errorcode",
  "titleDefinition" : "OpCon Task Failure (schedule @EV_Schedule job @EV_Job )",

Looking at the above extract from the template, the variables in the attribute value of the description attribute will change as follows:

date @EV_Date job (@EV_Job) of schedule (@EV_Schedule) running on server (@EV_Agent) failed with error code @EV_Errorcode
OpCon Task Failure (schedule @EV_Schedule job @EV_Job )

date 2021-10-26 job (EvFailure_DEF) of schedule (EasyVista Tests) running on server (LocalWin) failed with error code 0000000001
OpCon Task Failure (schedule EasyVista Tests job EvFailure_DEF )

Generate Auto Connection Link

The viewIncidentUrlTemplate attribute of the server section in the template, is used to create a direct link to the created Incident ticket. The link can be generated for the environment by using the following procedure within EasyVista.

Select Administration > Access Management > Auto Connection Link in the EasyVista menu.
Enter the following parameters
- Form Name = DialogF0_Incidents
- Field Name = RFC_NUMBER
- Value = Incident_Number
Click Generate Link
After the link has been generated, copy and then paste the generated link into the template changing the Incident_Number to {0}. (field5=ViewDialog&field6=Incident_Number&field7=RFC_NUMBER) (field5=ViewDialog&field6={0}&field7=RFC_NUMBER)

OpCon Notification Manager Definition

Notification Manager is used to execute the EasyVista Connector when a task completes with a failure condition. Using this approach allows the tasks to be added to the rule instead of defining a failure event on every task. If using environment variables to customize the description and title fields, a $JOB:Add event must be used instead of Run Command as the Run Command option does not support environment variables.

Configuring $JOB:ADD event

Using Notification Manager, select the Jobs tab and create a new Group called EasyVista. Once the Group has been created, select the EasyVista Group, perform a ‘right-click’ and select Add Job Trigger. In the Add Job Trigger selection, select Job Failed.

In the Notification Definitions section, select Send OpCon/xps Events. In the Event tab, select Add event and select the $JOB:ADD template.

Insert the following definition to perform a $JOB:ADD of the Windows task that will execute the EasyVista Connector.

[[$SCHEDULE DATE]],AdHoc,EASY-VISTA,DAILY,ID=[[$JOBID]];MACH=[[$MACHINE NAME]];SCHED=[[$SCHEDULE NAME]];JOB=[[$JOB NAME]];ECODE=[[$JOB TERMINATION]];SID=[[$SCHEDULE ID]];SINST=[[$SCHEDULE INST]],Y

Configuring Run Command

In the Run Command tab, enter the following:

Command C:\Connectors\EasyVista\EasyVista.exe -a [[$MACHINE NAME]] -s [[$SCHEDULE NAME]] -jn [[$JOB NAME]] -e [[$JOB TERMINATION]] -sd [[$SCHEDULE DATE-EVIS]] -si [[$SCHEDULE ID]] -sn [[$SCHEDULE INST]] -t bas_easyvista.json

                       Where 
                       C:\Connectors\EasyVista\EasyVista.exe    is the location of the connector.
                       -a [[$MACHINE NAME]]                     resolves to the agent name
                       -s [[$SCHEDULE NAME]]                    resolves to the schedule name
                       -jn [[$JOB NAME]]                        resolves to the job name
                       -e [[JOB TERMINATION]]                   resolves to the job termination code
                       -sd [[$SCHEDULE DATE-EVIS]]              resolves to the date (format YYYY-MM-DD)
                       -si [[$SCHEDULE ID]]                     resolves to the schedule ID
                       -sn [[$SCHEDULE INST]]                   resolves to the schedule instance
                       -t bas_easyvista.json                    which template in the templates folder to use

Working Directory C:\Connectors\EasyVista

Batch User Use Service Account The batch User under which the task will be run.

Definition of EASY-VISTA task in OpCon AdHoc workflow

If the $JOB:ADD option was selected when configuring Notification Manager, add the EASY-VISTA task to the AdHoc schedule. Create a Windows Job, associated with the agent that the EasyVista Connector was installed on.

Set the Command Line, inserting the full path name of the EasyVista Connector executable and the required arguments. C:\Connectors\EasyVista\EasyVista.exe -a [[JI.MACH]] -s [[JI.SCHED]] -jn [[JI.JOB]] -e [[JI.ECODE]] -sd [[$SCHEDULE DATE-EVIS]] -si [[JI.SID]] -sn [[JI.SINST]] -t template
Set the -t option (template) to the template value defined for this EasyVista instance. The template must be placed in the templates directory of the EasyVista installation.
Set the working directory to the full path of the EasyVista Connector installation directory
Create a frequency called ALLDAYS allowing the task to be scheduled 7 days a week.
Select Disable Build.
Select Allow Multi-Instance.
Add the required environment Variables matching the definitions in the descriptionDefinition and titleDefinition fields of the template.

Installation

Supported Software Levels​

Installation​

OpCon Windows Agent Installation​

EasyVista Connector Installation​

Create $SCHEDULE DATE-EVIS Global Property​

EasyVista Connector Configuration​

Encrypt Utility​

Connector.config configuration​

Templates​

Customized Description and Title Definitions​

Generate Auto Connection Link​

OpCon Notification Manager Definition​

Configuring $JOB:ADD event​

Configuring Run Command​

Definition of EASY-VISTA task in OpCon AdHoc workflow​

Supported Software Levels

Installation

OpCon Windows Agent Installation

EasyVista Connector Installation

Create $SCHEDULE DATE-EVIS Global Property

EasyVista Connector Configuration

Encrypt Utility

Connector.config configuration

Templates

Customized Description and Title Definitions

Generate Auto Connection Link

OpCon Notification Manager Definition

Configuring $JOB:ADD event

Configuring Run Command

Definition of EASY-VISTA task in OpCon AdHoc workflow