User Guide

Hamilton VENUS Compatibility

✅ VENUS 6

• Tested on VENUS 6.2

✅ VENUS 4

• Tested on VENUS 4.5
  

Functions

Configuration

• Sets the name, icon and/or emoji for the Slack application when posting from the Liquid and Data Hamilton Slack Integration commands. This can be used to override the settings configured in slack.json, or the default image and name configured with the Slack application.

• i_strSlackIcon: Specify the url to a .png icon file that is square and 128x128px or smaller.

• i_strSlackEmoji: use the “:emoji":” syntax when specifying emoji. If selected, emoji will take priority over an icon

GetConversationMembers

• Retrieves the users added to the specified conversation. This can be useful to filter a particular user or users from a specific channel to be tagged during method execution.

GetConversations

• Retrieves the conversations available to the Slack application.

• Note: For large Slack instances, this function may return an unwieldy amount of conversations.

GetLastError

• Retrieves the last error encountered by the functions called in the Slack Integration library.

• If a function returns anything other than 0 (false), use this function to elucidate the error encountered.

GetUsers

• Retrieves the users available to the Slack application.

• Note: For large Slack instances, this function may return an unwieldy amount of users. In this case, use GetConversationMembers to retrieve a more targeted group of users for tagging or tracing purposes.

Initialize

• Initializes the Liquid and Data - Hamilton Slack Integration Library.

• i_strToken: Bot User OAuth token generated for your Slack application

• i_strLicenseKey: Activation key generated during sign up.

InitializeEx

• Use this function to initialize the Liquid and Data - Hamilton Slack Integration Library from a JSON configuration file.
  

PostMessage

• This function will post a message to the specified Slack conversation or user.

• PostMessage supports plain text, markdown, or Slack JSON block syntax.

• The Thread Ts returned by PostMessage can be used by PostMessageThreaded to implement threaded replies.

PostMessageThreaded

• This function will post a message as a reply to the specified Slack thread.

• PostMessageThreaded supports plain text, markdown, or Slack JSON block syntax.

Release

• This function releases the Slack object created in Initialize or InitializeEx. It’s good practice to release objects when they are no longer needed, at the completion of a method, or in the OnAbort handler.

SetSimulation

• This function sets the simulation more for the functions in the Slack integration library. If the simulation mode is set to 1 (true) the commands in the library will be simulated (i.e. messages will not actually post to Slack).

• SetSimulation is useful during method development to turn off the Slack integration until needed.

SetTraceLevel

• SetTraceLevel sets the verbosity of tracing from the Slack integration library. If troubleshooting, it is recommended to set the Trace Level to DEBUG for the most visibility on the behavior of commands and any errors encountered.

UploadFile

• This function uploads files to the specified Slack channel (recommended) or to the Slack file system.

• It is easier to search for, navigate to, and find files that are uploaded to a Slack Channel vs. ones that are merely uploaded by the Slack application to the file system.

• Most file types (i.e. trace files, .csvs, JSON) will be viewable inline in Slack

Test Methods

Slack - Quick Start.med

C:\Program Files (x86)\HAMILTON\Library\LiquidandData\Slack\Test\Slack - Quick Start.med

Configure this method with your Slack Application Token and your Liquid and Data Activation Key and you’re off and running. Three commands: 1. Initialize 2. PostMessage 3. Release, and you have a fully functional Hamilton <-> Slack integration.

The Slack - Quick Start method is the simplest way to test your integration. Throw in a GetLastError function after the Initialize or PostMessage commands to capture and troubleshoot any errors.

Dependencies

Liquid and Data

• Slack

Hamilton

• ASWStandard Libraries

  • ASWGlobal

  • TraceLevel

• HSLStrLib

Slack - Message Templates.med

C:\Program Files (x86)\HAMILTON\Library\LiquidandData\Slack\Test\Slack - Message Templates.med

The Slack - Message Templates.med method is a demonstration of all of the functionality of the SlackMessageTemplates.smt Sub-method Library.

Use the functions in the SlackMessagetemplates.smt out-of-the-box, or as examples to extend the .smt tailoring message templates for your methods.

We’re here to collaborate if you have suggestions or improvements or additions to the standard Method message templates (hello@liquidanddata.io).

Dependencies

Liquid and Data

• Environment

• Slack

• SlackMessageTemplates.smt

Hamilton

• ASWStandard Libraries

  • ASWGlobal

  • TraceLevel

• HSLStrLib

Slack thread generated by the Slack - Message Templates demonstration method.

Slack - Test Method.med

C:\Program Files (x86)\HAMILTON\Library\LiquidandData\Slack\Test\Slack - Test Method.med

The Slack - Test Method.med method is a catch-all method for testing library functionality. It’s the most comprehensive reference for implementation examples for each library function.

Dependencies

Liquid and Data

• Slack

Hamilton

• ASWStandard Libraries

  • ASWGlobal

  • TraceLevel

• HSLStrLib

Configuration with JSON

For simplicity of implementing the Liquid and Data Hamilton Slack Integration across multiple instruments and methods, the library supports configuration with a slack.json file.

Set the values for the token and license key and initialize the library using the InitializeEx function,.

C:\Program Files (x86)\HAMILTON\Library\LiquidandData\Slack\Bin\slack.json

{
  "token": "",
  "licensekey": "",
  "name": "Liquid and Data",
  "icon": "https://cdn.liquidanddata.io/icon-48x48.png",
  "emoji": ""
}

Send Method Updates with Message Templates

Message templates provide a sleek, coherent, powerful mechanism to bring relevant information into Slack during the execution of a Hamilton VENUS Method.

Message templates are enabled out-of-the-box with the SlackMessageTemplates Sub-method Library.

C:\Program Files (x86)\HAMILTON\Library\LiquidandData\Slack\Templates\SlackMessageTemplates.smt

Templates

• Method Start

• Method Progress

• Method Complete

• Method Abort

• Method Error

• Method Attachment

• Method Trace File

Method Message Template Examples

Run the Slack - Message Templates.med test method to see all of the various method message templates in action.

Handle Hamilton Hardware Errors

Hamilton VENUS error settings are configured in the System Configuration Editor and present an option for specifying an executable to run when default errors are triggered. These default errors are triggered on hardware errors - for example, when a wrong tip type is detected on pickup, or a liquid level wasn’t detected during LLD seeking.

These are the errors that are the most-difficult to anticipate and hardest to address with automated recovery - in other words, exactly the ones where reliable actionable real-time notifications are the most important.

With a dedicated executable the Liquid and Data Hamilton Slack Integration provides visibility by sending notifications during these unanticipated hardware errors to allow walk-away confidence - knowing you’ll get a Slack message when user-intervention is necessary.

Configure the slackexecutable.json file with a message to send relevant error information to users as hardware errors happen in real-time.

Customize your error messages sent from the Slack Executable with relevant information for your users and operations teams.

Customized Message Templates with the Slack Block Kit Builder

Slack facilitates rich custom messages with a JSON syntax with the Slack Block Kit Builder.

The PostMessage and PostThreadedMessage commands support messages that include JSON formatted blocks in addition to string containing plain text and markdown.

Supported Block Types

• header

• image

• section

• divider

• context

Not-yet Supported Block Types

• Rich text

  • Rich text is supported in both the section and context blocks, as well as in markdown formatted text passed in as a string to the PostMessage and PostThreadedMessage functions.

• Input

• Action

Link and File Unfurling

By default, files and links posted to Slack from the Liquid and Data Hamilton Slack Integration will be unfurled to present inline previews.

Note: an uploaded and linked trace file did not unfurl when the ® symbol was included in the Trace after pulling the instrument type: Microlab® STAR from the Windows registry. The ® made Slack treat the trace file as a binary file that could not be previewed.

Link unfurling example from message posted from Slack - Quick Start.med

Linked File unfurling example with .csv worklist

Slack API Rate Limits

Slack Web API requests are grouped into tiers with various rate limits.

Slack API Rate Limits

Each of the functions used in this library fall under Tier 3 (50+ per minute) or Tier 4 (100+ per minute) rate limits.

It’s feasible that with a large install base, rate limits may come into play. The Liquid and Data Hamilton Slack Integration implements measures to minimize non-message posting API calls (i.e. capturing Conversations and Users in memory preventing subsequent calls to endpoints with Tier 3 rate limits) that should alleviate rate limit concerns for a large majority of install bases.