Contents 2 Table of Contents Foreword Part I Overview Part II 0 3 4... 1 Dow nload and prepare 4... 2 Enable the ex ternal ID column on ISL Conference Prox y 4... 3 Deploy w eb content 5... 4 Add items to Developer Studio 11... 5 Change Forms 13... 6 Add Filters 31... 7 Add Active Links 34... 8 Finish and Test 42 Part III ConnectBox Example 43... 1 ConnectBox 43 Part IV Zendesk Integration 46... 1 Creating App Files and Testing 46... 2 Ex ample App 48... 3 Ex ample App Code 50... 4 Uploading Your App to Your Zendesk 52 Part V Web API Index 54 0 2
1 Overview 3 Overview This document is intended for developers who want to integrate ISL Online solutions into other applications.
2 4 This section describes a sample integration of ISL Light and. 2.1 Download and prepare First step in integration process is to download required files needed for integration of ISL Online products into system. The newest package is available on ISL Online website: http://www.islonline.com/ integration/bmc But if you want the list of all version of available packages, please visit http:// www.islonline.com/integration/bmc/index.htm Save the desired zip file to the desired folder (ie. C:\BMC). Extract the file. There are two folders: web - this folder hold all the files that needs to be deployed on any web server for integration to work, remedy - files needed for Developer Studio. When you are ready, continue to next step of integration. 2.2 Enable the external ID column on ISL Conference Proxy You should create a file called dbopt i ons in your ISL Conference Proxy installation directory with the following content: l i ght _ex t er nal _i d=1 i s l pr ont o_ex t er nal _i d=1 Once you save this file you need to restart ISL Conference Proxy to apply it. When the server comes back up you will see an additional column called "External ID" in the ISL Light and ISL Pronto session history. This column is indexed so it is possible to
5 perform webapi2 queries on it. Our ISL Light integration example will use this field to store the appropriate BMC ticket id. You are now ready to proceed to the next step of integration. 2.3 Deploy web content The files that we extracted in first step and are now located in C:\BMC\web must be deployed on a web server. This server must be visible to any user. If you run Remedy on local network, local web server can be used, but if Remedy is used over internet, public web server is required. The easiest way is to use BMC AR's Tomcat web server. Any kind of web server can be used, since files that needs to be served for ISL Online integration to work correctly are plain HTML and JavaScripts. Let's look at the example of how to integrate on Windows 2003 system: Log on to server Copy files from C:\BMC\web to C:\Inetpub\isl for instance. We will use this folder as a root to new virtual directory Open Internet Information Services Manager. More on how to open it: http:// msdn.microsoft.com/en-us/library/bb763170(v=vs.100).aspx Go to the Web Sites section Right click on Default Web Site, then New and select Virtual Directory...
6 In the wizard click Next
7 Enter virtual directory name (isl) in the box and click Next
8 Click Browse... and select C:\Inetpub\isl as destination folder Click Next
9 Click Finish to complete the wizard
10 Your IIS Manager should look much like this: Open any browser and navigate newly deployed virtual directory (we will use bmc.example.com as our website address): http://bmc.example.com/isl/ sessions.html The result should look like this:
11 If you have problems viewing the page, you can try http://localhost/isl/sessions.html If problem persists, there is something wrong with your IIS instalation or you should check your firewall settings. When you are ready, continue to next step of integration. 2.4 Add items to Developer Studio First we need to ingest all required external objects into Developer Studio. Images To add images: Run the developer studio and log in Expand server and All Objects Right click on Images and click on New Image
12 In Description write ISL Online Logo Click Browse... and select C:\bmc\remedy\ISL Online Logo.png Your view should look like this: When you are ready, continue to next step of integration.
2.5 13 Change Forms We will change default installation of. We will change main Help Desk form, but this instructions can be applied to any existing form. In developer studio expand server, All Objects and double click on Forms In the right panel form list should appear Expand Filtering options and write HPD:Help in the filtering text box as shown in the image below Double click HPD:Help Desk form in the list to open the form In the tabbed section right click on one of the tabs and select Add New Panel
14 Configure the panel's properties
15 In Database section change name to ISL Light In Display section, set Label to ISL Remote Support Drag Character field from Data Fields section to add the field to Panel
16 Configure the field's properties
17
18 In Database section change name to CPAddress In Display section, set Label to CP Address, X to 5, Y to 5, Width to 260, Visible to False Set Permissions to Public Drag Character field from Data Fields section to add the field to Panel Configure the field's properties
19
20 In Database section change name to sessionusername In Display section, set Label to ISL Username, X to 5, Y to 30, Width to 260, Visible to False Set Permissions to Public Drag Character field from Data Fields section to add the field to Panel Configure the field's properties
21
22 In Database section change name to sessionpassword In Display section, set Label to ISL Password, X to 5, Y to 55, Width to 260, Visible to False Set Permissions to Public Drag Character field from Data Fields section to add the field to Panel Configure the field's properties
23
24 In Database section change name to ticketid In Display section, set Label to Ticket ID, X to 5, Y to 80, Width to 260, Visible to False Set Permissions to Public Drag Character field from Data Fields section to add the field to Panel Configure the field's properties
25
26 In Database section change name to WebAddress In Display section, set Label to Web Address, X to 5, Y to 105, Width to 260, Visible to False Set Permissions to Public Drag Button field from Display Fields section to add the field to Panel Configure the field's properties
27 In Database section change name to sessionsrefresh In Display section, set Button Label to Refresh ISL Remote Sessions, X to 8, Y to 360 Set Permissions to Public Drag Button field from Display Fields section to add the field to Panel Configure the field's properties
28 In Database section change name to startisllight In Display section, set Button Label to Start ISL Remote Support, X to 174, Y to 360 Set Permissions to Public Drag View field from Display Fields section to add the field to Panel
29 Configure the field's properties In Database section change name to sessionsview In Display section, set Label to View Sessions, X to 0, Y to 0, Width to 640, Height to 350 Set Permissions to Public Drag Panel field from Composite Fields section to add the field to Panel
30 Configure the field's properties In Database section change name to ISLLogo In Display section, set Label to ISL Online logo, X to 640, Y to 0, Width to 235, Height to 78 In Image section set Background Image to ISL:Logo Set Permissions to Public
31 When you are ready, continue to next step of integration. 2.6 Add Filters For our new Form elements to work properly, we need to add Filter elements. If you changed any other Forms besides HPD:Help Desk, you will need to adapt filter values. Let's create Filter In developer studio expand server, All Objects, right click on Filters and choose New Filter Expand Associated Forms and add HPD:Help Desk form by pressing Add... button
32 Expand Execution Options and check Get Entry checkbox Right click on If Actions, select Add Action and Set Fields
33 Data Source should be set to CURRENT TRANSACTION Add field WebAddress and set value to "http://bmc.example.com/isl" - this is the address where we deployed Add field CPAddress and set value to "http://isl.example.com:7615" - this is the address of Conference Proxy Add field sessionusername and set value to "bmcsupport" - this is the user name that will be used for logging into Conference Proxy Add field sessionpassword and set value to "bmcsupport" - this is the password that will be used for logging into Conference Proxy Add field ticketid and set value to $Incident Number$ - Incident ID needs to be sent to Conference Proxy for reference Save the Filter and name it ISL:HPD:Help Desk Init Your FIlter should look like this:
34 When you are ready, continue to next step of integration. 2.7 Add Active Links Integration requires creation of several Active Links. If you changed any other Forms besides HPD:Help Desk, you will need to adapt Active Links' values. Let's create Active Links
35 In developer studio expand server, All Objects, right click on Active Links and choose New Active Link Expand Associated Forms and add HPD:Help Desk form by pressing Add... button
36 Expand Execution Options and check Gain Focus checkbox In the Field textbox enter ISL Light Right click on If Actions, select Add Action and Set Fields
37 Data Source should be set to CURRENT TRANSACTION Add field sessionview and set value to ((((((($WebAddress$ + "/sessions.html?tid=") + $ticketid$) + "&u=") + $sessionusername$) + "&p=") + $sessionpassword$) + "&a=") + $CPAddress$ - this will execute web call to early deployed files when user clicks on ISL Remote Support tab Save the Active Link and name it ISL:HPD:Help Desk OnInit ISL Light tab Your Active Link should look like this:
38
39 Right click on Active Links again and choose New Active Link Expand Associated Forms and add HPD:Help Desk form by pressing Add... button Expand Execution Options and enter sessionsrefresh to Button/Menu field Right click on If Actions, select Add Action and Run Process In Command Line enter JAVASCRIPT MyBroker.SendEventToField("$ticketID$", "$sessionusername$", "$sessionpassword$", "$CPAddress$"); - this will do exactly the same as Active Link above, but this will manually cause refresh of session list Save the Active Link and name it ISL:HPD:Help Desk Refresh Session List Your Active Link should look like this:
40 Right click on Active Links again and choose New Active Link Expand Associated Forms and add HPD:Help Desk form by pressing Add... button Expand Execution Options and enter startisllight to Button/Menu field Right click on If Actions, select Add Action and Run Process In Command Line enter PERFORM-ACTION-OPEN-URL new "$CPAddress$/start/
41 ISLLightDesk?cmdline=--get-code+--username+$sessionUsername$+--password +$sessionpassword$+--proxy-notification+external_id=$ticketid$+--sessionmessage+%22user=$user$%22" - this command will start ISL Light Desk with autologin. No username and password will be required. Save the Active Link and name it ISL:HPD:Help Desk Start ISL Light Your Active Link should look like this:
42 When you are ready, continue to next step of integration. 2.8 Finish and Test You have successfully integrated ISL Online products into system. Log into Mid Tier Configuration Tool, click on Cache Settings and press Flush Cache button. This might take a while, depending on your system. If you do this on production server, be sure, that it will not interfere with work process. Visit http://bmc.example.com/arsys/ and login If you did all steps correctly, your screen in browser should look much like this:
3 ConnectBox Example 43 ConnectBox Example Here is described how to include ConnectBox HTML in your website. 3.1 ConnectBox To include ConnectBox in your web page will require to have a ConnectBox HTML code. The code is available on the following page: http://www.islonline.com/remotesupport/customization-and-integration.htm#connect-box Select and copy the above code and then paste it to the desired location in your web page. If you open now your page in browser, you will see a ConnectBox in. To start a new ISL Light session just enter the session code in a box and press connect button bellow.
ConnectBox Example 44 You will get ISL Light client application from the web page as executable. Which means, from now on a remote support can be initiated and supporter is going to have access on client desktop.
ConnectBox Example 45 This concludes ConnectBox integration, you have successfully integrated ConnectBox in your web page. More information regarding the other options, you can find on the following page: http://www.islonline.com/help/isl-light/3-5/manual/?i-advanced-webpage-integration.htm.
4 Zendesk Integration 46 Zendesk Integration This section provides an example of how to integrate ISL Online with Zendesk 4.1 Creating App Files and Testing To begin setting up integration with Zendesk, follow Zendesk's steps to install the developer tools: Installing the Zendesk app tools Once the Zendesk tools are installed, you can either begin from scratch and create the app files. Creating the app files Or install these files which provide a basic work flow for ISL Online Zendesk integration. zendesk.zip Once the files are installed, the app is working. In order to test the app you have currently, or to test throughout your development, you do not need to upload the app each time. Instead, open up you command-line interface (with Ruby on Windows), and navigate to the location of the app files. Then type the command: "zat server".
Zendesk Integration 47 Keep your command line interface open until you are finished Now go to your zendesk, navigate to any ticket, the URL will look like this: "https:// subdomain.zendesk.com/agent/tickets/123" Add "?zat=true" to the end of the url to make: "https://subdomain.zendesk.com/agent/ tickets/123?zat=true" Your browser may now block your app due to an 'unsafe script'. If you are using Chrome or Firefox, click the shield icon in the address bar and press "Load Unsafe Script". Now you should see the app. This is what the default app looks like:
4.2 Zendesk Integration 48 Example App The example app has a basic workflow which can be styled to your requirements by using the app.css file. Here is a demonstration of the app's functionality. The user is presented with a Login page on startup This sends a Login request to the ISL Online Web API, and returns a session id.
Zendesk Integration 49 Once logged into your ISL Online account, a JSON request is sent to start an ISL Light Session which returns a link to download the ISL Light Desk application. The user is then shown the start session page which provides this link: Once this is clicked, the browser will download the ISL Light Desk application. This will then be opened, and will immediately create a code for a session: Now the user is presented with the insert code form, when the button is clicked, a JSON request is sent to resolve the session, so that the application can use the database ID. Once the database ID is acquired, a JSON request is sent to get the Session Info. This will return the code for the session, and a link to connect straight away. This link is used when the user presses the button and is input into the form. The user can then send this to their client. When the client opens the application the Remote Support session begins.
4.3 Zendesk Integration 50 Example App Code The example app has a basic work flow to show how ISL Online's Web API works with Zendesk. The app.js file in the example app is well commented and should be easy enough to follow, however this document will show the basics of Zendesk requesting, so that ISL Online's Web API can work with Zendesk.
Zendesk Integration 51 Here are the requests used in the example app.js file. These should show the structure required in order to successfully work with ISL Online's API. Zendesk also has some useful documentation on their website about requests: https:// developer.zendesk.com/apps/docs/agent/requests In order to process the results of a request, use the "events". Here is an example of processing a request's results:
Zendesk Integration 52 Zendesk documentation explains how to use events: https://developer.zendesk.com/ apps/docs/agent/events In this event, the function is called when 'LoginRequest' is done. LoginRequest is the JSON Function that logs into the ISL Online account. The function defines one parameter 'data'. This automatically stores the result of the JSON Request in an object. The function accesses the session id (sid) by using the result object. 4.4 Uploading Your App to Your Zendesk Zendesk have an article on how to upload your private app to your Zendesk here: https://support.zendesk.com/hc/en-us/articles/203691246-uploading-and-installing-yourprivate-app-in-zendesk It is very simple, Firstly, create a Zip file of all your app files. Go to your Zendesk, click on the "Admin" icon in the sidebar, and click Apps -> Manage. Then click "Upload App"
Zendesk Integration 53 Enter the name of your app Click "Choose File" and select the Then click save, and agree to upload the app. You will be prompted to install. Once the process has completed, the app will be visible in the "Manage Apps" page on your Zendesk. Now you are ready to use it in a ticket, click the Apps button in the top right hand corner and find the app to use it.
5 Web API 54 Web API User API communicates via HTTP (both POST and GET) protocol and provides many ways of communication JSON(P) and XML. Apart from general communication fields, that must be sent via POST/GET, all other data can be sent in any way. We strongly encourage the use of POST over GET method for sending data (except in the case of JSONP). All data sent via POST or GET should be URL encoded! All APIs are available at /webapi2 url. APIs can be tested at : https://www.islonline.net/users/main/test_webapi2.html For server license users use this link: http://[server_address]/users/main/test_webapi2.html - replace [server_address] with your server. Additional info regarding the available API calls is also available on this page. For information on the communication model for Web API see this section within the API documentation: http://www.islonline.com/help/isl-api/any/manual/?communication_model.htm This manual topic gives information regarding the methods. Methods are listed for account procedures and examples are given to show parameters for each call, and return values. http://www.islonline.com/help/isl-api/any/manual/?methods.htm