Ryan Farley's Blog

A Deeper Look at Adding Custom Fields in SalesLogix Mobile

Ryan Farley — Tue, 07 May 2013 16:00:00 GMT

We looked previously at adding custom fields to the SalesLogix Mobile client. It was easy enough to do, but as I've mentioned before, one of the hardest parts about customizing the mobile product is that you have to know what to type. Let's take a look at just what's available when adding custom fields in an customization module so you'll have all the knowledge you need.

Background

When we looked at adding custom fields to the mobile client previously, we used a "registerCustomization" function and passed in some values. We didn't really discuss in that post how to know what parameter values are available to pass into this function. That can make it hard to know exactly what to type and what you can and can't do there. We're going to examine every part of that statement so you understand how it works, what's available, and where to look to figure all this out for yourself.

The registerCustomization Function

The registerCustomization function is implemented in the Application.js file in the Argos-SDK. Well, what you're actually using in your ApplicationModule is the registerCustomization function in the ApplicationModule.js in the Argos-SDK, which is the base code your own custom ApplicationModule extends, but the function there only passes the details along to registerCustomization in the Application.js, so the ApplicationModule base code doesn't really do any of the work. Why is this important? Because you can look at the code in the Argos-SDK to find out everything you need to know about using this function to add custom fields. The fact that you have all the source code available to you is helpful. So use it. In a sense, it's like some additional documentation (although source code doesn't really count for as much as real documentation, but at least it's something). Let's look in the Application.js file (located in the argos-sdk\src folder) to see what the registerCustomization function does. The most useful thing you'll find there is the comment preceding the function itself. It says the following:

So, here's what we know so far about what you pass to registerCustomization:

It can take either 2 or 3 parameters (we can tell this by looking at the function signatures in Application.js and ApplicationModule.js, as well as the comment):

path: A path is in the form of something like "edit#account_edit". Alternatively, you can pass these separately as "edit", "account_edit".
spec: The "spec" is the set of parameters that define the customization we're adding. We'll outline these parameters next.

The Customization Specification

The customization specification, or "spec" is what describes the WHAT YOU ARE DOING part of the customization. "I want to add a customization here". The spec parameter options are:

"at" which describes where you want the customization. This can be an index, but usually is a function that evaluates to true when for the row you want to look for. This function is passed the current row item. As the view is built and as each row is created, the row item is passed to this function. You can then check properties of that row, usually the row.name to see if it's the one you want. So, if this function evaluates to true, then it looks at the "type" and "where" parameters to see what to do next.
"type" which is the type of customization. This indicates what action to take when the "at" evaluates to true. So, when the "at" function finds the right row, this tells it what to do. The choices are:

"insert"
"modify"
"remove"

"where" only applies if the "type" is an insert. If we're inserting a new element, do we want it before of after the located row in the "at" param. Obviously, the choices are:

"before"
"after"

"value" is the parameter that contains what you're customization contains. This is the actual "customization". All the properties to set for the customization are wrapped up in this object. Optionally, you can pass an array of values, meaning an array of customizations, you're adding. This parameter is the most important part. However, this sort of looks like a black hole. How do we know what choices are available? Let's look at that next.

All in all, we'll end up with something that looks like this. This sample, adds a customization to the account_detail view:

this.registerCustomization('detail', 'account_detail', {
    at: function (row) { return row.name == 'LeadSource.Description'; },
    type: 'insert',
    where: 'after',
    value: {
        name: 'NewField1',
        property: 'NewField1',
        label: 'new field 1'
    }
});

The basic structure is:

this.registerCustomization('[set]', '[view id]', {
    [spec parameters], // WHAT YOU ARE DOING
    value: {
        [value parameters] // WHAT YOU ARE ADDING
    }
});

OK, let's move on and see what choices there are for the value (or customization) object.

The Customization Object (The Values)

The customization values is the set of properties and values that describe the WHAT YOU ARE ADDING for the customization. This is the important part. This is what you actually want added to the view. The spec above outlines the what you are doing, "I want to add a customization here", and the values object outlines what you're actually adding.

So, how do we know what is available for this set of values? What are the available properties for this? Well, we have to think for a minute about *what* exactly we are adding. We're adding a text value, or a picklist, or a lookup, or something. In short, we're adding a field. It just so happens that there is a defined base "field" in the Argos-SDK (the actual object is named "_Field"). All fields start from this base field object. There's also a specific field object for each of the different field types. For example, the "_Field" object is extended by the implementation for a picklist. The reason this is important to understand is because looking at the implementation for these field types will show up what the available properties are. What we're actually setting in this values object that we pass to registerCustomization is a set of the properties for this field.

Let's start by opening up the _Field.js file (located in the argos-sdk\src\fields folder). This is the base type for any field. We can scroll through that and see the available properties. These are some of the properties we can set for our values object for our customization. We can see properties such as:

owner
disabled
hidden
'default' (to set a default value
name
label
property (the SData property to bind to)
type
validate
clearValue()
setValue()
and so on...

Luckily, these properties all have comments with them that describe what each of the properties & functions are for. Next, we can look at the implementation of the specific field type we're adding. For example, open the LookupField.js (located in the argos-sdk\src\fields folder). We can look through this and see even more properties we can set if the customization is adding a lookup field. There are properties such as:

widgetTemplate (if we want to define a new look for the control)
dependentErrorText
emptyText
completeText
cancelText
lookupText
view
keyProperty
textProperty
valueKeyProperty
valueTextProperty
requireSelection
resourceKind
where
orderBy
to list only some of the available properties...

Now we're getting a more complete picture of what the available choices are for our values object. Sweet.

We can see even more field types (the SalesLogix specific ones) implemented in the argos-saleslogix\src\fields folder. We can see the picklist, address, name fields, etc. We can open those just the same to see what's available and even better, we can override the default behavior easily as well and provide our own implementation for this. For example, a common request is how to customize the name parts dialog, or the address dialog. It couldn't be easier in mobile. The template for these are located in these files and you can provide your own template for them by just setting the property with the new template (we'll look at templates later on in a future article).

Conclusion

I guess the point I am trying to make with all of this, besides trying to outline exactly what you're doing when you add registerCustomization in an ApplicationModule, is to point out that while there isn't tons of documentation for the mobile platform, we can learn just about everything we need by looking at the source code. Good luck.

Consuming Data from External Applications in SalesLogix Mobile Customizations

Ryan Farley — Tue, 30 Apr 2013 16:00:00 GMT

The SalesLogix Mobile client is more customizable than you might think. It's easy to assume that the new architecture isn't as customizable as you might be used to with SalesLogix Web or LAN clients. However, it does sometimes take some rethinking. In this article we'll look at how to add a customization that pulls in data from the Twitter API and displays on the contact detail. We'll delay the loading of the data so that the contact detail will display quickly and bring in the data from Twitter when it is received.

Background

For this customization what we'll be doing is adding code to pull in a contact's last tweet from the Twitter API and displaying it on the contact detail screen in SalesLogix Mobile. While there are a few different ways we could be doing this (for example, we could do this on the server using a custom code property on the entity), we'll be letting the contact data load normally, and we'll delay the loading of the data from Twitter until after the contact data has loaded. On the detail screen we'll see the last tweet, however on the edit screen we'll see a textbox allowing the user to add a contact's twitter name. In my test system I have already created a contact property called TwitterName and have redeployed my SData portal so the TwitterName property is in the contact SData feeds.

What exactly do I mean by "delay loading"? What I mean is that instead of going out to Twitter and getting the last tweet while the contact detail is loading, we let the contact detail screen load normally, and then we asynchronously go get the last tweet and update the UI once it is received. Doing things this way will allow the contact screen to load quickly and not be slowed down by whatever slowness the Twitter API might be experiencing at the moment. Also, note that the point of this example isn't to demonstrate how to grab data from Twitter, or the best way to do that, but to show how to go grab data from any other system using this technique. This could be used with getting something from an external support system, accounting system, or whatever.

Adding the Basic Customization

First, what we'll need to do is add the basic customization. Meaning, we'll add the TwitterName property to the query used for the detail and edit screens and also add the UI control elements. If you've been following the previous posts in this series, you should already know how to do this:

See Adding Custom Fields to SalesLogix Mobile

Here's the code for adding the TwitterName to the queries for the edit and detail screens as well as the UI element for the detail and edit screens. Note, that for the UI element on the detail screen, we're not actually binding the property to it. Instead we're just adding a "loading" message and icon (we'll have code that adds the result from the Twitter API to that element later):

// Add TwitterName to the query for the detail view            
dojo.extend(Mobile.SalesLogix.Views.Contact.Detail, {
    querySelect: Mobile.SalesLogix.Views.Contact.Detail.prototype.querySelect.concat([
        'TwitterName'
    ])
});

// Add TwitterName UI element (note, we're only adding the "loading" message here
// The data will be loaded in later when recieved from the Twitter API
this.registerCustomization('detail', 'contact_detail', {
    at: function (row) { return row.name == 'CuisinePreference'; },
    type: 'insert',
    where: 'after',
    value: {
        name: 'TwitterName',
        label: 'twitter',
        property: 'TwitterName',
        cls: 'content-loading', // add "loading" icon
        value: 'loading...'     // add "loading" message
    }
});

// Add TwitterName to the query for the edit view
dojo.extend(Mobile.SalesLogix.Views.Contact.Edit, {
    querySelect: Mobile.SalesLogix.Views.Contact.Edit.prototype.querySelect.concat([
        'TwitterName'
    ])
});

// Add TwitterName UI element to the edit view so the user can add a contact's 
// twitter name
this.registerCustomization('edit', 'contact_edit', {
    at: function (row) { return row.name == 'CuisinePreference'; },
    type: 'insert',
    where: 'after',
    value: {
        name: 'TwitterName',
        property: 'TwitterName',
        label: 'twitter',
        type: 'text'
    }
});

For the UI element for the detail view, we're not displaying the TwitterName property itself (yet). Instead we're just displaying the "loading" message. We still need the TwitterName in the querySelect for the detail screen. Later, we'll be adding code that gets this from the bound SData entity so we'll need it to exist in the SData entity for the view. If we took at look at things right now, the screen would look like this on the detail screen:

When we're done, this "loading" message will display until our request comes back from Twitter - at that point we'll clear this loading message and replace it with the data returned. It would look like this on the edit screen:

What we need to do now is add some code that goes out to grab the last tweet from the Twitter API and load it into the UI element when it comes back.

Delay Loading the Last Tweet from Twitter

To be able to pull in the last tweet into the UI element we created, we'll need to extend a method in the base code for the detail screen. To open and view the base code for the detail screen, go to the argos-sdk\src folder and open the Detail.js file. Scrolling through that code, we'll find the following method:

/**
 * Saves the SData response to `this.entry` and invokes {@link #processLayout processLayout} by passing the customized
 * layout definition. If no entry is provided, empty the screen.
 * @param {Object} entry SData response
 */
processEntry: function(entry) {
    this.entry = entry;

    if (this.entry)
    {
        this.processLayout(this._createCustomizedLayout(this.createLayout()), this.entry);
    }
    else
    {
        this.set('detailContent', '');
    }
}

From the comment, we can understand that this method receives the bound SData entity and then loads the data onto the screen. This will be perfect for us to use this and asynchronously load the last tweet from Twitter. We're not going to edit this file directly. That wouldn't be a good idea since this code is the base for all detail screens, not just the contact one. Instead, we're going to extend this function in our ApplicationModule.

To extend this function our code will look similar to how we extend the querySelect on the base contact view. However, instead of extending the querySelect, we'll be extending the processEntry function. The most important part of this is that we pass everything back to the base code so the view can be loaded normally as well. If we neglect this part our code will execute but the rest of the code in the base Detail.js won't so none of the UI elements will be added to the view. The empty function would look like this when we add it to our ApplicationModule:

dojo.extend(Mobile.SalesLogix.Views.Contact.Detail, {
    processEntry: function(entry) {
        // you MUST pass everything back to base class so it can continue
        // loading the view
        Mobile.SalesLogix.Views.Contact.Detail.superclass.processEntry.apply(this, arguments);
        

        // WE WILL ADD THE REST OF OUR CODE HERE

    }
});

Notice the line:

Mobile.SalesLogix.Views.Contact.Detail.superclass.processEntry.apply(this, arguments);

This line is what passes things back to the base processEntry code, applying the arguments (meaning the SData entity) to it and allowing it to proceed normally. This line is important.

Before we add the rest of the code, we'll need to make some other parts of dojo available. Specifically, we'll need to use "dojo/dom-class" and "dojo/query" available to us so we can find and manipulate the UI element to update the value received from Twitter. To do this, we just need to change the header or declaration of our ApplicationModule. Right now the first few lines of our Application Module looks like this (my product name is "Custom"):

define('Mobile/Custom/ApplicationModule', [
    'Sage/Platform/Mobile/ApplicationModule'
], function () {
    return dojo.declare('Mobile.Custom.ApplicationModule', Sage.Platform.Mobile.ApplicationModule, {
        loadCustomizations: function () {
            this.inherited(arguments);

We'll use dojo's AMD loading to bring in these dependencies and change those lines to look like this:

define('Mobile/Custom/ApplicationModule', [
    'Sage/Platform/Mobile/ApplicationModule',
    'dojo/dom-class',
    'dojo/query'
], function (
    ApplicationModule,
    domClass,
    query
) {
    return dojo.declare('Mobile.Custom.ApplicationModule', Sage.Platform.Mobile.ApplicationModule, {
        loadCustomizations: function () {
            this.inherited(arguments);

I'll cover more on dojo's AMD loading and mixins in a future post, but for now you can read more on the dojotoolkit.org blog.

Now, let's add the code that does all the work of going out to the Twitter API and getting the last tweet for this contact:

dojo.extend(Mobile.SalesLogix.Views.Contact.Detail, {
    processEntry: function(entry) {
        // you MUST pass everything back to base class so it can continue
        // loading the view
        Mobile.SalesLogix.Views.Contact.Detail.superclass.processEntry.apply(this, arguments);
        
        // get the TwitterName property from the bound SData contact entity
        var twitterName = entry['TwitterName'];

        // locate the TwitterName row
        var rowNode = query('[data-property="TwitterName"]', this.domNode)[0],
            contentNode = rowNode && query('span', rowNode)[0];

        // remove the "loading" message
        if (rowNode)
            domClass.remove(rowNode, 'content-loading');

        // exit if the contact does not have a twitter name
        if (twitterName == null) {
            contentNode.innerHTML = '';
            return;
        }
        
        // now we'll go get the last tweet from twitter
        dojo.require("dojo.io.script");
        dojo.ready(function() {
            dojo.io.script.get({
                url: 'https://api.twitter.com/1/statuses/user_timeline/' + twitterName + '.json?count=1&include_rts=1',
                callbackParamName: "callback",
                load: function(data) {
                    var twitterText = "<img src=\"" + data[0].user.profile_image_url + "\" align=\"left\" style=\"padding-right:8px;\">" + 
                                      data[0].text + "<br />" + 
                                      "<a href=\"http://twitter.com/" + twitterName + "\">@" + twitterName + "</a>";

                    // update the node to display the data
                    if (contentNode)
                        contentNode.innerHTML = twitterText;
                }
            });
        });
    }
});

With this code in place we'll see the following on the contact detail screen (last tweet from @RyanFarley, and what a "meaningful" tweet it is, lol)

Conclusion

As I mentioned earlier, this isn't an exercise to see how to best grab a tweet from Twitter, but the process we've gone through is how we could go grab any data from any system in the mobile client. We could even go back to SalesLogix using SData to grab some related data of some kind and it would be delay loaded so things stay snappy.

Download the complete ApplicationModule.js file from this article

Formatting Data in SalesLogix Mobile Customizations

Ryan Farley — Tue, 23 Apr 2013 16:00:00 GMT

When adding custom fields to SalesLogix Mobile, you'll often want to do things to the value, instead of just displaying it as-is. There are many built-in formatting functions, or renderers, available in the out-of-the-box SalesLogix Mobile platform, but what if you need to do something custom? Let's take a look at what built-in formatting functions there are as well as how to create you own custom formatting function on the fly.

Where/how do you use formatting for a custom field in mobile?

First of all, what are formatting functions (or renderers)? Simply put, a formatting function is a function that takes a value and changes it so it is formatted differently than the raw data value. A format function can do things like take a phone number, stored as 8005551212 and format it like a phone number like (800) 555-1212. A format function can take a numeric value like 6543.21 and format it like $6,543.21. They are also called renderers when you're using them. If you're adding a field that is a phone number, you'll add a "renderer" to tell it to format the value as a phone number like this:

this.registerCustomization('detail', 'account_detail', {
    at: function (row) { return row.name == 'Type'; },
    type: 'insert',
    where: 'after',
    value: {
        name: 'SecretPhone',
        property: 'SecretPhone',
        label: 'secret phone',
        renderer: Mobile.SalesLogix.Format.phone
    }
});

Built-in Formatting Options

There are a lot of built-in renderers. Some trim spaces from the value, some format the value like a hyperlink, and some are a bit more complex too. You can see the entire list of available formatting functions on the Argos SDK wiki:

Built-In Templates & Formatting Functions

You can see the code for these built-in functions as well. If you noticed on the page linked above, some of the formatting functions are part of the Argos SDK, while other are implemented in the argos-saleslogix product itself (also note that they can all be referenced via Mobile.SalesLogix.Format). To see the ones implemented in argos-saleslogix, navigate in your development environment to \products\argos-saleslogix\src and look for the Format.js file. The ones implemented in the Argos SDK can be found in the Format.js file in argos-sdk\src. If you open up those files, you can see that most of the formatting functions take in a single parameter and then return a string (the formatted result).

How do you create a custom formatting function?

It's easy enough to create formatting functions on the fly. Keeping in mind that it takes a single parameter and returns a string. If you refer back to the code in this article, the sample where you'll see the renderer property set to Mobile.SalesLogix.Format.phone. Well, Mobile.SalesLogix.Format.phone is a function. It's set as the value of the renderer property, but it's still a function. Rather than set a predefined function for the renderer, we can just create one in-line. For example, let's say we have some "customer code" stored in the Account entity and that we can launch a URL including this code to go to some other website and see tickets for that customer code. If we add this in mobile, all we have is the code, so we'll use a format function to format this code value as the URL we want to launch, and the user will just see the code itself as a hyperlink. Here's how we do that:

this.registerCustomization('detail', 'account_detail', {
    at: function (row) { return row.name == 'Type'; },
    type: 'insert',
    where: 'after',
    value: {
        name: 'CustomerCode',
        property: 'CustomerCode',
        label: 'customer code',
        renderer: function(val) {
                    return '<a href="http://somewebsite.com/orders?customerCode=' + val + '">' + val + '</a>;
                }
    }
});

Not too bad, you can see all we need to worry about is taking a single parameter and returning a string. Easy. The user will see the customer code as a hyperlink and when clicked it will launch the URL.

Bundling and Deploying SalesLogix Mobile Customizations

Ryan Farley — Tue, 16 Apr 2013 16:00:00 GMT

Once you've started creating customizations for your SalesLogix Mobile, at some point you'll want to start getting those customizations into production by deploying them or bundling them to add to your production system. This article will walk you through how to do this in both SalesLogix v8 as well as in SalesLogix v7.5.4. You'll even get a video to follow along through the whole thing.

Background

This video walks through how to add your customizations into Application Architect, bundle them, and deploy them. Take a look at the write-up following the video to see the steps specific to both SalesLogix v8 and SalesLogix v7.5.4.

Watch Bundling and Deploying SalesLogix Mobile Customizations on YouTube
The video will open on youtube.com in a new window

Steps to Add Customizations To SalesLogix v8

These steps are for adding your customizations to Application Architect in SalesLogix v8. This also assumes you've created your customization product using the SalesLogix Mobile Developer Toolkit.

In Application Architect, open your SalesLogix Mobile portal
Go to the "Custom Modules" tab
Click the add ("+") button
Browse for your "module-info.json" file in your customization product (layer)
Ensure the checkbox next to you newly listed customization product is checked on the Custom Modules tab
Save everything and deploy

Steps to Add Customizations to SalesLogix v7.5.4 (Manual Steps)

These steps are the manual steps for adding your customizations to Application Architect in SalesLogix 7.5.4. These steps work in SalesLogix v8 as well, but the built-in way (outlined above) is far easier. This also assumes you've created your customization product using the SalesLogix Mobile Developer Toolkit.

In Application Architect, open your SalesLogix Mobile portal
In the Support Files tab, under "source\products", add the same folder structure, along with all files, from your customization product
Open the release.jsb2 file under "source\products\argos-saleslogix\build" folder and scroll to the bottom to locate the "resources" section
Just ABOVE the "resources" section, there is line with a "]," - just ABOVE that, add the package from the release.jsb2 file in your customization product. In my system, my custom product was named "argos-custom" so it ended up looking like this (also, don't forget the comma after the "}" above this line):
Now, copy the resource from the release.jsb2 file in your customized product and paste as an entry in the resources section of the release.jsb2 file in the argos-saleslogix\build folder as well. Mine looked like this:
Open the index.html file in the argos-saleslogix folder
Under the "" line, add the following (my custom product is called argos-custom):
```
<script type="text/javascript" src="content/javascript/argos-custom.js"></script>
```
Now locate the configuration section in the index.html. It starts with "configuration = [" and at the end of that section add a comma and then your configuration (my customization product is named "custom" so it looked like this):
Save everything and deploy

What to Include in the Bundle?

In the Support Files tab of the portal, include the following:

Your custom product folder
The modified release.jsb2 file under the argos-saleslogix\build folder
The modified index.html under the argos-saleslogix folder

All of this might seem like a lot of steps, but once you've done this once it becomes much easier. Refer back to the video as needed for the complete walkthrough.

Updates to the SalesLogix Mobile Developer Toolkit

Ryan Farley — Wed, 10 Apr 2013 19:37:00 GMT

I've released some updates to the SalesLogix Mobile Developer Toolkit. This new release adds some fixes and a few new features.

Download the SalesLogix Mobile Developer Toolkit

New Features

Some of the more notable new features in the SalesLogix Mobile Developer Toolkit are the following:

Support for adding the Mobile 2.0 backwards compatibility module for SalesLogix 7.5.4

There is now an option for including the mobile 2.0 backwards compatibility module for SalesLogix 7.5.4. This means, if you're on SalesLogix 7.5.4, you can use Mobile 2.0 instead of Mobile 1.2. If you're using SLX Mobile at all, going with Mobile 2.0 is by far the best route. This option will add the backwards compatibility module to your development environment for you.

Master Index File Created in the Development Environment Root

The SalesLogix Mobile Developer Toolkit now creates an index.html in the root of your development environment. Any new customization products that you create get added to this index file automatically.

Now, you can navigate to the root of your development environment and see a list of all customization products in your development website. Obviously, you can click on any of these customization products and open the mobile website with that customization product loaded. Go back to the root and load some new set of customizations by clicking on a different customization product.

If you already have the toolkit installed, simply opening it up will cause it to automatically upgrade to this new version.

Download the SalesLogix Mobile Developer Toolkit

If you've not yet tried out the toolkit, download it and take it for a spin. Also, be sure to check out my new developer series on SalesLogix Mobile. See the series index for a list of articles to get started.

Adding Custom Fields to SalesLogix Mobile

Ryan Farley — Tue, 09 Apr 2013 16:00:00 GMT

Time to take SalesLogix Mobile to the next level. Customization! This article will outline how to add custom fields to SalesLogix Mobile, from start to finish. You'll walk through every step, from creating the custom field to viewing and editing it in SalesLogix Mobile. Best part? You'll see a video that walks you through the whole process.

Background

So, you've gotten your SalesLogix Mobile development environment all set up and ready to go. Now what? Well, it's time to start customizing it. In the video below we'll walk through the entire process.

Watch Adding custom fields to SalesLogix Mobile on YouTube
The video will open on youtube.com in a new window

The Complete ApplicationModule Code

The following is the ApplicationModule.js code used in the video.

define('Mobile/Custom/ApplicationModule', [
    'Sage/Platform/Mobile/ApplicationModule'
], function () {
    return dojo.declare('Mobile.Custom.ApplicationModule', Sage.Platform.Mobile.ApplicationModule, {
        loadCustomizations: function () {
            this.inherited(arguments);

            // Add the NewField1 property into the SData query for the detail form
            
            dojo.extend(Mobile.SalesLogix.Views.Account.Detail, {
                querySelect: Mobile.SalesLogix.Views.Account.Detail.prototype.querySelect.concat([
                    'NewField1'
                ])
            });

            // Add the NewField1 property onto the Account Detail form
            this.registerCustomization('detail', 'account_detail', {
                at: function (row) { return row.name == 'LeadSource.Description'; },
                type: 'insert',
                where: 'after',
                value: {
                    name: 'NewField1',
                    property: 'NewField1',
                    label: 'new field 1'
                }
            });
            
            // Add the NewField1 into the SData query for the edit form
            dojo.extend(Mobile.SalesLogix.Views.Account.Edit, {
                querySelect: Mobile.SalesLogix.Views.Account.Edit.prototype.querySelect.concat([
                    'NewField1'
                ])
            });


            // Add the NewField1 property onto the Account Edit form
            this.registerCustomization('edit', 'account_edit', {
                at: function (row) { return row.name == 'LeadSource'; },
                type: 'insert',
                where: 'after',
                value: {
                    name: 'NewField1',
                    property: 'NewField1',
                    label: 'new field 1',
                    type: 'text'
                }
            });


        }
    });
});

Next time we'll look at how to add this customization back into Application Architect, deploy to the production mobile site, and even how to bundle the customizations.

Setting up a SalesLogix Mobile Development Environment

Ryan Farley — Tue, 02 Apr 2013 15:00:00 GMT

One of the first steps to doing customizations for the SalesLogix Mobile product is to set up a development environment. This task can be confusing for those just starting out with mobile, but with the help of the SalesLogix Mobile Developer Toolkit this is made much simpler. Even better, this article includes a video to walk you through the process.

Background

Before you can customize the SalesLogix Mobile product, you need to be able to set up a development environment. The following video will walk you through the entire process using the SalesLogix Mobile Developer Toolkit.

Watch Setting up a SalesLogix Mobile Development Environment on YouTube
The video will open on youtube.com in a new window

Download the SalesLogix Mobile Developer Toolkit

Stay tuned for the next video that will take you through the next steps in customizing the SalesLogix Mobile product by adding custom fields to screens. Until next time :)

Free Tool to Retrieve SalesLogix User Names and Passwords

Ryan Farley — Mon, 25 Feb 2013 21:51:00 GMT

As a business partner we work with customer SalesLogix databases often. Along with getting a database backup we need to ask the customer what their SalesLogix admin user password is, as well as any other user passwords needed for testing. I tend to think I'll remember these passwords and don't write them down, but then end up forgetting them later. Step in the SalesLogix User Logins tool. This open source tool from Customer FX will retrieve all SalesLogix user login names and unencrypted passwords with a click of a button.

The SalesLogix User Logins Tool

The SalesLogix User Login tool will connect to a SalesLogix SQL database using the SQL sysdba account and then list all SalesLogix users and decrypt their passwords as well. You can easily export this list as well for easy saving.

click for larger view

Source Code Available

The source for this tool is available on github. Feel free to grab the source, report any issues or give feedback. The tool does not have any other dependencies of any kind. You can just grab the source, open it in Visual Studio and run it.

View the SalesLogixUserLogins Source Repository

A Word of Warning

Obviously, a tool like this makes it possible for anyone to connect to your SalesLogix database and see all the passwords, right? Well, sort of. The tool still requires the SQL sysdba account password to connect to the database in the first place. If you leave the sysdba account password the standard "masterkey" then you're opening your data up to prying eyes with or without a tool like this. So, it's a good idea to not leave it the standard password. Always set a secure password for the sysdba account.

Download the SalesLogix User Logins Tool

The SalesLogix User Logins tool is a single executable that does not have any dependencies. It does not need SalesLogix to be installed. Just download the exe and run it.

Download the SalesLogix User Logins Tool

As always, any feedback you'd like to provide is welcome.

Introducing the SalesLogix Mobile Developer Toolkit

Ryan Farley — Tue, 13 Nov 2012 22:29:00 GMT

I am very pleased to announce a new & free open source tool from Customer FX named the SalesLogix Mobile Developer Toolkit. This toolkit will make your life easier when working with the SalesLogix Mobile product and provide automation to some of the tedious tasks you have to complete before you actually get to start writing code. Let's take a look.

The SalesLogix Mobile Developer Toolkit

I always think a picture (video) is worth a bazillion words, so let's start with a video overview of the SalesLogix Mobile Developer Toolkit.

Watch the SalesLogix Mobile Developer Toolkit overview on YouTube
The video will open on youtube.com in a new window

In a nutshell, the SalesLogix Mobile Developer Toolkit provides you with the following at the moment:

Create a new mobile development environment with a couple of clicks (for either mobile 1.2 or mobile 2.0)
Create a new customization product & ApplicationModule for layering customizations (for either mobile 1.2 or mobile 2.0)
Launch a mobile development environment in a small webserver so no need to use or configure IIS
Launch a specific product (customization set) in the browser
View articles on SalesLogix Mobile development
Report bugs and feature requests for the SalesLogix Mobile Developer Toolkit

That's where it is at now. I would love some feature requests for things that you think would make this toolkit even better. If you have a suggestion for a feature or would like to report a bug, you can do so at the github home for the SalesLogix Mobile Developer Toolkit

Report bugs, feature requests, or contribute source code on github

So, how can you get this free tool? Read on.

Downloading the SalesLogix Mobile Developer Toolkit

To download the SalesLogix Mobile Developer Toolkit, visit the product page on customerfx.com.

Get the SalesLogix Mobile Developer Toolkit

Download it and take it for a spin. I'd love any feedback you might have on how to improve it.

Easily Increasing the Height of the Picklist Dropdown in SalesLogix Web

Ryan Farley — Thu, 22 Mar 2012 19:07:00 GMT

Something that has always frustrated me when using the SalesLogix Web client was how the picklist control only shows four items in the dropdown and you have to scroll up or down to see the rest. This works fine for lists with only a few items, but for bigger lists it is a huge pain. It wasn't until a coworker was asked by a customer that I gave it any thought about how to go about changing this. Luckily, it's a pretty easy change to make.

This change can be made for all picklist controls in the client with a simple CSS change. If you open the sage-styles.css file in Application Architect. Look in the CSS folder in the Support Files for the portal. Then just add the following:

.picklist-container .picklist-inner-container .picklist-items
{
    height:200px;
}

This change increases the height of the dropdown to 200 pixels. That changes the picklist dropdown from this:

to this:

Much better. Of course, you can play with that 200px value to get the default height to look & feel just right.

Passing Connection Information from SalesLogix Web to Another Website

Ryan Farley — Thu, 22 Dec 2011 17:44:00 GMT

When integrating another system, application, or website with SalesLogix there are many options. If you're need to make connections to the SalesLogix database via the provider using user credentials you either need to prompt the user for login (again) or you can pass the connection information along to the other system.

It's easy enough to get the connection information using the DataService in SalesLogix. However, you don't really want to pass around a complete connection string around, especially since it will have the user's username and password in it. However, you can get the user's authentication token and then pass that to another system. It can use that authentication token to get all the connection values and form a valid connection string. Let's take a look.

Retrieving the current user's Authentication Token

To retrieve the user's authentication token, you can use the AuthenticationProvider service.

var authService = ApplicationContext.Current.Services.Get<IAuthenticationProvider>();
string authToken = authService.AuthenticationToken;

The authentication token will look like a long string of letters and numbers. You can pass this to some other website so that website/webpage can log into SalesLogix as that same user without prompting the user for their username and password. Let's look at what to do with this authentication token.

Decrypting and Using the Authentication Token

Once the other website or webpage has the Authentication Token all you need to do is convert it back to a stream and then read out the values from it. Then you have everything you need to form a valid connection string to the SalesLogix database as the user whose authentication token you have.

// In this code the "authToken" variable holds the authentication token value
// passed from SalesLogix Web (see code above)

using (var stream = new MemoryStream(Convert.FromBase64String(authToken)))
{
    using (var reader = new StreamReader(stream))
    {
        string UserName = reader.ReadLine();
        string Password = reader.ReadLine();
        string UserId = reader.ReadLine();
        string Database = reader.ReadLine();
        string Alias = reader.ReadLine();
        string Server = reader.ReadLine();
        string ExtendedProperties = reader.ReadLine();
        string Provider = reader.ReadLine();
        string UserType = reader.ReadLine();

        string ConnectionString = string.Format(
                "Provider={5};Persist Security Info=True;Initial Catalog={1};Data Source={0};User ID={3};Password=\"{4}\";Extended Properties=\"{2}\"", 
                Server, Database, ExtendedProperties, UserName, Password, Provider
            );
    }
}

Pretty easy and the other external website or password didn't need to ask the user again for credentials or store a connection string locally.

Note if passing the Auth Token in a URL

If you are passing this authorization token from SalesLogix to another website or webpage via a parameter in the URL, you must encode the token otherwise any contained "+" chars will break the string (since that will be interpreted in the URL as a space).

On the SalesLogix side, encode the token using something like this:

authToken = System.Web.HttpUtility.UrlEncode(authToken);

Then, on the receiving side, grab the token from the URL and then decode is using something like this:

authToken = System.Web.HttpUtility.UrlDecode(authToken);

Then all will work fine and you can proceed to get the connection values from the token.

Including Nested Payloads with SData for SalesLogix

Ryan Farley — Thu, 01 Dec 2011 15:00:00 GMT

When you're developing an application or customization using SData for SalesLogix, the fewer trips you make to the server the better. Moving data back and forth across the wire will always be the biggest bottleneck in your code, so making use of embedded payloads will save you some trips by bringing all the data you're after back in one pass.

What Are Nested Payloads?

Before we get into things, what exactly are nested payloads? Maybe a better term might be "included" payloads. Either way, when you request an entity, or entities, via SData, some part of the entity might be missing, or incomplete. Why? Because of the way that relationships work in the entity model. For example, if you request an Account entity, the AccountManager is a relationship to the User entity. These relationship properties are not included by default in the Account entity unless you tell SData you want those too. If you include related entities, such as the AccountManager, when you get back the Account entity you'll have an nested payload inside the Account payload. So, no need to make another trip back to the server to get the AccountManager. One thing to keep in mind, including related entites will increase the size of the data coming back in the SData feed, this is why these are not included by default, so be sure only include them when you really need them.

Adding An Included Entity In An SData URL

I think it is important to know what the SData URL looks like when doing anything with the client library. I think it helps to understand what you're ultimately ending up with. It also helps to see what the data coming back looks like using your browser by using the URL. When you want to include related entities you simple add an "include" parameter to the query string. For example, consider this URL to get a specific account:

http://localhost:3333/sdata/slx/dynamic/-/accounts('AA2EK0013023')

Now, to include the AccountManager entity as an embedded payload, add to the URL as follows:

http://localhost:3333/sdata/slx/dynamic/-/accounts('AA2EK0013023')?Include=AccountManager

To include additional related entities, such as all Contact entities for the Account, add that as well:

http://localhost:3333/sdata/slx/dynamic/-/accounts('AA2EK0013023')?Include=AccountManager,Contacts

Now when the Account entity comes back it will include an nested payload for the AccountManager, but also a collection of payloads for each Contact related to the Account - all in one trip to the server.

Including Related Entities Using the C# Client Library

Now that you know what the URL with includes look like, let's take a look at how to write the code and how to use the nested payloads. We'll use the example above to get a single Account and include the AccountManager and all related Contacts for the Account as nested payloads.

using Sage.SData.Client.Atom;
using Sage.SData.Client.Core;
using Sage.SData.Client.Extensions;


//...


var service = new SDataService("http://localhost:3333/sdata/slx/dynamic/-/", "admin", "");

 
var req = new SDataSingleResourceRequest(service);
req.ResourceKind = "Accounts";
req.ResourceSelector = "'AA2EK0013023'";

 
// We have to include the entities we want returned as nested payloads
req.QueryValues.Add("include", "Contacts,AccountManager");

 
// We can access normal properties of the Account
var string accountName = payload.Values["AccountName"].ToString();

 
// Now get nested payload for AccountManager
var accMgrPayload = (SDataPayload)payload.Values["AccountManager"];
// We can access properties in the AccountManager payload
var accMgrUserName = accMgrPayload.Values["UserName"].ToString();

 
// Get nested Contacts collection of payloads
var contactsPayloadCollection = (SDataPayloadCollection)payload.Values["Contacts"];
// And iterate through each one
foreach (SDataPayload contactPayload in contactsPayloadCollection)
{
    // We can access properties in this Contact payload
    var contactLastName = contactPayload.Values["LastName"].ToString();
}

The key is to just access the property in the entity and cast it to either an SDataPayload or a SDataPayloadCollection. Cool beans.

Extending Sublogix Entities

Ryan Farley — Tue, 15 Nov 2011 16:22:00 GMT

If you've followed my posts on Sublogix, or even better, given Sublogix a spin, you'll know that if you're doing SalesLogix development Sublogix can save you a ton of time and give you a much easier to use data access and entity model. This post will show you how to extend the Sublogix entities to give you even easier access and save even more time.

The Sublogix Entity Model

Before we look at extending Sublogix entities, let's take a look at the standard generated Sublogix entities. The Sublogix library has a built-in entity model for the standard out of the box SalesLogix database. There are T4 templates you can add to your project to generate the entity model based on your own custom SalesLogix database schema. Either way, you have and entity class for each table in the database. If you've used teh T4 templates, you can find a file in your project called SublogixEntityObjects.cs which contains all of these classes and you can take a look. There's nothing special about these classes. The important part of these objects are the attributes they're decorated with that tells Sublogix how the classes and properties relate to the SalesLogix database tables and fields.

Extending A SubLogix Entity

Let's look at a sample of extending the Account entity. Let's add a property to get the related Contacts for the account. To do this, we simply need to inherit the Account entity as our base class, then add soem new custom properties.

First, let's create a new class, we'll call it AccountExtended. Then we'll have it inherit from account. At this point we have the following:

using System;
using System.Collections.Generic;
using Sublogix.Model;
using Sublogix.Entities;
 

namespace SublogixDemo.Entities
{
    public class AccountExtended : Sublogix.Entities.Account
    {
    }
}

There is one crucial thing missing from this class. The attributes that normally decorate a Sublogix entity. You can see these by looking at the Account class in the SublogixEntityObjects.cs file that was generated by the T4 templates. Once we add that our class will look like this:

using System;
using System.Collections.Generic;
using Sublogix.Model;
using Sublogix.Entities;
 

namespace SublogixDemo.Entities
{
    [EntityElement(Name="ACCOUNT", PrimaryKey="ACCOUNTID")]
    public class AccountExtended : Sublogix.Entities.Account
    {
    }
}

Now we can add whatever custom properties to the class we need. One thing to note, the base Account class has a built-in repository. So, to add the property to get the related child Contacts, we just need to add the following:

using System;
using System.Collections.Generic;
using Sublogix.Model;
using Sublogix.Entities;
 

namespace SublogixDemo.Entities
{
    [EntityElement(Name="ACCOUNT", PrimaryKey="ACCOUNTID")]
    public class AccountExtended : Sublogix.Entities.Account
    {
        public IList<Contact> Contacts
        {
            get
            {
                return this.Repository.Find<Contact>(x => x.AccountId == this.AccountId);
            }
        }
    }
}

Pretty simple. Now we could just use account.Contacts to get a list of the Contacts related to the account. Often, when I do this sort of thing, I store the retrieved items locally in a private variable to avoid going back to the database to retrieve them. For example, this sample extends the OpportunityProduct entity to provide the related Product entity built-in. The difference here is that I only retrieve it once, then store the reference so next time I ask for it I don't make a trip back to the database for it.

using System;
using Sublogix.Model;
using Sublogix.Entities;
 

namespace SublogixDemo.Entities
{
    [EntityElement(Name="OPPORTUNITY_PRODUCT", PrimaryKey="OPPPRODUCTID")]
    public class OpportunityProductExtended : Sublogix.Entities.OpportunityProduct
    {
        private Product _product;
        public Product Product
        {
            get
            {
                if (_product == null)
                    _product = this.Repository.GetById<Product>(this.ProductId);
                return _product;
            }
        }
    }
}

One of the cool things about doing this is that if you're binding the Sublogix entity to a datagrid, you can create properties for related items so you can easily bind as you normally would since the values from related tables are all built in. Also, it goes without saying that you can certainly do a lot more than just retrieving related entities. You could do any sort of calculations or complex things there too, of course. Here's one that extends the Opportunity entity to add a calculated property to get the total price of all related opportunity products.

using System;
using System.Linq;
using System.Linq.Expressions;
using Sublogix.Model;
using Sublogix.Entities;
 

namespace SublogixDemo.Entities
{
    [EntityElement(Name="OPPORTUNITY", PrimaryKey="OPPORTUNITYID")]
    public class OpportunityExtended : Sublogix.Entities.Opportunity
    {
        public double? OpportunityProductTotal
        {
            get
            {
                return this.Repository.Find<OpportunityProduct>(x => x.OpportunityId == this.OpportunityId).Sum(x => x.Price);
            }
        }
    }
}

The sky is the limit. If you need to add any writable properties, that is, a property with a "set" as well as a "get", you'll need to tell Sublogix to ignore that property, otherwise it will try to match that up with a SalesLogix database field with the same name. To tell Sublogix to ignore that property, simply add the EntityElement attribute with an Ignore flag.

[EntityElement(Ignore = true)]
public string MyCustomProperty { get; set; }

Using Extended Sublogix Entities

To use an extended Sublogix entity, you just replace the standard entity name with your extended one.

So, instead of doing this:

var accountList = repo.Find<Account>(x => x.AccountName.StartsWith('Ab'));

You just do this to use your extended entity (Notice the change from Account to AccountExtended):

var accountList = repo.Find<AccountExtended>(x => x.AccountName.StartsWith('Ab'));

Pretty easy. Are you drinking the Sublogix koolaid yet?

Creating SalesLogix .NET Extensions with the .NET Extensions Helper Library

Ryan Farley — Thu, 27 Oct 2011 16:00:00 GMT

A couple of weeks ago I announced the .NET Extensions Helper open source library. I figured it was time for a more complete walkthrough so this post will show a video of how to get the library and use it to embed a .NET UserControl on a SalesLogix account tab. Let's take a look.

Demonstration of the .NET Extensions Helper Library

In this video you'll see how to get the .NET Extensions Helper library and how to use it to embed a .NET UserControl in SalesLogix.

Watch the Creating SalesLogix .NET Extensions with the .NET Extensions Helper Library on YouTube
The video will open on youtube.com in a new window

Take It For A Whirl

So, there will be more coming in future posts about the .NET Extensions Helper library. I'll cover how to wire up callbacks to invoke VBScript methods in the SalesLogix plugin from your .NET Extension and creating dialogs as well. For now, give it a try and let me know what you think.

Want to see something cool? The SalesLogix Mobile client embedded in Outlook!

Ryan Farley — Fri, 21 Oct 2011 16:00:00 GMT

Imagine this. The full, awesome power of the SalesLogix Mobile client, embedded in Outlook that shows the matching contact from the context of the currently selected e-mail in Outlook. Pretty awesome thought, right? Well, it's an idea that I have in the works, and not all that far off.

Take a look. Be sure to click on the image to see it full size.

(Click to view full size)

So, what exactly are we looking at here? This is Chromium, the open source browser code behind Google Chrome, embedded in an Outlook addin. It hosts the SalesLogix Mobile client, in all it's HTML5 goodness, and then attempts to set context based on the currently selected e-mail. It uses SData to locate the matching contact for the selected e-mail address and then uses the matching ContactID value to *attempt* to set that context in the embedded mobile client. I say *attempt* because there are some issues with setting context to a specific record in the mobile client in the current builds.

What's left to get this to fully work? Well, there's a lot of things. The addin does a lot of injecting Javascript into the embedded client to get things to work the way I want/need it to. I'd rather not have to do that, since that is prone to possible issues, and get the mobile client to play nicely in this scenario. I have a modified version of the mobile client started that I am using for a lot of this even with the constant javascript injection in the client. It would be great to just have the mobile client work as is with this. Also, there's some small "quirky" issues with embedding Chromium in Outlook that I need to get worked out. Most of the work that has gone into this so far is getting Chromium to work in an Outlook addin and play nicely embedded in Outlook. Note, this is Chromium, not Google Chrome. You don't even need Google Chrome installed for this to work. Anyway, all this extra work using Chromium (which isn't really built to be embeddable in other apps) wouldn't be necessary if IE got it's act together with full support for HTML5. In time it might get there which could make this solution get a whole lot closer to working in a quicker time frame.

It goes without saying how highly flexible this would be. You can customize the mobile client and then your customizations would be available in Outlook as well, all in context to the currently selected e-mail.

As I mentioned, there is still a ton of work before this sees the light of day, but for now, I'm excited enough about this that I thought it was worth sharing a sneak peek.

Unit Testing SalesLogix .NET Extensions and Mocking the SlxApplication Object

Ryan Farley — Tue, 18 Oct 2011 17:00:00 GMT

One of the many great things about developing for the SalesLogix Windows client using .NET Extensions is that you are able to unit test your code. However, since .NET Extensions are passed references to the running instance of SalesLogix, it's important to be able to mock those objects so you can test properly. Best of all, this also allows you to fully test and debug within Visual Studio without the need to have SalesLogix even running.

Background

I posted before about how to debug a .NET Extension by connecting to the running instance of SalesLogix and being able to set break points in your code. That's great, but this also means you need to add your extension to SalesLogix, add code in SalesLogix to load the extension and so on. Being able to perform this same sort of testing inside of Visual Studio, taking SalesLogix out of the picture, let's you focus completely on your .NET code and what the .NET Extension is actually doing.

Mocking the SlxApplication, BasicFunctions, and Other SalesLogix COM Objects

So what exactly are mock objects? There are plenty of resources online so I won't get too deep into mocking in this post. In a nutshell, a mock object is a "fake" object meant to be used in place of some other object for testing. In the case of SalesLogix, your .NET Extension receives a COM reference to SlxApplication where it can get things like a connection string or use things in BasicFunctions, etc. What we are going to do is create a mock, or fake, SlxApplication object that provides the limited functionality we'll be using in our .NET Extension. Then when we test we'll use that mock object instead. We will give it to our .NET Extension rather than SalesLogix passing it into our extension. To accomplish this we'll use the awesome Moq mocking library. Also, to point out, I will assume use of MSTest (even though I prefer XUnit).

First create a test project and add a test class. We will create our mock objects in the class initialize and then use them in separate test methods.

[TestClass]
public class ExtensionTests
{
    ISlxApplication _slxApplication;

    [ClassInitialize]
    public static void ClassInitialize(TestContext testContext)
    {
        // Create the mock SlxApplication object
        var slxApplication = new Mock<ISlxApplication>();
        // Set the connection string you want to use for your testing
        slxApplication.Setup(x => x.ConnectionString).Returns(TestConstants.SlxDbConnectionString);
        

        // Create the BasicFunctions mock object
        var basicFunctions = new Mock<IBasicFunctions>();
        // Set the userid you want to use as current user for your testing
        basicFunctions.Setup(x => x.CurrentUserID()).Returns(TestConstants.UserId);
        slxApplication.Setup(x => x.BasicFunctions).Returns(basicFunctions.Object);
        

        _slxApplication = slxApplication.Object;
    }
}

Now you have a mock SlxApplication object you can use and pass to your .NET Extensions. The way we set it up you'll have the following available.

SlxApplication.ConnectionString
SlxApplication.BasicFunctions.CurrentUserID()

You could of course wire up more items if your extension used them.

Using the Mock Objects and Running Your .NET Extensions from Visual Studio

One of the best parts of setting up these mock objects (aside from the fact that you can create unit tests that won't fail that reply on a running SalesLogix) is that you can now set up a test method to run your .NET Extension and use it from Visual Studio. What I like to do is create a test method that launches the extension and pass my mock objects to it.

If your .NET Extension is a form (meaning your form implements IRunnable), you can add the following test method.

[TestMethod]
public void RunExtensionForm()
{
    var extensionForm = new ExtensionForm();
    extensionForm.Initialize(_slxApplication, null);
    extensionForm.Run(new[] { TestConstants.AccountId });
}

Then, all you have to do is select that test method and click the "Run tests in current context" button in Visual Studio and your .NET Extension form will launch and it will have been passed the SlxApplication mock object and all will proceed as normal.

If your .NET Extension is a UserControl (meaning your UserControl implements IRunnable), you can add the UserControl to a test form (in the example below the form is called ExtensionTestForm) and then add the following test method.

[TestMethod]
public void RunExtensionUserControl()
{
    var extension = new ExtensionTestForm();
    extension.Initialize(_slxApplication, null);
    extension.Run(new[] { TestConstants.AccountId });
    extension.ShowDialog();
}

Same as before, select the method and use the "Run tests in current context" and the test form will open with your UserControl on it and will appear as though it were embedded in SalesLogix.

Wrapping It All Up

When all is said and done, I love being able to unit test my applications, but I have to admit, my favorite part is being able to simply run my .NET Extensions from Visual Studio without the need to add them to the .NET Extension Manager, do a full refresh in SalesLogix, and get to the area my extension loads on a record I can test with. Doing things this way gives you complete control.

And yes, all of this works with the NetExtensionsHelper library I posted about earlier without changes :-)

Announcing the Open-Source SalesLogix .NET Extensions Helper Library

Ryan Farley — Fri, 14 Oct 2011 00:20:00 GMT

If you're working in the SalesLogix Windows (LAN) client, why not make as most use as possible of a modern development environment, language, and tools? The SalesLogix .NET Extensions feature in the SalesLogix Windows client is one of the best, and likely least used, features in the SalesLogix Windows client development story. A choice bewteen using an out-dated development environment and VBScript, with no possibility of using source control or a true multi-developer experience verses using Visual Studio, with source control, a modern language and framework where the sky is the limit? I'll take the latter any day. Still not convinced? The .NET Extensions Helper library comes to the rescue. This new open source project from Customer FX will make embedding .NET controls in SalesLogix a breeze.

Overview & How To Use

The .NET Extension Helper is a library that will do all the heavy lifting to embed controls in SalesLogix. All you do is have your UserControl inherit from the FX.SalesLogix.NetExtensionsHelper.SalesLogixControl and then use a script class in SalesLogix to load the control and set the record context.

Let's consider a very simple example of a .NET Control on an Account tab. You want to display the current account's contacts in a grid on this tab. Your .NET UserControl code will look something like this:

public partial class UserControl1 : FX.SalesLogix.NetExtensionsHelper.SalesLogixControl
{
    private void UserControl1_SalesLogixRecordChanged(string RecordID)
    {
        using (OleDbConnection conn = new OleDbConnection(this.SlxApplication.ConnectionString))
        {
            conn.Open();
            using (OleDbDataAdapter da = new OleDbDataAdapter(string.Format("select lastname as LastName, firstname as FirstName, type as Type from contact where accountid = '{0}'", RecordID), conn))
            {
                DataTable table = new DataTable();
                da.Fill(table);
 
                dataGridView1.DataSource = table;
            }
        }
    }
}

So, what are we looking at here? Basically, there's extra code in that example that opens an ADO.NET connection to the SalesLogix database and gets a DataSet to bind to a DataGridView, but the important parts there is that the UserControl inherits from a special base class named "SalesLogixControl" and then wires up an event called SalesLogixRecordChanged which passes in the current record's ID value. Whenever the record changes in SalesLogix, this event is fired and you're passed the record ID. Simple.

The above is the .NET side of things. There's only two lines of code needed in SalesLogix to drive this. In the example we have above, the SalesLogix form (the actual form in SalesLogix hosting this control), would include the following code:

'Including Script - System:ExtensionControl Class
option explicit

Dim ext

Sub AXFormOpen(Sender)
    Set ext = new ExtensionControl
    ext.Load "SampleExtension", "SampleExtension.UserControl1", Form.HWND, True
End Sub

Sub AXFormChange(Sender)
    ext.CurrentID = Form.CurrentID
End Sub

The code above simply includes a VBScript plugin named "ExtensionControl Class". Then, in the form's Open event it creates an instance of the ExtensionControl class and then tells it which .NET Extension to load, and passes the Windows handle (HWND) of where to embed the control (in this case it passes the handle, or HWND of the form itself). The "True" at the end tells it to resize the control to fill all available space in that area. When the record changes, it passes that into the class which fires the event in your .NET UserControl. That is it.

What you'll end up with is this:

There are other things available as well which you can make use of, such as passing a Subroutine from your VBScript to the .NET UserControl as a callback function. I'll discuss more about that later.

One of the biggest benefits you'll have when using this, and .NET Extensions in general, is that you'll get to use Sublogix for all data access which will drastically speed up development time. I've been working with a customer where we've been building out their SalesLogix Windows client using exclusively .NET Extensions and this library with Sublogix and it's actually been enjoyable to work with. I've not been this happy working in the Windows client, well, ever.

Where Can You Get It?

All code for this is on github as an open source project. You can grab the .NET assembly and associated SalesLogix bundle from there and start rolling. I'll try to put together a sample video of how to go from download to first use next week.

Visit the NETExtensionHelper home on github
Grab everything you need, the assembly, the SalesLogix bundle, and a sample project from the Downloads section.

Best Of All, It's Open Source

As I mentioned above, this is an open source project. If you're using .NET Extensions and have some good ideas to add, I'd love to see some contributions. Just clone the repository, make some changes and then submit a pull request.

Changes in Sublogix Version 1.2

Ryan Farley — Wed, 24 Aug 2011 19:08:00 GMT

I've pushed version 1.2 of Sublogix to NuGet. There's some changes in how the custom entity templates are created by default. In previous versions of Sublogix, the custom entity templates used the display names for tables and fields in SalesLogix to create classes and properties. This caused several problems such as:

Localized/International versions of SalesLogix had many characters in the display names that would cause isseues when used as table & field names.
If a display name was changed (user's see these display names when building groups and several other places) then when the entities were generated again your properties would be different and you'd have to change code that references the old property name.

The new change in version 1.2 of Sublogix now uses the table & field names by default for the entity class names and properties. There is an option to use the display names still if you'd like in the entity template settings file. This means that the built in entites in Sublogix will be using table name and field names for the entities rather than the display names as it used previously. So, if you're upgrading Sublogix in an existing project you'll need to do a one-time remapping of code from the old property names to the new ones where the display name was different than the field or table name. But at least you'll now be able to avoid changing code if someone needs to change a display name somewhere. If you'd like to avoid this you can either just not upgrade to 1.2 of Sublogix or upgrade and change the template settings file to continue to use display names for the entity names and properties.

Some Background on Entity Templates

Sublogix uses Visual Studio T4 templates to generate code for the entities based on what the schema includes in your SalesLogix database. Out of the box, Sublogix includes an enity model based on the standard SalesLogix blank database. You can drop the templates into Visual Studio, modify the connection properties in the template settings file and then Visual Studio will transform the templates into an actual C# code file by connecting to your SalesLogix database and analyzing the tables & fields and then emitting the code for those tables & fields. When you use Sublogix, if all you need to do is work with the standard out of the box SalesLogix tables, you don't need to use the templates at all - you can just use the entity model built into Sublogix. If you need to work with anything custom, such as custom fields to out of the box tables or completely custom tables, then you can use the entity templates to generate your entity model based on your database schema.

Field and table names will still be pascal cased and dashes and underscores removed for the entity names & properties. MYFIELDNAME will end up being Myfieldname and MY_FIELD_NAME will end up being MyFieldName. There's a few other special circumstances, such as if the field name is the same as the table name, for those the value "Name" will be appended to the end. For example, the ACCOUNT field on the ACCOUNT table will end up being AccountName (you can't have a property the same name as the class it's in). Also, it looks for ending "ID" and makes that "Id" and the built in CREATEDATE/USER & MODIFYDATE/USER will be properly cased. Using the field & tables names don't end up as pretty, but it will be easier to work with going forward and less prone to errors and code changes.

Getting Sublogix

Sublogix continues to be distributed via the NuGet packaging system only. To date it's had 240 downloads from NuGet since they started tracking downloads, that number doesn't include any downloads before they started keeping track of that which was several versions into NuGet. How is this working? Would a non-NuGet option be worthwhile? If I were to make the Sublogix source code publically available on github would anyone be interested in contributing? There is much work to be done in the expression trees for using Linq expressions for the Repository.Find overload (it is currently pretty limited in the kinds of expressisons it can handle). Thoughts? Feedback?

Writing Queries for the SalesLogix SData API

Ryan Farley — Tue, 31 May 2011 17:12:00 GMT

In this fourth post in the SalesLogix SData series, I will introduce how to write queries for SalesLogix SData and will point to a useful resource as you get started, or more comfortable with SData.

SData Query Language

Be sure to first take a look at my last post which covers how to retrieve data via the SData API. The ability to read data from SalesLogix via the SData API is only useful if you know how to control it. Reading all records from a table isn't exactly useful. Knowing how to control which records you're retrieving is a must. Fortunately, that is easy, but it does take some knowledge of the SData Query Language.

SData uses a language refered to as SData Query Lanaguage. So, what does this mean to you, another thing to learn? Not really. The syntax for the language is simple and easily guessable. If you know how to write NHibernate queries then this won't look much different. As a matter of fact, if you know how to write SQL queries, this won't really look much different.

Example Query Conditions

Before we get too deep into things, let's take a look at some sample query conditions using SData. As I showed in the previous post (Retrieving Data via SData), you can use these conditions by adding them to the QueryValues collection of the SDataResourceCollectionRequest for the "where" part of the query.

Retrieve all records created since 5/1/2011
"CreateDate ge @2011-01-05@"
Retrieve all account records whose Name starts with the letter A through L
"left(AccountName,1) between 'A' and 'L'"
Retrieve all SalesOrders whose State on it's associated BillingAddress is 'AZ'
"BillingAddress.State eq 'AZ'"
Retrieve all Accounts whose name contains the word Bank
"AccountName like '%bank%'"

You'll see something that looks familiar and understandable with all of those.

Query Conditions, Functions, & Operators

So what are all the possible things you can use in an SData query? Rather than list them all here, I will point to the official SData specification where it outlines the available functions and operators for SData.

SData Query Language on SData Core Specification

Retrieving Data via SData for SalesLogix

Ryan Farley — Fri, 27 May 2011 16:00:00 GMT

If you followed my last two posts, you'll know some basics of what SData is and how to get it to use in your projects. In this post, we will take this a step further and look at how to actually use it, starting with how to query data from SalesLogix.

Getting a list of Contacts

Let's start with a basic query. For this example, we will retrieve all contacts whose last name starts with 'Ab'. Take a look at the code (with comments to walk through each part)

using Sage.SData.Client.Core;
using Sage.SData.Client.Atom;
using Sage.SData.Client.Extensions;
//...
 

 

// All requests require an ISDataService which provides
// the service location and user authentication values
ISDataService svc = 
    new SDataService("http://localhost/sdata/slx/dynamic/-/", "lee", "");
 

// Now create the request, passing in the ISDataService we created 
// above
var req = new SDataResourceCollectionRequest(svc);
 

// Tell it which kind of resource we want to access, in this case 
// Contacts. Note, this needs to match the values on the SData tab
// of the entity in Application Architect
req.ResourceKind = "Contacts";


// This part is optional (without it we'd be getting ALL contacts). 
// This is our where clause, or condition of which contacts we want.
// In this example we want all contacts whose last name starts with
// the value 'Ab'. We need to use the exact property name as defined
// in the entity (case-sensitive).
req.QueryValues.Add("where", "LastName like 'Ab%'");
 

// Now read the data (or run the query)
AtomFeed feed = req.Read();
 

// We now have the results in our AtomFeed variable, which is 
// basically a list of AtomEntry objects. To get to our data, 
// we need to read the payload from each AtomEntry and then we 
// can access the values for each field from it's Values 
// dictionary. In this example, we'll just write a few fields 
// from each contact to the console.
foreach (AtomEntry entry in feed.Entries)
{ 
    // Get the payload for this entity
    SDataPayload payload = entry.GetSDataPayload();
     

    // Now read some values from the payload. Note, the 
    // property names you use here need to match the property 
    // names defined for the entity (these are case-sensitive).
    string account = payload.Values["AccountName"].ToString();
    string contactName = payload.Values["NameLF"].ToString();
    string title = payload.Values["Title"].ToString();
     

    Console.WriteLine("{0}, {1} from {2}", contactName, account, title);
}

That's not too bad. You do have to access the fields by string name, which means you don't get intellisense, but at least it's easy code to write. There are ways to retrieve the schema for an entity which I will look at in a future post.

Getting Started with SData for SalesLogix - Installing the SData Client Library

Ryan Farley — Tue, 17 May 2011 16:00:00 GMT

In my previous post, an Overview of SData, I outlined the working parts and anatomy of the web enabled API for SalesLogix known as SData. In this post I will show you how to take your first step with how to get the SData Client Library.

Getting the SData Client Library?

As I mentioned in my previous post, the best route to take when using SData is to use the SData Client Library. While it is possible to parse the payload XML in an SData feed, using the client library will make this a very easy task. There are a few places to get the SData Client Library, however, the best and easiest place is from the NuGet packaging system. NuGet is a packaging system that you can install as an extension in Visual Studio 2010. You can get NuGet from the Microsoft Extension Library here. Once it is installed in Visual Studio, you can easily add libraries to projects - including the SData Client Library.

With NuGet installed, you can right click on the References folder of your project and select "Add Library Package Reference"

The NuGet dialog will open and you can search for SData and you'll find the SData Client Library.

Click for larger image

When you find it, click the "Install" button and it will be downloaded and added to your current project. Some of the other ways you can get the client library is direct from it's github repository. Stay tuned next time when I'll show you how to use the client library and easily work with SData.

An Overview of SData - The SalesLogix Web Enabled API

Ryan Farley — Mon, 28 Mar 2011 19:56:00 GMT

Chances are, if you work or use SalesLogix (or any Sage product) you've heard of SData by now. SData is a basically a web enabled API for SalesLogix allowing you to interact with SalesLogix data from an external application or website. The great thing about SData is that it is a specification that is implemented via RESTful web services. This means you're not limited to using SData with a particular technology (such as exclusively via .NET). In a nutshell, SData works via sending and receiving XML payloads via a URL. Pretty simple. This article will take a high-level overview of SData as an introduction (which means there will be several more in-depth posts on the way).

SData Versions

We started to see parts of SData as early as SalesLogix 7.5 and even more in 7.5.1. While these versions did work, SData wasn't exactly considered fully-baked until SalesLogix 7.5.2 (and even more functionality added in 7.5.3 such as picklist support). Needless to say, there were significant changes in 7.5.2 from it's earlier beta versions in 7.5.1 and prior. These changes were breaking changes, so if you're on 7.5 or 7.5.1 what I will be outlining here won't fit completely. The URL structure will be different and the way the payload is deilivered is quite different (but you'll still get the general ideas from this article, just bear in mind you'll have these changes to deal with).

The SData Server

The SData server is deployed from the Application Architect as a web portal. However, I do want to point out that using SData does not mean you have to be using the SalesLogix Web client. You can be an all LAN implementation and still deploy an SData portal. You only need to be on a version that includes support for SData. The SData deployment will create an "sdata" application in the deployment location (so you will have this next to your typical "slxclient" folder if you have a SalesLogix Web deployment). If you have a SalesLogix Web deployment then also deploying SData can be simpler since SData also uses the same entity model.

The Anatomy of an SData URL

Using SData comes down to an XML payload exchange via a URL. Knowing how these URLs are formed is important, and luckily, they are pretty easy to understand. A sample SData URL to access a list of Accounts would look like this:

Let's break down what all those values mean:

server & port: These are the server address and port of your SalesLogix web deployment.
sdata: This is the deployment folder for the SData portal. As I mentioned earlier, the SData portal will reside as a folder named sdata next to your slxclient portal deployment.
slx: The application name. SData is a specification that is currently used by several Sage applications, not just SalesLogix.
dynamic: This is the contract name. I won't get too deep into this now and may address this in a future post, but an SData deployment can support several integration contracts. For now, just stick with dynamic.
-: This part of the URL defines the dataset to use. Stick with the hyphen "-" which means the default dataset (or that the application only supports a single dataset).
Accounts: This is a resource to access, more on this next.

SData Resources

A resource is the entity type or table that you wish to query (or add, modify, delete, etc). Not all entities or tables are exposed by default. You get to pick and choose which entities are exposed via SData in the Application Architect (open the entity and you'll see an SData tab ewhere you can specify whether the entity is exposed or not.

Sample SData URLs

Here's some useful sample SData URLs you can use to query SalesLogix data via your browser. This is a great way to test things. When you access one of these URLs in your browser you'll be promoted for your SalesLogix login credentials. One thing to keep in mind as you use these, normal SalesLogix security applies, so you'll only see records that the user you're logged in with can see.

The SData Client Library

If you're using .NET with SData, one of the more easy ways to work with it is using the SData Client Library developed by Sage. When using the SData Client Library you don't necessarily need to know how to structure the SData URLs, but that certainly does help. The source for this lirbary is available on github as well. I will definitely have more posts on this in the future including how to use, best ways to get this library and more.

Errors about "getcp" in Git Extensions for SalesLogix

Ryan Farley — Tue, 15 Mar 2011 20:40:00 GMT

Some of you have reported to me via Twitter that you've been experiencing errors mentioning "getcp" when using Git Extensions for SalesLogix.

The complete error message is something like this:

This error isn't occuring for everyone, but for those experiencing this, it pretty much makes Git Extensions for SalesLogix useless and inoperable. You'll be seeing the same error when using Git Extensions directly as well. This error comes from a problem with mSysGit, the Windows Git port. It comes with a command interpreter cmd file that uses the getcp.dll and it's not loading it like it should.

The Solution

The fix for this is easy. Basically, we'll be switching from using the Git command intepreter from the git.cmd to git.exe. Then both Git Extensions for SalesLogix and Git Extensions itself will work just fine and avoid the issue. You'll want to open the Git Extensions settings. You can get to this by going to the "Settings" menu in Git Extensions, or in Application Architect (with Git Extensions for SalesLogix installed) by going to the "Git Extensions" menu and selecting "Git Extensions Settings".

In the Settings dialog, on the "Git" tab you'll see an entry labeled "Command used to run git" at the top. The value there will currently either show "git.cmd" by itself or the full path to git.cmd. Click the Browse button to locate the git.exe which is located in the Bin folder of the Git installation directory (under Program Files). Mine looks like this:

You can close the settings and all should work now. Keep in mind there's no need to make this change if you're not currently experiencing this problem.

SalesLogix Group Explorer Updated

Ryan Farley — Wed, 16 Feb 2011 22:06:00 GMT

The SalesLogix Group Explorer has become a widely used tool for tracking down issues with SalesLogix groups, allowing you to see the group definition, conditions, layout, and underlying SQL for any SalesLogix group. Best of all it's a free tool. This tool has been updated to work on 64-bit computers as well as all versions of SalesLogix from version 7.2 up to the most recent version 7.5.3.

If you've not yet tried the SalesLogix Group Explorer, take a look at the screenshot below and you'll find a link to the download page after the image.

If you'd like to download the SalesLogix Group Explorer, visit the download page here:

Download the SalesLogix Group Explorer

Background Tasks for SalesLogix - A New Open Source Project from Customer FX

Ryan Farley — Mon, 06 Dec 2010 17:10:00 GMT

I'd like to introduce a new open source project from Customer FX that allows you to create and run background tasks in the SalesLogix Web platform. Background Tasks for SalesLogix provides a framework for you to use to build custom tasks that will run on an interval and perform some action in the background while the SalesLogix Web platform is running.

What Does Background Tasks for SalesLogix Do?

Background Tasks for SalesLogix has two parts. You get both parts by simply installing a bundle. The first part installs as a service in the SalesLogix Portal and provides the engine for running tasks. You create tasks for this engine by creating a DLL that inherits from a particular base class and then add your DLL to the Bin folder of the Support Files for the portal. You wire up and configure your DLL to be loaded by editing a config file provided by the Background Tasks for SalesLogix bundle. Once a user logs into the SalesLogix portal the service starts and begins executing your task on the interval you defined for it. The second part is a administrative console screen that you view inside the portal. This console allows you to see and monitor any background tasks and pause & start them as needed.

Background Tasks for SalesLogix Demo

The following video will give you the best visual picture of what Background Tasks for SalesLogix does and how to create your own custom background task.

Watch the Background Tasks for SalesLogix Demo on YouTube
The video will open on youtube.com in a new window

Download Background Tasks for SalesLogix

So, how do you get Background Tasks for SalesLogix? Visit the Background Tasks for SalesLogix home on Github. From there, you can click the Downloads button and download the SalesLogix bundle. That gives you everything you need.

Visit Background Tasks for SalesLogix on github
Download the current v1.0.1 SalesLogix bundle

Download it and take it for a spin. I'd love any feedback you might have on how to improve it.