smatechnologies / opcon-cli-java

Command line utility for Windows & Linux to interact with OpCon

OpCon CLI

A command line utility for Windows & Linux that uses the OpCon Rest-API to interact with OpCon. Provides functions to manage machines, machine groups, jobs, properties, thresholds and schedules.

Prerequisites

• Uses the OpCon Rest-API to perform the functions, so an OpCon Rest-API license is required.
• requires OpCon 18.3 or greater.
• This command line utility requires Java version 11 to function:
  • An embedded OpenJDK JRE is included along with the delivery zip/tar files, and can be found under "/java" folder. So no need to install it manually on your environment.

Instructions

Is a command utility that submits requests to OpCon using the SMA OpCon Rest-API. The utility is available for both Windows and Linux.

See documentation for the complete documentation.

It consists of a single program opconcli.exe for Windows and opconcli for Linux.

Supported Tasks

The opconcli program provides the following tasks:

• AppToken: Used to create an application token
• Dependency: Used to check a job dependency on a remote OpCon System. It tracks the execution of the remote job waiting for job completion. Retrieves the job log of the remote job and terminates with the same termination code as the remote job (requires OpCon 17.1 or greater).
• ExpEval: Evaluates an OpCon expression.
• GetJobLog: Retrieve the job log of a job in a schedule in the Daily tables (requires OpCon 17.1 or greater).
• JobAction: JobAction Performs an action on a job in the Daily tables (available actions are estimatedStartTime, hold, cancel, skip, kill, start, restart, forceRestart, restartOnHold, release, markFinishedOk, markFailed, markUnderReview, markFixed).
• JobAdd: Add a job to schedule in the Daily tables. Includes an option to wait for the completion of the job that has been added.
• MachAction: Performs an action on a machine or list of machines (available actions are up, down, limited, wlimited). The option wlimited option, sets the machine into limited state and waits until all current executing jobs on the machine to complete before returning.
• MachAdd: Add a machine or list of machines to the OpCon System.
• MachGrpAdd: Add the machines to the machine group.
• MachGrpRemove: Removes the machines from the machine group.
• MachUpdate: Update machine name, IP address or DNS address.
• PropExp: Uses the expression evaluator to update properties. If the property does not exist it is created. Supports global and instance properties.
• PropUpdate: Updates the value of a global property for OpCon 18.1 and beyond (supports encryption).
• SchedAction: Performs an action on a schedule (available actions are hold, release, start, close).
• SchedBuild: Build a schedule (requires OpCon 18.1 or greater).
• SchedRebuild: Rebuilds schedules in the daily (requires OpCon 18.1 or greater).
• ThreshUpdate: Updates the value of a threshold.
• Version: Retrieves the version of a the SMA OpCon-RestAPI

See command line arguments, for complete description of arguments to pass and associated examples.

Installation

Windows Instructions

Download OpConCLI_Windows.zip file from the desired release available here.

After download, extract the zip file to the location you'd like to install the command line utility. Once unzipped, everything needed should be located under the root folder of that directory.

Linux Instructions

Download OpConCLI_Linux.tar.gz file from the desired release available here.

Disclaimer

No Support and No Warranty are provided by SMA Technologies for this project and related material. The use of this project's files is on your own risk.

SMA Technologies assumes no liability for damage caused by the usage of any of the files offered here via this Github repository.

License

Copyright 2019 SMA Technologies

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Contributing

We love contributions, please read our Contribution Guide to get started!

Code of Conduct

SMA Technologies has adopted the Contributor Covenant as its Code of Conduct, and we expect project participants to adhere to it. Please read the full text so that you can understand what actions will and will not be tolerated.

opcon-cli-java's Issues

Documentation modification for PropExp

There is an error in the documentation concerning the PropExp task.
The use of the -ev argument is not indicated.

Can you provide us with an example of its use?

Thank you

Convert opcon-cli documentation to markdown

The current documentation is a docx file, in order to provide a simpler contribution process (and versioning), it would be neat to rather have a markdown documentation.

Wrong check on machineAction

Hello,

checkIfMachineJobsFinished get the field currentJobs on Machine. I think this field should contain the number of running job on the machine and not the status of the machineactions.

It should check instead the result field of /api/machineactions/{id}:

  "machines": [
    {
      "id": 2459,
      "result": "success",
      "message": "Machine status for [MACHINE] changed to [D] by ocadm"
    }
  ],
  "id": 110,
  "action": "down",
  "result": "success",
  "expires": "2023-07-30T00:11:49.3552014+02:00"

Please check

Fix case-sensitive info in documentation

The documentation provides examples that are not working out-of-the-box, related to case-sensitiveness or Task arguments.

Problems connecting to OpCon 20

Unrecognized field "isExternalTokenDisabled" when trying to connect to OpCon version 20.

Deprecate word (.docx) documentation

Since we now have markdown documentation for the connector, we want to keep only one source of truth.

To that intent, we have decided to delete the .docx file to avoid having to maintain two files. We might consider generating exported version of the markdown documentation (e.g. html) - this will be evaluated at a later time.

Linux - Could not find or load main class

Hi,
I just installed opcon-cli on linux and it doesn't work. I followed every instructions and already have runned it successfully on the windows version.
Here is my error :

Is it possible that it doesn't work because of the authorizations on folders ? Thank you for your help

PropUpdate

the -pe parameter does not work with the PropUpdate function.
Without this parameter the PropUpdate function works correctly.

Whit -pe

Whitout -pe

Problems with Dependency task

when using Dependency task and the monitored job is a NULL job, termination code is not interpreted correctly.

GetEstimatedStartTime

Would it be possible to add the GetEstimatedStartTime Function?

Thanks in advance ..

Provide the Linux version

Provide the Linux version of OpCon CLI.

• Make code change to generate a Linux binary
• Update CI to include generate and share Linux archive (binaries, JRE).

App Token support for system authentication

Currently the CLI supports user/pwd per system in its configuration file to connect to the remote system. It would be neat to have the hability to rather use an app token instead of storing user/pwd. This would allow disregarding user's password change policy.

Correction of the documentation.

Hello,

Can you change the Opcon-CLI-JAVA documentation?

Indeed there is an error concerning the json template. It's necessary to put a [ at the beginning of the template and one ] at the end.

Thank you

$JOB:DELETE

Hi,

I have two quesions:

Would it be possible to add the schedule date to the output of the GetEstimatedStartTime Function?

Example of old utility: Estimated Start time for Job EindeTestBatch of Schedule C-ASSIST-TEST-Selfservice on Schedule Date 04/06/2020 is : 04/06/2020 : 22:55
Example of new utility: Estimated Start time for Job EindeTestBatch of Schedule C-ASSIST-TEST-Selfservice is 04/06/2020 : 20:43

We could use the current date but this makes the calculation a bit more reliable.

Would it also be possible to add a $JOB:DELETE property?
When the end time of the schedule is exceeded, we want to remove the adhoc job which is responsible for the late end time.

Thanks in advance

Best regards,

Gertjan Altenburg