Clay Widgets: Sharing & Embedding Objects as Web Pages

Digital-Clay objects such as dashboards, lists, graphs, charts, analysis tables, document templates, etc as well as any document saved in Clay, may be shared with other users via a URL if Web ClayStation is installed.

To get a URL for these objects, either use the 'Share…' functionality when the object or query is open, and check the 'Get Web/Widget URL' option, or, you can get URLs for existing shared objects via the Document Repository using the 'Get Web/Widget URL' functionality in the list of repository items.

Note that the 'URL for Web ClayStation' ClayCentral setting must be set for this to work, which provides the base Web URL for the above document URLs.

This URL can be sent to other users (as long as they have access to Web ClayStation via their web browser), and, by default, they will be asked to login before they can open the query/item you sent them. Once they login they may open multiple Digital-Clay shared objects, and their login session will only time-out after a period of inactivity. For logging in the user automatically using the URL itself, see below.

These URLs can be sent via e-mail or any collaboration tool, or they can be embedded inside documents and web pages. So, for example, web sites and portals maymake use of these URLs just like any other URL:

• The developer can build a custom web homepage with links, buttons, tabs, toolbars or any custom HTML components that open and display Digital-Clay shared objects.
• Clay objects such as graphs may be embedded in an IFRAME or floating HTML elements.

These embedded Clay widgets can be combined with REST API or Data Injection for entering data into Digital-Clay, thus allowing customers to build their own application or interfaces that combine easily-built native Clay objects (like dashboards) together with custom programming.

All of the objects mentioned above such as dashboards or lists may contain dynamic filters, which ask the user for filter values before running the query(s). You can programmatically fill these filter values instead having Clay ask the user, for any of the following reasons:

• You want to program your own filtering interface and enter the values that the user selected in your own GUI into the Digital-Clay objects as filter values.
• You want the filter values to change behind the scenes depending on which user is currently logged into your system, or based on what he is doing on the web site, or what page he is currently visiting.

To do this, set your filters as dynamic filters when sharing the object as usual, then append the 'uf' parameter to the shared URL. Example:

http://myhomepage.com/clay.dcw/?r=12&aid=2100025214&uf=87:27:0-0

The filter value syntax is as follows:

uf=LinkGroupID1:FieldID1:value1,value2,...;LinkGroupID2:FieldID2:value1,value2...;etc.

The LinkGroupID is mandatory per filter. You can look up Link Group IDs in the Custom Links tool in ClayStudio.

The FieldID is only needed if you are filtering on a specific field rather than the LinkGroup itself. Examples:

• “Customer” Link Group on its own is “17::”
• “Opportunity:Estimated Costs” is “87:27”

Filter values for Link Groups and Linked Fields must be internal record IDs, not name fields. These IDs can be viewed by adding them to Digital-Clay Custom Functions using the 'ID' field. This allows precise filtering even when there are duplicate names, but it can only work if you know the ID beforehand, or if you add a list of IDs into the user's interface. If this is inconvenient, or if you want to search simply based on the name of the record, then you must add the Name field for that record as the filter. For example, to filter based on the Creator' Last Name, use: “3:6:Smith” where '3' is the LinkGroupID for 'Creator', and '6' is the Last Name field ID.

Numeric, Currency and Percentage fields must be filtered using a range of “minimum-maximum”. If you want to filter based on a maximum value of 100, use 0-100. For only a minimum value, simply add a large value for the maximum value such as 100-999999. Example: To search for Opportunities with Estimated Costs of exactly $1000 or $2000, use “87:27:1000-1000,2000-2000”.

Duration fields must also be filtered using a range of minutes. E.g. for 2-3 hours, use “120-180”.

Date fields must also be filtered based on a numeric range, and should be in Unixtime format (number of seconds since 1-Jan-1970).

Text filters are by default filtered with the 'Contains' comparator. To use a different comparator, add the comparator prefix “@@” and a constant number, as follows:

• 0: Contains
• 1: =
• 2: >
• 3: <
• 4: > =
• 5: < =
• 6: IsContainedIn
• 7: Starts With
• 8: IsTheStartOf
• 9: Matches

For example, to search for all Customers with the exact name of IBM, use: “17:1:@@1IBM”.

Multiple filters are concatenated with a semi-colon (e.g. “uf=87:27:1000-1000,2000-2000;17:1:IBM”)

If you wish to use the separators ; , or : inside your filter values, escape them with a backslash (\) character.

The above URL parameter allows one to load a Digital-Clay list, graph, dashboard, etc with custom filter values as part of the URL. However, it is also very useful to be able to change the filter values of the embedded Clay web object via a web interface on-the-fly. Although the search box may reload the embedded Clay web object every time a new value is entered, the issue here is one of performance. I.e. ideally, we only want to refresh the displayed data with the new filter value without reloading the page every time. This can be done by calling the javascript refreshExternal() function on the embedded iframe, instead of reloading the whole page/iframe.

Here is a simple example that displays a search box, a button for applying the filter, and an embedded iframe containing the clay web object, in this case a list shared in the Repository with a dynamic filter on the “Name Keyword” built-in filter (43):

<INPUT ID="val" TYPE="Text"><INPUT TYPE="Button" Value="Filter" onclick="filt();"><BR>
<IFRAME ID="clay" SRC="" STYLE="width:100%;height:300px;"></IFRAME>
<SCRIPT>
var firstTime=true;
function filt(){
 var clay=document.getElementById("clay");
 var val=document.getElementById("val").value;
 if (firstTime) clay.src="http://myip.com/clay.dcw?r=12&aid=12345&uf=43::"+val;
 else clay.contentWindow.refreshExternal("43::"+val);
 firstTime=false;
}
</SCRIPT>

This basic code sets the URL of the iframe the first time the user searches for a name, and then calls the function with the new filter value on every subsequent search.

Note that this functionality does not work with Document Templates with dynamic filters. In this case the URL must be reloaded.

Normally, the user has to login to the system the first time they access any Web-ClayStation page. If this is the first time the user accesses the page, or if the user-session expired, then a Login page will display where they can enter a username and password, after which the original requested page will load.

But there is also an option to login the user automatically with a default username and password using the u/p parameters. (e.g. mysite.com/clay.dcw/?r=12&aid=2100025214&u=john&p=john123).

There is also an option to automatically login the user via a Role for pseudo-anonymous access. I.e. for the user there will be no login and the user will not exist in the system, but they login anyways by assigning a user from a pool of users given a specific role. This works as follows:

• A Role is selected or added to the system for anonymous web access (e.g. 'Web User')
• Users are added to the system with this Role. Since these users are anonymous and their names are not meaningful, their names should be something like User1, User2, etc. If a password is set, all users should have the same password.
• Note that each of these Users uses up a platform license just like any other User, except that this group of Users will be shared by many Web users. The amount of users you add with this role will determine how many anonymous users can make requests concurrently (not how many users can connect to the system, which is unlimited). If there aren't enough Users in the system versus the amount of concurrent anonymous users, their requests will be queued and there will be waiting times.
• Since these Users are shared, an anonymous Web User cannot set personalized settings such as Colors and messaging options without affecting all other users in this group. Similarly, record change history data and other such user tracking features will not be meaningful since many anonymous users will be sharing the same 'User'.
• Note that this is not the same as a Floating License. Multiple Floating Users each have their own User record and are only sharing a license, whereas this is a group of users sharing a User.
• These shared Users may use Floating Licenses as well though. All this means is that the amount of concurrent connected anonymous users will be limited by the amount of floating licenses in the system.
• The system will automatically assign or re-use connections for multiple users logging in using the same Role.
• Because many anonymous users will be sharing a single User and connection and the password will often be exposed to several people or even to the public, this is obviously not a secure method of login. So a password is almost useless and the Role should be as restricted as possible in terms of permissions.

To login anonymously using a Role, use role:RoleName as the username. (e.g. myhomepage.com/clay.dcw/?r=12&aid=2100025214&u=role:webuser).

Lists, graphs, charts, analysis tables and other components may all be opened by default in 'full-screen' mode, to force the content to take up the full size of the browser window without buttons and other components surrounding it. To do this, add fs=1 to the URL (e.g. myhomepage.com/clay.dcw/?r=12&aid=2100025214&fs=1).