Integrating Adaptive with 3rd-party Software

The Adaptive Desktop provides various ways for third-party software developers to integrate with Adaptive software functionally. There are two sides to integration:

  1. Macros - driving third-party applications from the Adaptive Desktop
  2. Automation - driving the Adaptive Desktop from third-party applications

The following sections describe both sets of techniques.

Macros: driving third-party applications from the Adaptive Desktop

The most common use of macros in Adaptive software is for CTI screen-pops. A screen-pop consists of a trigger event and an AM macro.

Trigger Events

You can assign a "manually triggered" screen-pop to a button on the Adaptive Desktop macro toolbar, or to a menu command on the Adaptive Desktop Macros menu. You can also create fully automatic screen-pops, using any of the following trigger events (provided the product licence enables the corresponding functionality at the desktop):

  • Inbound email shownInbound email sent/fwd/nfaOutbound email shownOutbound email sentInbound telephone call ringingInbound telephone call answeredInbound telephone call finishedOutbound telephone call ringingOutbound telephone call answeredOutbound telephone call finishedTelephone call finishedOutbound SMS shownOutbound SMS sentWebAssist conversation openedWebAssist conversation closedCall-back shownCall-back scheduledCall-back rescheduledCall-back completedCall-back NFAedCall-back closedCampaign call presentedCampaign call diallingCampaign call ringingCampaign call answeredCampaign call wrap-up begunCampaign call rescheduled
  • Campaign call closed

AM macros

At their simplest, AM macros "type" characters into the Windows keyboard buffer. This allows a straightforward screen-pop to use keyboard commands to drive another Windows application, e.g. to open the "Find" dialogue and search for a contact by telephone number. However, AM macros also support other functionality. The Adaptive User Guide gives more information on the fundamentals of writing custom AM macros using the Adaptive Macro Editor, including how to run another executable from an AM macro.

Using an AM Macro to pass a parameter on the command line

The "Run Program" command, from the Insert menu in the Adaptive Macro Editor, inserts a comand into the body of an AM Macro which will run a program. For example, if you were to use this command to tell the macro to run Notepad.exe, your macro might look like this:

¬run(Notepad.exe)

If you run Notepad with a command line parameter, it will treat that parameter as a file name and try to open the specified text file. You can pass such a parameter from the macro, by changing the "run" command in the macro body so that the executable is followed by a comma and then the command line parameter or parameters. Using our previous example, to run Notepad and pass it the file name "readme.txt" as a parameter, change the macro body to look like this:

¬run(Notepad.exe,readme.txt)

Passing the CLI on the command line

As well as passing literals as parameters, you can pass Adaptive variables, such as the CLI of an inbound telephone call. The following example macro body would pass the CLI to Notepad:

¬run(Notepad.exe,¬field(Telephone Number))

Note also that if you run this macro when there is no current telephone call, then the value of the "Telephone Number" field will be blank. In this case, the command line parameter passed to Notepad will itself be blank, which is the same as not passing a parameter at all.Of course, if you were actually to use this example as a screen-pop macro, then when the screen-pop occurred, Notepad would simply display an error message box saying that it could not find the file. For a real screen-pop, rather than using Notepad, you would pass the CLI as a command line parameter to a program that can do something useful with it.

Using an AM macro to run a script file (VBScript)

All copies of Windows 2000, 2003 and XP ship as standard with Windows Scripting Host. This enables you to run scripts, specifically VBScript or JavaScript. AM macros can run such scripts just as easily as they can run other programs. Here is the body of an AM macro that would run a VBScript called myscript.bs located on the root of the C: drive.

¬run(C:\myscript.vbs)

You need to be careful, when writing an AM macro to run a script file, that you refer to a script file that is in the correct location for any PC that might run the macro. Remember that users may be hot-seated. If you assign your macro to a screen-pop, you need to be aware that the users in the screen-pop team may sit at different PCs, with different drives and paths.

Passing the CLI to a script file

The following AM macro body will run the a script file called myscript, located at the root of the C: drive, and pass it the CLI of the current inbound telephone call (if any):

¬run(C:\myscript.vbs, ¬field(Telephone Number))

You could use the VBScript to display the command line parameter it was pased in a message box. Here is an example script to do this:

Set objArgs = WScript.Arguments

	If objArgs.Count > 0 Then
		MsgBox "CLI = " & objArgs(0)
	Else
		MsgBox "No command-line parameter passed to script"
	End If

Example files showing this technique are available for download:

Copy both files to the macros sub-folder of your AM Data directory. Assign the AM Macro to a screen-pop event to see it working.

Passing multiple command line parameters

In an AM macro body "run" command, everything that follows the first comma is treated as the command line to pass to the executable. To pass more than one command line parameter, simply add the extra parameters directly after the first. For example, the following AM macro body would pass "-h -n -rs" to the command line:

¬run(myprog.exe, -h -n -rs)

Using scripts to make conditional screen-pops.

AM macros are unconditional. They do not have any "if-then-else" features. However, this does not mean that you cannot create conditional screen-pops using the Adaptive system. Adaptive Desktop screen-pops will run their AM macro whenever the trigger event occurs. This is fine if you always want the same thing to happen, but what if you want different things to happen based on the value of a field? One way is to give the user discretion, by assigning the screen-pop to a button on the Adaptive Desktop toolbar. However, sometimes you want the logic of your "what if?" to be performed automatically, by the macro. A good way to do this is using VBScript, which after all is a full programming language. This section presents some examples of how to use AM macros and scripts to create conditional screen-pops for your Adaptive software.

Conditional screen-pops: show a message box only for a specific DDI

Suppose you have a set of DDI numbers for customers to ring. You want a screen-pop that will display a message box to your users if an inbound call was to 08456124002 but not if it was to any of your other DDI numbers.To achieve this, first create a VBScript file (you can use any text editor, e.g. Notepad), call it ShowMessageForSpecialDDI.vbs and save it to the root of your C: drive. Write the contents of the file as follows:

Set objArgs = WScript.Arguments

	If objArgs.Count > 0 Then
		If objArgs(0) = "08456124002" Then
			MsgBox "The customer dialled the special DDI!"
		End If
	End If

Remember to change the number 08456124002 to a DDI that will work for your telephone system! Next, use the Adaptive Macro Editor to create a macro with the following body:

¬run(C:\ShowMessageForSpecialDDI.vbs, ¬field(Telephone DDI))

Assign the macro to the "Inbound telephone call ringing" screen-pop event for a team. Log into the Adaptive Desktop as a member of that team. When customers ring in, if they use the DDI you specified in your VBScript, then a message box will appear. If the customers use any other number, the box will not appear.

Conditional screen-pop: screen-pop external calls only

The following script and macro combination will run the standard Adaptive screen-pop macro for GoldMine, but only if the CLI was more than five digits long (i.e. was probably an external call call and not an intercom call).Save the following as GoldMineForExternalCallsOnly.vbs in the root of your C: drive:

Set objArgs = WScript.Arguments

	If objArgs.Count > 0 Then
		If Len( objArgs(0) ) > 5 Then
			Dim obj ' As Object
			Set obj = CreateObject("AMAgentAutomation.AMAutoAgent")
			obj.RunMacro "Screen-pop GoldMine.amm"
		End If
	End If

Use the Adaptive Macro Editor to create a new macro with a body that looks like this:

¬run(C:\GoldMineForExternalCallsOnly.vbs, ¬field(Telephone DDI))

Assign the new macro to your screen-pop event in the usual way and log into the Adaptive Desktop as a member of the team with the screen-pop. When a customer dials in, the screen-pop will find the record in GoldMine. When a colleague rings your extension, the screen-pop will not fire.

Example macros and VBScript files you can download

Downloadable example: conditional screen-pop on CLI length.

The following macro and VBScript pair will enable you to run any existing AM macro as a conditional screen-pop, firing only when the CLI of the call is more than five digits long:

Download the files and put them both in your macros folder. Use a text editor, e.g. Notepad, to edit the vbs file and change the line that looks like this:

strNameOfMacroToRun = "Screen-pop GoldMine.amm"

...so that the file name between the quote marks is the name of the AM Macro you want to run. For instance, if you want to use the Maximizer scren-pop macro, as shipped with Adaptive as standard, you would change it to look like this:

strNameOfMacroToRun = "Screen-pop Maximizer.amm"

Downloadable example: pass both CLI and DDI to VBScript

The following macro and VBScript pair show how to pass two command line parameters at once to a VBScript file:

Download the files and put them both in your macros folder. Assign the macro to an automatic screen-pop on inbound call ringing.

Automation: Driving the Adaptive Desktop from third-party applications

Third-party applications typically drive the Adaptive Desktop using Automation. This is achieved easily using VB (Visual Basic), VBA, or a scripting language such as VBScript or JavaScript.The following integration topics are discussed here:

  • Detecting whether or not a user is logged into the Adaptive DesktopTelephone call control from another application
  • Creating a new outbound email from another applicationCreating a new SMS from another application
  • Running an AM Macro from another application

Please note that for call control, messages and macro Automation methods, a user must be logged into the Adaptive Desktop. If no user is logged in, the methods will do nothing.

Summary of automation functions:

  • Dial Number as String
  • HangUp
  • CreateNewBlankOutboundEmail ToAddress as String, Subject as String, Body as String
  • CreateNewOutboundEmailFromFile FilePath as String
  • CreateNewOutboundEmailFromObject AMEmailMessage as Object
  • CreateAndSendNewOutboundEmailFromFile FilePath as String
  • CreateAndSendNewOutboundEmailFromObject AMEmailMessages as Object
  • CreateAndBulkSendNewEmail Addresses as String, AMEmailMessage as Object
  • CreateNewBlankSMSCreateNewSMS Number as String, Text as String
  • CreateAndSendNewSMS Number as String, Text as String
  • RunMacro MacroFileName as String
  • bool IsAgentDesktopRunning
  • bool IsAgentLoggedIn
  • bool IsEmailFunctionalityAvailability
  • bool IsSMSFunctionalityAvailability

Detecting whether or not a user is logged into the Adaptive Desktop

You need to be sure that a user is logged into the Adaptive Desktop before any of the call control, messaging and macro Automation methods will have any effect. The Automation interface includes methods to detect whether or not the Adaptive Desktop is running and a user is logged in.The following example VBScript will detect whether or not the Adaptive Desktop is running:

Dim obj As Object
Set obj = CreateObject("AMAgentAutomation.AMAutoAgent")
If obj.IsAgentDesktopRunning <> 0 Then
	MsgBox "Adaptive Desktop is running"
Else
	MsgBox "Adaptive Desktop is NOT running"
End If

The following example VBScript will detect whether or not a user is logged in:

Dim obj As Object
Set obj = CreateObject("AMAgentAutomation.AMAutoAgent")
If obj.IsAgentLoggedIn <> 0 Then
	MsgBox "a user is logged in - you can use the Automation interface"
Else
	MsgBox "No user is logged in"
End If

As you would expect, the IsAgentLoggedIn function also returns zero (false) if the Adaptive Desktop is not running, since a priori a user cannot be logged in. If you need to determine whether or not a specific type of functionality is currently available through the Automation interface, e.g. call control functionality, then you can use one of the following functions:

  • IsTelephoneFucntionalityAvailable
  • IsEmailFunctionalityAvailable
  • IsSMSFunctionalityAvailable

These functions all work in a similar way to the IsAgentLoggedIn function described above.

Telephone call control from another application

You can tell the Adaptive Desktop to dial a telephone number, just as though you had typed the number into the box and clicked the "Dial" button in the normal way. Similarly, the normal restrictions apply: you must be logged in, with a valid telephone extension, and the AM CTI Gateway must be running.The following example VBScript will dial 0870 870 4450:

Dim obj As Object
Set obj = CreateObject("AMAgentAutomation.AMAutoAgent")
obj.Dial "08708704450"

The following example VBScript will hang up the active call (if any):

Dim obj As Object
Set obj = CreateObject("AMAgentAutomation.AMAutoAgent")
obj.HangUp

Remember, the telephone call control Automation methods described here are exactly like typing the number into the Adaptive Desktop and clicking its "Dial" button, or clicking its "Hang Up" button. So, for instance, if you try to dial while the telephone is busy, or you try to hang up when there is no active call at that extension, then the Adaptive Desktop will report errors (or simply do nothing) in exactly the same way as it would if you tried the same thing manually.

From a technical standpoint, the Dial and HangUp commands are asynchronous and the AMAutoAgent object need not be persistent; your code can delete the object (or allow it to go out of scope) as soon as you have issued the command you wish to use. Because they are asynchronous and return immediately, the methods do not return error values if the commands cannot be carried out. So, for instance, calling Dial when the extension is already busy will not return an Automation error. However, the user Desktop will display a message asking the user to finish the current call first.

Creating a New Outbound Email From another Application

You can tell the Adaptive Desktop to create a new outbound email. The new message can be blank, or you can pre-populate part of it by passing appropriate parameters to the Automation call.Even though the email was created (and perhaps automatically sent) using the Automation interface, it will still appear to come from the user currently logged into the Adaptive Desktop. The email message will be logged in the Message Database and will appear in Message Database Browser search results in the usual way. You can:

  • Create an email for a user to review and send
  • Create an email and send it automatically
  • Create an email and "Bulk send" it automatically

Create an email for a user to review and send

Using the following code, the appropriate message viewer will appear and the user can edit, send or forward the message in the normal way.The following example VBScript will create a new, blank, outbound email:

Dim obj As Object
Set obj = CreateObject("AMAgentAutomation.AMAutoAgent")
obj.CreateNewBlankOutboundEmail

The following example VBScript will create a new outbound email addressed to sales@newmediaserver.com, with the subject "Hello World" and some example text in the body:

Dim obj As Object
Set obj = CreateObject("AMAgentAutomation.AMAutoAgent")
obj.CreateNewOutboundEmail "sales@newmediaserver.com", "Hello World", "Here is some example text"

To construct a more complicated outbound email, you can create an email message object, populate as much of it as you wish, then either tell the Adaptive Desktop to create a new outbound email based on the object, or save the object as a file and tell the Adaptive Desktop to create a new outbound email based on the contents of the file (optionally deleting the saved file at the same time):

Dim obj As Object
Set obj = CreateObject("AMAgentAutomation.AMAutoAgent")
Dim ame As Object
Set ame = CreateObject("AMEasyMailWrappers.AMEmailMessage")
ame.Recipients.Add "Phill", "pmcgowan@newmediaserver.com", 1
ame.Subject = "My test subject"
ame.BodyText = "This is my test email body" & vbCrLf & "with two lines"
ame.Attachments.Add "c:\pic1.jpg"

then either:

obj.CreateNewOutboundEmailFromObject ame

or:

ame.Save "c:\test.emx"
obj.CreateNewOutboundEmailFromFile "c:\test.emx"

Create an Email and Send it Automatically

The following example VBScript will create a new outbound email addressed to sales@newmediaserver.com, with the subject "Hello World" and some example text in the body; the email will be sent immediately:

Dim obj As Object
Set obj = CreateObject("AMAgentAutomation.AMAutoAgent")
obj.CreateAndSendNewOutboundEmail "sales@newmediaserver.com", "Hello World", "Here is some example text"

To send a more complicated outbound email, you can either create or construct a more complicated outbound email, you can create an email message object, populate as much of it as you wish, save it and then tell the Adaptive Desktop to create a new outbound email based on the values in the saved file:

Dim obj As Object
Set obj = CreateObject("AMAgentAutomation.AMAutoAgent")
Dim ame As Object
Set ame = CreateObject("AMEasyMailWrappers.AMEmailMessage")
ame.Recipients.Add "Phill", "pmcgowan@newmediaserver.com", 1
ame.Subject = "My test subject"
ame.BodyText = "This is my test email body" & vbCrLf & "with two lines"
ame.Attachments.Add "c:\pic1.jpg"

then either:

obj.CreateAndSendNewOutboundEmailFromObject ame

or:

ame.Save "c:\test.emx"
obj.CreateAndSendNewOutboundEmailFromFile "c:\test.emx"

Create an Email and "Bulk Send" it Automatically

The following example VBScript will create a new outbound email object, populate it with suitable values and then send it individually to each address in the string of addresses passed as a parameter. Note that the string of addresses must have each address separated from the next by vbCrLf (carriage return, line feed).

Dim ame As Object
Set ame = CreateObject("AMEasyMailWrappers.AMEmailMessage")
ame.Subject = "My bulk send test subject"
ame.BodyText = "This is my bulk test email body" & vbCrLf & "with two lines"
ame.Attachments.Add "c:\pic1.jpg"
Dim strAddresses As String
strAddresses = "first@abc.com" & vbCrLf;
strAddresses = strAddresses & "second@def.com" & vbCrLf;
strAddresses = strAddresses & "third@ghi.com" & vbCrLf;
obj.CreateAndBulkSendNewEmail strAddresses, ame

Creating a new SMS from Another Application

You can tell Adaptive Desktop to create a new SMS. The new message can be blank, or you can pre-populate part of it by passing appropriate parameters to the Automation call.Even though the SMS was created (and perhaps automatically sent) using the Automation interface, it will still appear to come from the user currently logged into the Adaptive Desktop. The message will be logged in the Message Database and will appear in Message Database Browser search results in the usual way. You can:

  • Create an SMS for a user to review and send
  • Create an SMS and send it automatically
  • Create an SMS email and "Bulk send" it automatically

Create an SMS for a user to review and send

Using the following code, the appropriate message viewer will appear and the user can edit or send the SMS in the normal way. The following example VBScript will create a new, blank, outbound SMS:

Dim obj As Object
Set obj = CreateObject("AMAgentAutomation.AMAutoAgent")
obj.CreateNewBlankSMS

The following example VBScript will create a new outbound SMS to a mobile phone number 07700123456 with "Hello how R U" as the text message:

Dim obj As Object
Set obj = CreateObject("AMAgentAutomation.AMAutoAgent")
obj.CreateNewSMS "07700123456", "Hello how R U"

Create an SMS and send it automatically

The following example VBScript will create a new outbound SMS to a mobile phone number 07700123456, with "Hello how R U" as the text message; the SMS will be sent immediately:

Dim obj As Object
Set obj = CreateObject("AMAgentAutomation.AMAutoAgent")
obj.CreateAndSendNewSMS "07700123456", "Hello how R U"

Create an SMS and "Bulk Send" it automatically

The following example VBScript will create a new outbound SMS and send the text "Hello how R U" to each mobile phone number in the string of numbers passed as a parameter. Note that the string of numbers must have each number separated from the next by vbCrLf (carriage return, line feed).

Dim obj As Object
Set obj = CreateObject("AMAgentAutomation.AMAutoAgent")
Dim strNumbers As String
strNumbers = "07700123456" & vbCrLf;
strNumbers = strNumbers & "07789654321" & vbCrLf;
strNumbers = strNumbers & "07970888333" & vbCrLf;
obj.CreateAndBulkSendNewSMS strNumbers, "Hello how R U"

Running an AM Macro from Another Application

You can tell the Adaptive Desktop to run a named macro. You pass the name of the macro file (which must be in the Macros subdirectory of the main AM Data directory) and the Adaptive Desktop runs the macro exactly as though the user had clicked a macro button with that macro assigned to it.The following example VBScript will run a macro saved to a file called mymacro.amm:

Dim obj As Object
Set obj = CreateObject("AMAgentAutomation.AMAutoAgent")
obj.RunMacro "mymacro"