23 Replies Latest reply on Feb 5, 2010 5:10 PM by wallewek

    Getting Started with Kiwi CatTools API

      Is there a tutorial for getting started with the CatTools API? I'm finding the documentation in this area to be somewhat lacking. From the 9.1 Environments section:

      In the VBA menu Tools/Reference select "Kiwi CatTools API" from the available references. 

      Is this instruction speaking to how to setup the MS Visual Basic Editor? The 8.1 Script Editors section mentions that any script editor will do, however, basic text editors don't have the functionality to reference an external library. Where is the "Kiwi CatTools API" DLL (library) on the filesystem?

      Given the 9.2.1.1 Sample Code used to establish a connection to the CatTools database via it's API. The the first variable in this script is cast as a CatToolsAPI.Database. How do you reference the "Kiwi CatTools API" library so that this script may cast this type of variable?

      Dim DB As CatToolsAPI.Database 
      Set DB = New CatToolsAPI.Database 
      DB.EncryptionPassword = "MyPassword" 
      If DB.OpenConnection Then
      MsgBox "Connected ok" 
      Else 
      MsgBox "DB connection failed: " & DB.ErrDescription 
      End If 
      DB.CloseConnection 
      Set DB = Nothing
      
        • Re: Getting Started with Kiwi CatTools API
          Steve Welsh

          The Script editors section 8.1 under the Custom scripting Chapter 8 section is with respect to creating device and activity custom scripts.

          The CatTools API does not form part of the custom scripting facility in CatTools which is why it has been written as a separate chapter in the help file.  The CatTools API is only available to licensed customers (i.e. not Freeware users).   If you create an application or code that uses the CatTools API, then you can only run this on the system where CatTools has been installed, as it needs to read the CatTools license details in order to work.

          Because of the capabilities of the CatTools API (i.e. it can modify device data in the CatTools database), it is assumed that a person using the API would have a reasonable knowledge of Visual Basic programming skills and so probably be familiar with the Visual Basic development environment, for example Visual Studio; or alternatively knows how to utilize the VBA programming environment (Visual Basic editor) within MS Office applications.  This is why the API sample code is written in VB/VBA form.  In these development environments, you can add a reference to the CatTools API called "Kiwi CatTools API".  Once the reference has been added, you should be able to simply copy and paste the sample code from the CatTools API help pages into your VB project and it will work.

          However, if you are using a text editor (such as Notepad), you won't be able to add a reference to the CatTools API as you have found.  For text editors, you need to change the code slightly to use the 'CreateObject' function to reference the CatToolsAPI available classes.

          For example:

          Dim DB
          Set DB = CreateObject("CatToolsAPI.Database")

          would be used to replace the code in your sample above of:

          Dim DB As CatToolsAPI.Database
          Set DB = New CatToolsAPI.Database

          You can then save the text file as a VBScript (.VBS) file and run it.

          In order for the API code to work, the CatTools API library file (Cattools.dll) must be registered on the system correctly, which you can do using the following from the START > RUN dialog:

          regsrv32 "C:\Windows\system32\cattools.dll"

          Hope this helps.

          Steve

            • Re: Getting Started with Kiwi CatTools API

              The command listed above to register the .dll "regsrv32" just needs to be updated to "regsvr32".  The r and v just needed to be switched around.

              regsvr32 "C:\Windows\system32\cattools.dll"

               

              Marcus

              • Re: Getting Started with Kiwi CatTools API

                Steve,

                Thanks much for the full explanation. The filesystem location and name of the dll is really what I was missing here (I should have better phrased my inquiry). Your examples and identification of the CreateObject caveat is great. We'll give her a go and let you know how we come along.

                Thanks,
                Lee

                  • Re: Getting Started with Kiwi CatTools API
                    Steve Welsh

                    You are welcome Lee.  Look forward to hearing how things turn out.

                      • Re: Getting Started with Kiwi CatTools API

                        Steve,

                        I may be doing something wrong here. I'm running into an error after adding the CatTools.dll as a reference in my VB project (see attached screenshot). As you can see, I'm using Microsoft Visual Basic 2008 Express Edition. I have the Add Reference screen open and after clicking OK to add the reference am getting the following pop-up error. 'Tis a shame Visual Basic doesn't give a more descriptive error. Can you point me in the right direction here? Are you available to chat either via instant messenger or voice?

                        Gtalk: leecalcote
                        AIM: lcalcote5343
                        VOIP: 1 (512) 340-3159 CST

                        Thanks,
                        Lee

                          • Re: Getting Started with Kiwi CatTools API
                            Steve Welsh

                            Hi Lee,

                            Unfortunately I don't have Microsoft Visual Basic 2008 Express Edition to test on, however I've tried add a reference within Visual Studio 2008 and it works fine (I tried this after installing CatTools v3.3.11 which I'm guessing is the same version you are running based on the CatTools.dll version shown above.)

                            This would then suggest either its an issue with the dll (maybe try uninstalling CatTools and reinstalling it to see if this fixes the CatTools.dll), or an issue with Microsoft Visual Basic 2008 Express Edition not being able to reference a COM dll?

                            Can you maybe try the VBScript approach I mentioned above (using say Notepad.exe) to make sure that you can at least use the API classes successfully?

                            Finally, are you using a licensed version of CatTools or the Freeware edition?  The Freeware edition can't use the CatTools API as it requires the same full Kiwi CatTools license in order to work.

                            Steve

                              • Re: Getting Started with Kiwi CatTools API

                                Steve,

                                We've been successful in making API calls. I appreciate your help. From the API documentation, I see that we're able to work with the Devices, Device Groups and Device Types. Does the API provide functionality to interact with Activities? For example, we'd like to use the API to modify the Device.CLI.Send Activity type.

                                On another note, when making API calls, do we need to ensure the timer is stopped? We're wondering about this since when working with the UI, you need to stop the timer before the bottom toolbar (Add, Edit, Remove, Copy, etc) becomes available.

                                Thanks,
                                Lee

                                  • Re: Getting Started with Kiwi CatTools API

                                    Steve,

                                    I'm wondering if you can assist me in regard to this issue: Solarwinds Case # 88273. I've had this case open since Monday and have yet to receive a callback. Could you assist in escalating this issue? Your assistance on this forum inquiry has been wonderful. I'm looking for the same support in real-time.

                                    Thanks,
                                    Lee

                                      • Re: Getting Started with Kiwi CatTools API
                                        Steve Welsh

                                        Hi Lee,

                                        With regards to your Solarwinds Case #88273, I have sent you a reply via the support case and have copied in the person handling this case.

                                        I've also raised a development ticket to update the CatTools API help documentation with a bit more 'meat' as I agree it was a little lacking.  I'll probably just be adding what we have discussed here on the forum for now, but if there is anything else specific you feel its missing which you would have found useful in getting you started with the API, please let me know and I'll see if I can add this in at the same time.

                                        Kind regards,

                                        Steve

                                      • Re: Getting Started with Kiwi CatTools API
                                        Steve Welsh

                                        Lee,

                                        Glad you've got the API working.

                                        Currently the API will only work on updating devices or device related data.   There are no activity related public classes available within the API to modify activities.

                                        When you say you want to use the API to modify a Device.CLI.Send commands activity, are you wanting to modify the commands that the activity is sending to the device(s), or modify something else?  If it’s just the commands, then I'd recommend taking a look at the on-line Help file page: http://www.kiwisyslog.com/help/cattools/act_devclisendcmd_setup.htm   You may be able to use the 'Or, read command from a file:' option to read in different sets of commands form different files by utilizing the command variables (Meta variables) that get translated at run-time.

                                        Steve

                                          • Re: Getting Started with Kiwi CatTools API

                                            Steve,

                                            Thanks for being on top of these questions and the support case. Your help is most appreciated. Regarding the exposure of Activity classes through the API, our use of CatTools hinges on the ability to programatically (not using the UI) schedule backups for devices. With the current API classes, we're able to add devices and groups, but need the ability to scheduled their backups as well. Is there any chance a request to have Activity classes made public would be answered in a short timespan?

                                            Lee

                                              • Re: Getting Started with Kiwi CatTools API
                                                chris.lapoint

                                                We've been asked for this capability by several other customers as well, so this is certainly on our roadmap.   Unfortunately, we cannot make any committments on timeframe - certainly not a short timespan.

                                                  • Re: Getting Started with Kiwi CatTools API
                                                    chris.lapoint

                                                    I meant to ask in my previous post.   Can you describe how you would use an API for scheduling backup jobs?   Why an API versus scheduling this through the existing GUI? 

                                                      • Re: Getting Started with Kiwi CatTools API

                                                        Hey Chris,

                                                        Sure. We're looking at archiving configurations of tens of thousands of devices, the connectivity details of which are stored in a database outside of CatTools. We'd like to populate the CatTools database with this device information and subsequently programmatically schedule their backups (activites). We're trying to stear clear of manual data entry through the CatTools UI.

                                                        Hope this helps. Feel free to inquire of further details, if this doesn't quite paint a full picture.

                                                        Lee

                                                          • Re: Getting Started with Kiwi CatTools API
                                                            chris.lapoint

                                                            Thanks Lee.  That clarifies it for me.  One last question, would you be okay with pre-configuring the backup config activity (with a list of devices) using the CatTools UI and then programatically executing the activity?   Or, do you have to be able to programatically configure the activity as well?

                                                              • Re: Getting Started with Kiwi CatTools API

                                                                Chris,

                                                                Yes, provided we’re able to setup predefined Activities that are broad-scoping enough in nature as to schedule groups of devices for configuration backup at given times, we may be able to work around the missing API functionality in the short-term.

                                                                I’m not sure that we’ll necessarily need to programmatically control the execution of an Activity. Creation, modification and deletion of an Activity is the functionality we were hoping for (unless I’m confused by what you were asking).

                                                                It may be that we’re able to get away with very infrequently using the CatTools UI to create a new Activity, if we’re able to intelligently think through generic (predefined) Activities that a newly added device falls into and is included in the next round of backups for that given device group/Activity schedule. Does that makes sense? What I’m trying to say here is that if when adding a new device to CatTools, a user rarely needs to bring up the UI to schedule a new Activity, but most newly added devices fall under a pre-existing backup strategy (Activity), we may be ok (short-term). I don’t believe our need to rearrange backup schedules (Activity times) is that frequent an occurrence. I’ll confirm and get back to you.

                                                                On another note, Steve mentioned the “best practice” of stopping the timer when adding, modifying, deleting devices and groups through the API. Could we get a little background on this? Having to pause our backup activities to interact with the API (database) is a potential showstopper. Is the CatTools database “locked” so to speak while the Timer is on? What do we risk when exercising the API while the Timer is on?

                                                                You alluded to a less than short timeline in exposing Activity related classes through the API. Ballpark – how much time are we talking?

                                                                Thanks,
                                                                Lee

                                                                  • Re: Getting Started with Kiwi CatTools API

                                                                    Chris, Steve,

                                                                    The reason I ask about stopping the Timer before API/database interaction is that would be unfortunate to have to interrupt Activities whenever an API call is made. API calls are expected to be made at will by users and may be fairly frequent. I assume the ability to start and stop the Timer has been exposed through the API, but haven't looked...

                                                                    Lee

                                                                      • Re: Getting Started with Kiwi CatTools API
                                                                        Steve Welsh

                                                                        Lee,

                                                                        You actually guessed correctly in your previous post the reason why it is recommended the timer is off when you use the API. 

                                                                        In the UI, you have to stop the Timer (and ensure that no activity is currently running) in order to maintain (add/remove/edit) devices.  This releases the logical database 'lock' that prevents you from inadvertently changing a device that an activity (or one that could potentially begin while in the process of maintaining a device) is associated with and could therefore be in the process of collecting data from.

                                                                        As the API can basically perform the same function as the 'Add', 'Remove' and 'Edit' buttons in the UI, it is recommended that the Timer is stopped for this very same reason.

                                                                        Unfortunately, the starting and stopping of the Timer has not been exposed in the API.  One of the reasons is that (as mentioned above); you also need to ensure that there is no currently running activity which is a little more complicated to handle within the API.

                                                                        Reading in to your activity requirements though, it appears that what you really need is a method of automatically adding a new device to an existing scheduled activity, correct?

                                                                        Steve

                                                                • Re: Getting Started with Kiwi CatTools API

                                                                  I'm looking for the same functionality, and don't see any solution here.  Could you help, please?

                                                                  In short, I need some way to make the CatTools timer more reliable.  Don't argue, it's terrible.  It stops on any little provocation, and the only way to restart it is to log in onto the server, launch the user interface, and click on the "Start Timer" button again.  That's no way to run a service.

                                                                  CatTools should not require the timer to be stopped in order to make changes; it should simply pause the timer while changes are in progress, and resume it when they are done.  It should also automatically resume the timer after a reboot if it was running before. 

                                                                  In the mean time, I would very much appreciate seeing a script stub that either:

                                                                  a) allows starting/restarting the timer programmatically (i.e., from a vb or powershell script) via a Windows scheduled task, or

                                                                  b) allows running specific predefined activities the same way.

                                                                  Frankly, I really think CatTools should use the WIndows task scheduler for all it's timer scheduling.  It doesn't have those issues.

                                                                  I have to admit, I'm a little frustrated about this.  I've missed a lot of updates and wasted a lot of time because the CatTools timer keeps stopping.  I contacted Support about it; they first didn't understand the issue, and when I clarified it, didn't bother to even respond.  If I had a bit of code I could run as a scheduled script to resolve this, I'd be tickled.

                                                                  /kenw

                                                                    • Re: Getting Started with Kiwi CatTools API
                                                                      chris.lapoint

                                                                      Despite its use of a service for scheduling, CatTools remains a desktop utility that leverages an Access DB.  As noted by Spartacus above, this comes along with certain limitations on locking.   If you need more advanced, multi-task scheduling, you might consider evaluating Orion NCM to see if it meets your needs.

                                                                        • Re: Getting Started with Kiwi CatTools API

                                                                          Chris, I'm not sure I understand what you're saying.  I don't understand your reference to "advanced, multi-task scheduling"?

                                                                          Are you saying that it will never be possible to use an API to launch a predefined activity in CatTools, so long as it uses an Access database?  Would that also apply to (say) launching CatTools with a command-line option to run a predefined activity and then exit?

                                                                          I'm just looking for some way to reliably run configuration backups on a regular basis.  I'm looking at my Activity log right now, and even though the timer appears to be active, the last daily backup ran nearly a week ago.  It's a little hard to tell if there are any recent Info logs; those doesn't show entry dates, just times.

                                                                          All I'm looking for is a way to programmatically simulate manually launching CatTools, clicking on the Run Now button, and closing it it again a few minutes later.  Doesn't seem so hard...  or complicated...

                                                                          /kenw

                                                              • Re: Getting Started with Kiwi CatTools API
                                                                Steve Welsh

                                                                RE> On another note, when making API calls, do we need to ensure the timer is stopped? We're wondering about this since when working with the UI, you need to stop the timer before the bottom toolbar (Add, Edit, Remove, Copy, etc) becomes available

                                                                Because the CatTools API is directly modifying the data in the CatTools database (i.e. the underlying device values used within an activity), it would always be recommended that the CatTools scheduler timer has been stopped and that no activity is currently running before the API code/script is executed.

                                                                (I'll add this to the documentation updates for the API help file pages as well)

                                                                Steve