Gary Sherman's blog

Dovetail Mobile on tablets

gsherman — Tue, 17 Jan 2012 20:04:39 +0000

The question has come up a few times: can I use Dovetail on a tablet? Well, Dovetail Mobile supports mobile devices, and a tablet is a mobile device, so it should work, right? Yes, indeed it does. Our Dovetail Mobile app works great on tablets.

And for and for those Clarify customers who want to access their Clarify system via smartphones and tablets, Dovetail Mobile is a great choice for this. We’ve certainly seen more and more organizations allowing employees to use their own devices, so having apps that are compatible with a user’s device is important. Web apps are a great choice for this.

I’ve captured a few screenshots using a few different devices (iPad, Kindle Fire, and a Motorola Xoom), so you can see that Dovetail is compatible with a variety of tablets.

iPad

Kindle Fire

Unfortunately, the Fire doesn’t have a built-in screenshot app, so I fell back to taking a pic of the whole tablet itself.

Motorola Xoom (Android)

Again, this Android doesn’t have a built-in screenshot app. Sorry.

FAQ

What tablets will it work on?

If it’s got a web browser on it, it’ll work. That’s one of the advantages of Dovetail Mobile being a web app as opposed to a native app.

Which view mode is recommended?

As I showed in a previous post, Dovetail Mobile has three view modes:

Classic Mobile, Modern Mobile, and Desktop.

Desktop: for laptops and desktops. Sometimes referred to as Dovetail Agent Lite.
Modern Mobile: For modern mobile devices like iPhone and Android
Classic Mobile: Minimalist version for older smart phones

Since today’s tablets are all pretty “modern”, the Modern Mobile mode looks great (which is the mode shown in all of the screenshots above).

But, if you prefer the Desktop or Classic Mobile mode – go for it. They all work. Your preference.

What version of Clarify will this work with?

Dovetail Mobile will work with any version of Clarify, from Clarify 7 –> Clarify 12, Amdocs 6 and 7.

Do I have to upgrade my Clarify version to use Dovetail Mobile?

No. It works with the version of Clarify you have. So even if you’re on an older version of Clarify, you can still add mobile access to your system.

Can I try it out on my device?

Sure. Just drop me an email, and I’ll give you access to a demo site that you can use.

What about you?

In case you can’t tell, I really dig this app. When I’m at work, I use Dovetail Mobile on my laptop (in Desktop mode). When I’m at home, I use it on my iPad (in Modern Mobile mode). And when I’m, uh, mobile, I use it on my iPhone (in Modern Mobile mode).

Are you using tablets? At home? At work? Is your organization using tablets? What would make this more useful to you or your organization? I’d love to hear what you have to say. Leave a comment below.

Rock on.

What’s new in Dovetail Mobile / Dovetail Agent Lite version 2.1

gsherman — Fri, 13 Jan 2012 16:59:16 +0000

Dovetail Mobile 2.1 was recently released, so I wanted to to highlight a few of the things that are new in this release.

BTW – did you know you can subscribe to our Dovetail product release RSS feed? This allows you to stay up to date about new releases.

Unified Mobile and Agent Lite

Dovetail Mobile now provides users with 3 view modes: Classic Mobile, Modern Mobile, and Desktop.

Desktop: for laptops and desktops. Sometimes referred to as Dovetail Agent Lite.
Modern Mobile: For modern mobile devices like iPhone and Android
Classic Mobile: Minimalist version for older smart phones

In previous versions, you would pick either Desktop mode or Mobile mode when setting up the application. If you wanted to run Mobile and Agent Lite (Desktop mode) you would need two instances of the application.

Now, all those modes are available in a single instance of the application.

Depending on the type of device/browser you’re using to access the application, you will be automagically presented with the view mode that is most appropriate for you.

So if Sally logs in with her iPhone, and Fred logs in with IE on his laptop, and Marty logs in with his older BlackBerry – they’ll all access the same application, but have a user interface that is styled appropriately for their device.

The core functionality is the same across all three – it’s just the styling that’s different.

Lets look at some examples of how the different view modes look.

Home Page

This is the same home page for the application, just with different styling.

Desktop:

Modern Mobile:

Classic Mobile:

Case Page

Here’s an example of the case page in each mode.

Desktop:

Modern Mobile:

Classic Mobile:

Switch View Mode

You can also switch to a specific mode. At the bottom of both the login and home pages is a link to Switch. It will take you to a Select your view mode page:

Attachments

Attachments can now be uploaded and downloaded.

This works just as you would expect on a laptop or desktop.

On mobile devices, file uploads are dependent on the capabilities of the device. For example, on an iPhone, you can’t upload a file, as there really isn’t a file system to pick a file from.

My Recent Items

The Home page now has a link to My Recent Items

These are items that you recently viewed. Doesn't matter who owns them, or if they're opened or closed. This is useful for quickly getting back to an item that you recently viewed. For example, Fred may look at a case that Sally owns, and may need to quickly get back to it in the near future.

Employee Lookup on Assign Page

When assigning a case or subcase, we’ve expanded the employee search to be two separate fields: first name and last name.

Previously, there was just one field, which would search for either first name or last name.

The recent change has made it clearer for users.

Allow solutions to be linked to closed cases

I’ve discussed this workflow and need in a previous post.

Here you can see the new capability:

Summary

That highlights just some of the recent capabilities we’ve added to Dovetail Mobile.

This application has become the primary Dovetail application that we use around here when working on support cases. Having mobile access is great (everyone here has a contemporary smartphone), and the quickness and ease-of-use of the desktop mode make it our preferred app. We still do use Dovetail Agent for more complex tasks (configuring site parts, creating contracts, etc.). Between the functionality that we want to add to the app, coupled with customer requests, the future of this app looks bright.

What’s New in Dovetail Agent 4.5 : Part 3

gsherman — Thu, 12 Jan 2012 20:06:08 +0000

We’re continuing on with highlighting some of what’s New in Dovetail Agent 4.5. Part 1. Part 2.

Multiple phone numbers and email addresses for contacts

I’ve posted in the past about multiple email addresses for a contact, and how we have existing schema for this within Clarify, but we needed the UI to support this.

Dovetail Agent now provides this UI.

Contacts can now have unlimited phone numbers and email addresses. There is a new Phone/Email tab used to manage the phone numbers and email addresses for a contact.

In addition, all of the additions/changes/deletes of these email and phone numbers are tracked in the activity log:

Link Solutions to Closed Cases

A common workflow we see here is:

1. A case is opened for a customer
2. We work with the customer to figure out a resolution to the issue
3. Customer uses SelfService to indicate that the resolution solved the issue, and the customer closes the case (and you know how much I love when a customer closes their own case)

Now that we know that the resolution we provided did indeed solve the problem, we can create a solution, so this knowledge can be reused, should the same issue arise in the future.

4. Create a new solution

So we’ve created a solution, but we can’t link the solution to the case because the case is closed.

So, we:

5. Reopen the case
6. Link the case to the solution
7. Close the case again

In general, once a case is closed, there shouldn’t be any more changes made to it.

But, it seems kind of silly to have to reopen a case, just to link it, so then you can just close it again.

Now you can link a solution to a closed case.

The solution form looks the same – the Link this Solution to a Case button is still there:

which opens a lightbox with the list of your open cases.

We’ve added a new checkbox, which allows you to include my recently closed cases:

clicking that checkbox now includes your recently closed (but not yet linked) cases:

and there’s an icon there as well that indicates that it’s a closed case:

So now you can link a solution to one (or more) of your closed cases.

64-bit Support

Dovetail Agent can now be run in 64-bit mode.

Note that this requires the 64-bit version of Dovetail SDK (version 3.0 or higher).

For more info, refer to a previous post: SDK based web apps in a 64-bit environment

A Better Attachment Upload Component

We’ve updated the component that we use for uploading of file attachments. It supports both 32 and 64 bit systems. This is also a more actively developed component, and it includes better memory management than the previous component.

Summary

OK, so that’s a wrap on the Dovetail Agent 4.5 changes that I wanted to cover. There’s also a bunch of minor changes and bug fixes that have been completed, but nothing exciting enough that I want to cover here. More details are in the Dovetail Agent documentation.

If you need more info, or would like a demonstration of any of these features (or heck, of any of out stuff), feel free to contact me.

What’s New in Dovetail Agent 4.5 : Part 2 : Search and Query

gsherman — Thu, 12 Jan 2012 18:29:54 +0000

We’re continuing on with what’s New in Dovetail Agent 4.5. Part 1 is available here.

Simplified Search Tips

We’ve simplified the Search Tips page, making it easier for users to understand all of the robust searching capabilities that are available.

Simplified Date Searching

We’ve simplified searching using a date/time property.

The baseline date/time range search can be a little cumbersome.

For example, to search for items created in December of 2011: created:[20110101 TO 20111231]

That syntax is still available for use, but we’ve expanded data/time searching for some common scenarios.

Search for items created today: created:today

Search for items created in the last 30 days: created:30days

And that number (30) can be any number: created:7days, created:365days, etc.

And, of course, you can combine this with other properties and keywords, and even save it as a favorite.

Here’s my search for all Franchise Support cases created in the last 30 days:

Distinct Queries

We’ve added the ability for Distinct Queries in the Query module.

This is probably best explained with an example.

Lets say I want to show all of the cases touched today by a particular user.

Without a distinct query, it’s possible that I would see the same case in the report multiple time. For example, if the same user logged multiple notes to the same case on the same day. Or if they did multiple workflow operations, which is also common.

This could result in a query output such as this:

Notice that in the above query results, the same case is repeated.

Annie really didn’t touch 7 cases. She really only touched 3 distinct cases.

By making the query distinct, we get the desired results:

And the way we make a query distinct is by checking the Only show distinct rows checkbox when creating/editing the query:

Summary

That highlights some of the search and query improvements. There’s still a few more improvements and features I want to highlight, so Part 3 will be coming soon.

What’s New in Dovetail Agent 4.5 : Part 1 : Console

gsherman — Thu, 12 Jan 2012 17:54:27 +0000

Dovetail Agent 4.5 was recently released, so I figured it was a good time to highlight a few of the things that are new in this release.

BTW – did you know you can subscribe to our Dovetail product release RSS feed – so you’ll always know about new releases?

Console Improvements

We’ve improved the user interaction quite a bit in the main console pages.

Right-click operations replaced by Actions button.

Previously, you could right-click on an item in the console to perform workflow and log operations. This is how it used to look:

Right-clicking in web-apps is not really expected. So we’ve replaced it with a more common and expected Actions button located at the top of the page.

If there’s only one item selected, the menu will show all of the actions available for that item type:

If there are multiple items selected. the menu will show common items that can be applied across those items in a “batch” operation:

Row Coloring, Clicking

In previous versions, a row would be color highlighted when the mouse was hovered over it. This caused confusion, especially when multiple items were selected.

In addition, we used to click a row (and color it) when an item was opened, or when it was clicked in any of its cells.

To open it, you had to click the ID number cell, or double-click elsewhere on the row.

All of this led to a lot of confusion, so we’ve simplified this.

A row will only be colored if it’s row’s checkbox been explicitly checked. A single-click anywhere else on the row will open the item. Much simpler.

To be honest, we borrowed a lot of this from Google’s Gmail interface, as we’re frequent users of that product, and like how that interaction works.

Drag Handle

You can still drag and drop items around (such as dragging a case into a WIPbin to move it, or dragging it into a queue to dispatch it), and we’ve made the drag handle (where you put your mouse to “grab” the item and start dragging from) clearer.

Item Counts, Show More, Show All

Whenever a user has a WIPbin or Queue selected, the console will show the total number of items, and allow you to click to Show More or Show All:

Profile / Settings

Previously, opening the user’s Profile page posted a small tabbed form in a new window.

Now, the user settings are shown on the same console page.

We’ve also simplified many of the elements on this settings page to make it easier to use.

We’ve also added a Settings icon at the top of the page to make it easy to get to, and make it more consistent with other common web apps.

User Configurable Console Columns

We’ve given the ability for users to configure the columns that show up in the console (for WIPBINs and queues).

Users can reorder columns, hide columns, and change the column headings. These are individual user settings, so each user can tailor this to their own liking.

Customizing the Console

From an administrative / development standpoint, we’ve simplified the task of customizing the console columns.

The default objects are case, subcase, solution, bugs, action items, and part requests. If other objects are added to the console pages, then columns from those objects can be added as well.

As a quick example, to add the item’s type (case type, bug type, etc.), I just need to modify one line of code:

addColumn("type", "Type", true, "Item's type (case type, bug type, etc.)");

Then that column will show up as an available column in the user’s settings and on the console:

Notice that if a particular object doesn’t have that column available in the schema, it will just show as blank (as we see here for the Solution’s Type).

More details on this are available in the Dovetail Agent Documentation.

Summary

OK, so that highlights some of the improvements made around the console. This post is starting to get a bit long, so I’ll highlight other new features in subsequent posts.

Automated Deployment for Clarify Example

gsherman — Wed, 11 Jan 2012 21:28:52 +0000

Last year I posted about automated deployments for Clarify. From that post:

Doing automatic deployments of Clarify changes is pretty straightforward. If I was starting off, I would use a contemporary build script tool such as nant or rake, and simply have it call out to your schema editing tool (Dovetail SchemaEditor, or ddcomp) to perform schema changes, use an import tool (such as Dovetail ArchiveManager, or dataex) for importing forms, and then compile your Clearbasic code using CBEX, or just import it as a DAT file using Dovetail ArchiveManager. File copying, registering components, configuring web servers, and setting permissions are all common tasks that are available in these build tools as well.

Should you also need to do additional stuff in your database, some code that uses the Dovetail SDK can be useful.

You could tie this in with a CI server if you wish, so when new code is checked in, the CI server could automatically push it to a test database.

Recently, I got a Please Send Me The Codez email, so I’ve shared an example of doing this.

Code

The code is freely available on GitHub: https://github.com/gsherman/Clarify-Deployment

Tools

In this example, I’m using the following tools:

Tool	Description	Alternatives
NAnt	Free Build Tool for .NET. Overall automation scripting tool	rake, psake, ant
Dovetail SchemaEditor	Extends the Clarify Schema	ddcomp, SchemaManager
Clarify CBEX Toolkit	ClearBasic Code “Compiler”
Dovetail Archive Manager (DIET)	DAT file importer	dataex
Powershell	Shell and scripting language for .NET
Dovetail SDK	APIs for Clarify

You’ll notice I didn’t upload all of my tools under the tools directory into GitHub. This is intentional. NAnt is free, so you can download this yourself. If you want to use the Dovetail tools, you’ll need to have a license to use them. CBEX is from Clarify/Amdocs.

Notice that I’ve also provided alternative tools to use, should you so desire.

NAnt Script

Everything starts with the NAnt script: dev.query.build

The NAnt script contains targets (sort of like functions). I’m using two main targets:

Target	Description
reset-dev-database	Reset my local development database
setup-dev	Does all the real work

Setup-Dev Target

The setup-dev target basically calls the following other targets:

Target	Description	Tools Used
dev-properties	defines the properties for my development environment
apply-schema-scripts	apply all of the schema files in the /schema directory	Dovetail SchemaEditor
setup-database-stored-procs	apply the stored procedures necessary for Dovetail SDK	sqlcmd.exe (Microsoft SQL Server Command Line Tool)
add-licenses	add Dovetail licenses to the database	NAnt built-in SQL task
import-dat-files	import all of the DAT files in the /files directory	Dovetail Archive Manager (DIET)
import-forms	import all of the forms (DAT files) in the /files directory	Dovetail Archive Manager (DIET)
setup-resource-config	add the forms to the proper resource configuration. add the current user into the proper resource configuration.	PowerShell and Dovetail SDK
compile-clearbasic-code	compile all of the ClearBasic code	Clarify CBEX Toolkit
clear-clarify-cache	clear my Clarify cache files	NAnt built-in delete file task

Execute the Script

To execute it, I simply type nant plus the target that I want to execute from a command line.

For example, to reset my database back to a good state (useful in development):

DOS> nant reset-dev-database

This is useful because I can screw stuff up as often as I want in development, and simply revert my database easily and quickly to put me back to a known good state. Then continue on developing and testing.

I then use the setup-dev task which does everything (schema, database setup, dat files, forms, resource config setup, CB code, etc.):

DOS> nant setup-dev

If needed, I can run just one target by itself, such as :

DOS> nant apply-schema-scripts

What about deploying to QA or Production?

You could add a qa-properties or prod-properties target, which define the properties for those environments.

Then, add a target such as deploy-to-qa or deploy-to-prod, such as :

Giddy-Up

Obviously, what I’ve done and how I’ve done it may not exactly fit into your environment or toolset. That’s OK. I think it’s the concept here that’s more important than the specific example.

Fortunately, the build tools, CI servers, and scripting environments are widely used. This means that there are tons of examples and tutorials available online to help you accomplish your tasks.

I think you’ll find that once you start using automated scripts, you’ll never want to manually repeat steps again.

Hope you find this helpful.

Rock on.

Notifying the Yankee (part 2) This time with the Clarify Client

gsherman — Wed, 21 Dec 2011 22:56:26 +0000

Recently I posted about how to notify the yankee, meaning the person who a case was yanked from.

I showed how to make this happen within applications that use the Dovetail SDK (Dovetail Agent, Dovetail Mobile, etc.)

Now, lets see how we can accomplish the same task within the Clarify Classic Client.

Setup

Most of the setup is the same as I covered previously.

1. Turn the participant2user pseudo-relation into an exclusive relation

2. Setup a business rule recipient alias for the “Yanked From User”

3. Create a business rule that uses the “Yanked from User” as a recipient of a rule

4. Add the participant record

Add a Participant using ClearBasic

To add a participant record, we can add some ClearBasic code behind form 737, which is the Yank form.

Caution: this is an old-school C form, so much of the prescribed way of using CB code on this form doesn’t work. Especially around the Form_Save routines.

Here’s what I came up with:

OPTION EXPLICIT

Dim actEntryObjid As Long

Function GetCurrentOwnerObjid() As Long

 Dim previousOwnerObjid As Long

 Dim lor As List

 Dim rec As Record

 Dim br As New BulkRetrieve

 Dim objectType As String

 Dim ownerRelation As String

 GetCurrentOwnerObjid = 0

 Select Case YANK_OBJ_TYPE.Text

 Case "Case"

   objectType = "case"

   ownerRelation = "case_owner2user"

 Case "Subcase"

   objectType = "subcase"

   ownerRelation = "subc_owner2user"

 End Select

 If Len(objectType) > 0 Then

   br.SimpleQuery 0, objectType

   br.AppendFilter 0, "id_number", cbEqual, EDT_5.Text

   br.TraverseFromParent 1, ownerRelation, 0

   br.RetrieveRecords

   Set lor = br.GetRecordList(1)

   If lor.Count > 0 Then

     Set rec = lor.ItemByIndex(0)

     previousOwnerObjid = rec.GetField("objid")

   End If

 End If

 GetCurrentOwnerObjid =  previousOwnerObjid

End Function

Sub Form_Load()

    Me.DoDefault

End Sub

Sub Form_Save2(bs As BulkSave)

 Dim recActEntry As Record

 If bs.CountByType("act_entry") > 0 Then

    Set recActEntry = bs.GetRecordByIndex(0,"act_entry")

    actEntryObjid = recActEntry.GetField("objid")

 End If

End Sub

Sub SaveParticipant(previousOwnerObjid As Long)

 Dim recP As New Record

 Dim bs As New BulkSave

 If actEntryObjid > 0 And previousOwnerObjid > 0 Then

    recP.RecordType = "participant"

    recP.SetField "role_code", 1

    bs.InsertRecord recP

    bs.RelateRecordsToID recP, "act_entry", actEntryObjid, "participant2act_entry"

    bs.RelateRecordsToID recP, "user", previousOwnerObjid, "participant2user"

    bs.Save

 End If

End Sub

Sub YANK_BTN_Click()

 Dim previousOwnerObjid As Long

 previousOwnerObjid = GetCurrentOwnerObjid()

 Me.DoDefault

 SaveParticipant previousOwnerObjid

End Sub

Normally, I would add the participant record within Form_Save1 or Form_Save2, but this didn’t work. It exhibited some really strange behavior and threw some gawd-awful OST subsystem errors. So, I punted, and just added it after the default behavior happened on the Yank button.

Also notice that I only added support for cases and subcases. If you want to support other object types, add them to the Select Case portion of the GetCurrentOwnerObjid function.

Lets give it a whirl

From the Clarify Classic Client, Yank a case:

and then we should see an email notification come through:

and we should see the Yank activity and the Business Rule action in the case activity log:

Success!

You may now continue yanking away (does that sound slightly naughty?). And the person you yanked from will be notified appropriately.

Hope you find this useful.

And that wraps up my blog posting for 2011. See you in 2012.

Rock on.

Better message notifications in the Clarify Client

gsherman — Mon, 12 Dec 2011 19:39:28 +0000

One of the common ways to do a message / notification to user from a from within the Clarify Classic Client is with a simple popup message box.

For example, if the user does a save operation on a form, and the save is successful, then it’s not uncommon to see a simple message box posted.

Sub btn_message_click()
App.MsgBox "Something Interesting Just Happened"
End Sub

These messages are purely informational. We’re not requiring the user to make a decision – we just want to tell them something.

The problem is that these message boxes interrupt the user’s flow.

Don’t interrupt my flow, man

Alan Cooper, in his book About Face 2.0, calls this stopping the proceedings with idiocy. And that's exactly what it is.

There is a particular form of excise that is so prevalent it deserves special attention. In Chapter 9, we introduced the concept of flow, where the user enters a highly productive mental state by working in harmony with his tools. Flow is a natural state, and people will enter it without much prodding. It takes some effort to break into flow after someone has achieved it. Interruptions like a ringing telephone will do it, as will an error message box. Most interruptions are avoidable; a few aren't. But interrupting a user's flow for no good reason is stopping the proceedings with idiocy and is one of the most disruptive forms of excise.

Jeff Atwood expands on this: Unnecessary Dialogs: Stopping the Proceedings with Idiocy

It’s better on the web

On most good web sites, we don’t get these kind of popup messages – instead we’ll see a message as part of the page that gives the information, but doesn’t interrupt flow.

An example from Gmail, when an email is deleted:"

Improved Clarify messages

So lets look at accomplishing a similar type of non-invasive informational message within the Clarify Classic Client.

Here’s what it looks like.

I start with a simple form:

When I click the “Show a Message” button, the form shows an information message, on the form, without interrupting the user’s flow:

Implementation

This is actually pretty simple to do.

1. Add a new label to the form.

I’ve set its BackColor so that it stands out appropriately. I’ve also set the Visible property to false so that the label is initially invisible.

2. Add a little bit of ClearBasic code to set the message string, and make the label visible.

Sub btn_go_Click()
    ShowMessage "Something Interesting Just Happened"
End Sub

Sub ShowMessage (messageString As String)
    lbl_message.caption = Space$(5) & messageString
    lbl_message.Visible=True
End Sub

Upon clicking the button, my message shows:

In a web app, it’s easy to make that message go away after a few seconds. We can use a little jQuery to hide an element:

$("#message").hide();

And we can even use jQuery to fade it out, which is pretty sexy:

$("#message").fadeOut("slow");

In Clarify, we can hide the message after a few seconds:

Sub ShowMessage (messageString As String)
    lbl_message.caption = Space$(5) & messageString
    lbl_message.Visible=True
    Sleep(3000)
    Call HideMessage
End Sub

Sub HideMessage()

On Error Resume Next
       lbl_message.caption = ""
       lbl_message.Visible=False
End Sub

Notice that in the ShowMessage subroutine, I sleep for 3 seconds, and then hide the message by making it invisible.

What about a sexy fadeout?

Sorry – I haven’t solved that task yet. Maybe a task for another day.

Won’t the Sleep command block the user from doing other operations?

I thought that myself. But as it turns out, no. It doesn’t block. While that Sleep statement is happening, it blocks the current (ShowMessage) subroutine, but not other code.

So the user is free to do other things. Sweet!

But (there’s always a but) – if you open a modal dialog while that sleep is occurring (including a MessageBox), that will block other code from executing. When the modal dialog is dismissed, the other code can resume.

If your modal dialog has been opened for more than the Sleep time, then the next statement after the sleep will be immediately executed.

In my scenario, I can click the “Show a Message” button, which will show the message on the form. I then immediately click the “Show Message Box”, which opens a message box (App.MsgBox). While that MessageBox is posted, the message remains on the form. If I wait more than 3 seconds to close the MessageBox, then the message is hidden as soon as I dismiss the MessageBox.

Pretty nice!

What’s with the On Error Resume Next?

Notice that in the HideMessage subroutine, I’m doing an On Error Resume Next. This says, any messages that happen in this subroutine, just ignore.

The reason I’m doing this is to handle the following scenario:

Display a message by calling ShowMessage
Close the form before the Sleep time expires (within 3 seconds), while the message is still visible.

What will happen is that when the Sleep timer expires, the next line of code will be executed: lbl_message.caption = ""

Because the form is already closed, Clarify can’t find that label, so you get this lovely error message:

The given form for this operation is invalid (possibly already closed).

So, in order to workaround this, I’m just ignoring any error that results from hiding the message.

Niceties

We could sexy this up a bit by changing the background color of that message dynamically.

For example, if I want an informational message to be displayed in Yellow, but an error to be displayed in Red, then I could do that.

So an error message might look like:

To do this, we’ll create a new color scheme, and set the colors appropriately. Then we’ll call either ShowInfoMessage or ShowErrorMessage, which sets the colors appropriately before showing the message:

Sub CreateColorSchema()
    Dim LabelList1 As New List
    Dim ColorList1 As New List
    LabelList1.AppendItem "ErrorBackground", "ErrorForeground", "InfoBackground", "InfoForeground"
    ColorList1.AppendItem "Red", "White", "Yellow", "Black"
    App.CreateColorScheme "messages", LabelList1, ColorList1
End Sub

Sub Form_Load()
    Me.Dodefault
    Call CreateColorSchema
End Sub

Sub ShowMessage (messageString As String, level As String)
    lbl_message.Visible=True
    lbl_message.BackColor = level & "background"
    lbl_message.ForeColor = level & "foreground"
    lbl_message.caption = Space$(5) & messageString
    Sleep(3000)
    Call HideMessage
End Sub

Sub ShowErrorMessage (messageString As String)
    ShowMessage messageString, "error"
End Sub

Sub ShowInfoMessage (messageString As String)
    ShowMessage messageString, "info"
End Sub

Sub HideMessage()
    On Error Resume Next
       lbl_message.caption = ""
       lbl_message.Visible=False
       lbl_countdown.Visible = False
End Sub

Sub btn_info_Click()
    ShowInfoMessage "Something Interesting Just Happened"
End Sub

Sub btn_error_Click()
    ShowErrorMessage "An Error Happened"
End Sub

Summary

So there you have it – a better way to show informational and error messages to your users without interrupting their flow.

Hope you find this useful.

Improving Attachments in the Clarify Classic Client

gsherman — Fri, 09 Dec 2011 19:03:52 +0000

A common issue with attachments in Clarify is getting the uploaded files to a common location.

By default, Clarify simply takes the filepath you give it (such as c:\temp\file.ext) and creates attachments records in the database with that filepath.

Obviously, no one else is going to be able to view an attachment that resides on a user’s C drive. So that default behavior stinks.

I’ve seen a number of attempts of solving this over the years. A couple common ones:

Create a shared drive (such a Z:\ or \\attachment_server\), and tell users to copy files there, and then attach them.
Add an FTP customization to the attachments form, so that files are automatically FTP-ed form the user’s machine to a common location.

I’m not really crazy about either of these solutions. In the first, it requires users to remember to do something. In the second, you end up with FTP permission issues, and its often the case that files end up in one huge directory.

It’s better on the web

With web applications (such as Dovetail Agent, Agent Lite, and Mobile), we’ve solved this issue. The file is uploaded to the web server, and then from there we have full control over what to do. Typically we store it on a common share (such a Z:\ or \\attachment_server\), and dynamically built subdirectories to keep things organized.

For example, the directory structure would look like \\server\attachments\PartialCaseId\CaseId\file.ext, such as \\server\attachments\009xxx\009009\file.ext

Then, when we want to download those files, we can simply serve them up by HTTP (which I discussed in a previous post).

How can we use the web to upload/download attachments from Clarify?

Pretty simple. We use a web browser control on a form set to a URL that handles our file uploading and downloading.

This is the same technique I described previously in Improving Case History within the Clarify Classic Client.

So what might this look like?

For a quick example, I re-used the attachment page from Dovetail Agent. Here’s the Clarify attachment form (form 1006) with a browser control on it:

The ClearBasic code behind it:

Sub Form_Load()
    Me.DoDefault

    Dim rec As Record
    Set rec = App.GetContext
    web.Navigate http://myserver/agent/workflow/clarify_attachment.asp?flag=1 & objid=" & rec.getField("objid") & "&type=" & rec.RecordType

End Sub

Pretty simple. Users can upload/download and delete file attachments. The files are automatically uploaded to the web server, and then can be moved to their final storage location. In my example, they’re stored on a server called tommy in a share named Attachments.

Roll your own

Now, if you’re not using Dovetail Agent, you might have to whip your own little web app to do this. But that’s pretty straight-forward for any web developer.

And it doesn’t matter if your web app is running on Windows, UNIX, or Linux. Your web app makes it easy for users to upload attachments – where you store them is up to you.

Keep in mind though that you still need to do the “Clarify stuff”, i.e. inserts/deletes from table_doc_inst and table_doc_path, and relating them to the proper entity (such as a case or subcase). This is where Clarify libraries such as the Dovetail SDK or Clarify CBOs come into play.

To the cloud!

Here’s another thought. What if all of these attachments were stored in the cloud, such as Amazon S3? Your web app could post/upload those files directly to your Amazon S3 account, and you could get out of the business of storing huge amounts of local file attachments. Hmmm……very interesting……

Summary

I think this is an interesting approach to improving a “legacy” application by incorporating contemporary technologies. And as legacy apps like the Clarify Client are phased out, we should be able to re-use much of the web-based components that we’ve built.

Rock on.

Customizing the Clarify Attachment Form (form 1006)

gsherman — Mon, 14 Nov 2011 15:18:32 +0000

I recently had to do some modifications to the attachment form in Clarify (form 1006). This is one of those old-school forms that doesn’t always behave very well with ClearBasic. This post captures a few of my findings and learnings.

FILELIST Double-Click

One of the things I wanted to do was to intercept the double-click action on the FILELIST control, which happens when a user double-clicks a file to Open it.

Plan A: some simple Clearbasic code

Sub FILELIST_DblClick()
If FileValidation = True Then
Me.DoDefault
Else
App.MsgBox "Not authorized"
End If
End Sub

Looks simple right? But it doesn’t work. Even if the Me.DoDefault code isn’t ever called, the file is still opened. So if the validation failed, the user would get the message box saying "Not authorized", and then the file would be opened. No bueno.

I tried everything I could think of, but I couldn’t prevent the file from being opened. I found an old forum post with the same findings.

Plan B: Change the FILELIST control so that it’s no longer a fancy file renderer with drag and drop capabilities, and just make it a plain ol’ listbox. I did this by deleting the existing control, then adding a new listbox with the same name (FILELIST), and the same source and destination contextual objects. I think the same thing would work by changing the flags on that control_db record from 32768 to 0.

Now I am able to trap the double-click event on that textbox.

I did lose the ability to drag and drop files onto that control now, but that didn’t matter for my scenario (and I have a hunch that no one uses this anyway).

Here’s what the baseline attachment form looks like, with a “fancy” listbox for files:

And now after changing it to a non-fancy listbox:

I actually prefer this, as I can see more than just a couple of files at a time.

But, the filelist listbox now showed a full file path and file name for each of the attachments. I didn’t like that.

Make it Better

Lets get rid of the full path in the listbox.

A little ClearBasic code:

Sub ReplaceFilePathsWithJustFileName()
    Dim allFiles As List
    Dim i As Integer
    Dim fileAndPath As String
    Dim fileName As String
    Dim n As Integer

    cobj_doc_list.GetContents allFiles

    For i = 0 To allFiles.Count - 1
        fileAndPath = allFiles.ItemByIndex(i)
        fileName = GetFileNameFromFileAndPath(fileAndPath)
        allFiles.ReplaceByIndex i, fileName
    Next i
    cobj_doc_list.Fill allFiles
End Sub

Sub Form_Load()
    Me.DoDefault
    Call ReplaceFilePathsWithJustFileName()
End Sub

Sub ADD_BTN_Click()
    Me.DoDefault
    Call ReplaceFilePathsWithJustFileName()
End Sub

Sub REPLACE_BTN_Click()
    Me.DoDefault
    Call ReplaceFilePathsWithJustFileName()
End Sub

And now our listbox of files looks like:

Cleaner. I like it.

Default the Attachment Name

One of my annoyances with that form is that when you browse and pick a file to be attached, you also have to enter an attachment name. I always wish that this had some sort of smart default, such as defaulting to the name of the file (without the path).

Since I was knee deep in that form, I tried to give it a try.

I added a click handler for the Browse button so that it gets the full file and path, gets just the file name out of that, and then puts that file name into the attachment name textbox:

Sub FILE_BTN_Click()
Dim fileAndPath As String
Dim fileName As String

Me.DoDefault

    fileAndPath = FILE.Value
    fileName = GetFileNameFromFileAndPath(fileAndPath)
    Ctl_Name.Value = fileName
End Sub

And a little helper function for extracting just the filename:

Function GetFileNameFromFileAndPath(fileAndPath As String) As String
    Dim n As Integer
    n = ItemCount(fileAndPath,"\")
    GetFileNameFromFileAndPath = Item$(fileAndPath,n, n + 1,"\")
End Function

So now, when you browse and pick a file, the Attachment Name will be defaulted to the filename. Sweet.

Download File Attachments via HTTP

An additional enhancement that I was working on was the ability to download a file attachment via HTTP. In a customer-specific scenario, we were uploading attachments via a Dovetail web application (Dovetail AgentLite), so they get stored on a common server, and we can download them via a URL.

I added a readonly URL textbox to the form (which was super helpful when developing).

When a file is clicked in the listbox, we want to build the proper URL, and fill that into the textbox via the contextual object.

I’m using our Dovetail Mobile as a web app for serving up that file. If desired, you could also serve it up just via your web server serving up a static file, without needing a Dovetail web app at all.

Const Base_Dovetail_URL = "http://localhost/mobiledev/Attachments/Download/"

Sub FILELIST_Click()
    Me.DoDefault
    Cobj_url.Fill BuildURL()
End Sub

Function BuildURL() As String
    Dim recDocInst As Record
    COBJ_doc_inst.GetContents recDocInst

    BuildUrl = Base_Dovetail_URL & CStr(recDocInst.GetField("objid"))
End Function

Open that file

And finally, a little code to open the file URL using the user’s browser.

Sub OpenURL(url)
    Dim taskID As Variant
    taskID = Shell("explorer.exe " & url)
End Sub

Sub EDIT_BTN_Click() 'Note: This is the "Open" button
    Dim url As String
    url = BuildUrl()

    OpenURL(url)
End Sub

What about file uploads?

In the specific customer scenario I was working on, they aren’t uploading file attachments via the Clarify Client – just by Dovetail. So I was able to simply disable the Browse, Add, Replace, and Delete buttons.

Uploading files to a common location is an interesting topic – perhaps for a future blog post.

Summary

The attachment form is certainly a tricky form to customize. Hopefully some of my experience will help should you have to customize this form yourself.