Connectors / Service / Slack

Slack

Slack

Slack is a cloud-based platform that brings all your collaboration and messaging tool needs together, for both individuals and companies.

Overview

Slack is a single tool for messaging and sharing components and files; where you can create channels, react to key events and potentially configure Slack specifically for your team’s unique needs or tech stack via the Slack API. Their directory has over 1500 integrable apps, and data protection expectations are key.

Authentication

Please bear in mind that your Tray.io-Slack authentication can be set up with various permission boundaries. With this in mind, the instructions given here are just one of many possible use cases and should be taken as a guideline, dependant on your particular project needs.

When using the Slack connector, the first thing you will need to do is make sure you are already logged into your chosen Slack account.

Once this is the case, select and drag the Slack connector to your workflow, and click on 'New Authentication' in the step editor:

You will be shown a pop up similar to what is displayed below. Name the connector as appropriate and bear in mind that there are several options pre-selected for you, and numerous permissions available to choose from.

Depending on your usage, you may not need all or any of these permissions. What is being given here is the most commonly requested/ used.

Make sure you select or un-tick as necessary. If you are unsure of your own needs, use the pre-selected settings for now. You can always create a new authentication later if need be:


After you have clicked 'Add authentication' you will get a secondary popup screen, where you will need to confirm your permissions settings:

Once complete, your Tray.io authentication option should be pre-populated with your completed auth:

Slack Trigger

If you wish your workflow to be kicked off by a particular action in Slack, you can use the Slack Trigger.

The Slack trigger allows you to receive notifications and trigger workflows when given events occur associated with the selected trigger operation.

Trigger Operations Available:

  • On action (button or menu click)
  • On Slack event
  • On slash command

Webhook Setup

When creating a new workflow choose Slack as your trigger at the 'Create new workflow' section and wait to be redirected to your new workflow.

Use the instructions above to authenticate your trigger, and select from the options available the event you want your trigger to listen to, in order to set off the workflow itself:

Available Operations

The examples below show one or two of the available connector operations in use.

Please see the Full Operations Reference at the end of this page for details on all available operations for this connector.

Example use cases

Due to the number of possibilities within Slack, we have created two use case scenarios for the purposes of this tutorial. A beginners and an advanced example as demonstrated below:

TRAY POTENTIAL: Tray.io is extremely flexible. By design there is no fixed way of working with it - you can pull whatever data you need from other services and work with it using our core and helper connectors. This demo which follows shows only one possible way of working with Tray.io and the Slack connector. Once you've finished working through this example please see our Introduction to working with data and jsonpaths page and Data Guide for more details.

For our beginner tutorial we will be demoing the 'Send message' operation as it is one of our most popular use cases. When a user joins a Slack channel, they will automatically have a welcome message displayed.

The advanced tutorial will involve using another connector plus additional Slack application setup. This is a complicated use case which has been built to show users how to set up Slash commands within a more likely usage scenario.

Example 1 : Beginner : Send message

In this example we imagaine a scenario whereupon whenever a new user joins a particular channel a welcome message will be displayed automatically. This is a good use case as it is a more public notification to the channel at large that a new "team member" has joined our group.

The steps will be as follows:

  • Set up the Slack trigger to react to a new user joining a channel.
  • Get the new user's details.
  • Respond with an automated message to the channel at large.

The completed workflows looks like this:

slack-completed-wf-beg

1 - Set up the Slack trigger

First go to your Tray.io dashboard, click on the 'Create new workflow' button in the top right corner and name your project workflow. Select Slack as your trigger.

Make sure you have your Slack authentication set up before continuing. Follow the tutorial above for more details.

Select your Slack authentication in your Settings -> 'Authentication' field.

Set your operation as 'On Slack event' and in your 'Event' input field, choose 'User joined a channel (public or private)'.

This setup means that once a user joins a new channel, it will literally trigger the workflow.

slack-trigger-beg

Make sure you clink on the green "Enable workflow" button in the bottom right hand corner. Once it turns red, it means your workflow is "listening" out for an event to trigger its processes.

2 - Get user name

Select the Slack connector from the connector panel on the left hand side of your workflow dashboard. Place it on the next step of your workflow. Select your Slack authentication.

Set your operation to 'Get user' and your 'User id' to the following: \$.steps.trigger.event.user. MAKE SURE your type selector is set to 'jsonpath' else your workflow will fail at this step.

The icon on the top right corner of your input field should change as a result of this selection change. See the image below for more details.

slack-get-user-beg

While the jasonpath given above is not immediately obvious, even when using the connector-snake, this is a path available which is made clear once output is generated/ your workflow is triggered.

Take a look in your debug panel for more details:

slack-get-user-output-beg

3 - Send message

Once more add a Slack connector to your workflow. Your operation this time will be set to 'Send Message'. Select your Slack authentication.

In your Channel input field, you should have an automated dropdown list of channels available as a result of the Slack domain you have setup with your authentication account. Choose an appropriate option for your workflow.

In the message section, we have an example of a written message that includes Tray.io's [Interpolation" src="/platform/standard-best-practices/managing-data/manipulating-data-part-2/).

INTERPOLATION: When you wish to include JSON generated data within another input/ output/ result, use our Interpolation method as described here.

This is a technique that can pull in data from our previous steps, and display the output accordingly. In this case, we have used it to get our message to display the new users name:

slack-send-msg-beg

As an added extra, we have also included a Slack icon to display with our message. You can get this by copying and pasting an icon from the Slack app itself, and dropping it in the 'Icon emoji' input field. Despite it appearing as an image when it is copied, the text version will display here (but don't worry, the icon will show as normal once generated as you can see below!):

slack-end-result
BEST PRACTICES: Whenever you do decide to create your own workflow, please make sure you take a look at our Managing data best practices guide.

Example 2 : Advanced : Slash command

this example will showcase the Slack trigger, Slack connector, and Airtable (a "spreadsheet-database hybrid" application) connector. This is so we can demonstrate a scenario that involves utilising Slack's rather special "On slash command" query.

You will need the following pre-requisites in order to complete the example below:
    - You will need an Airtable account

Airtable has a very simple sign on procedure not to mention automatically comes with prebuilt dummy data. Joining shouldn't take up more than a couple of minutes of your time.

    - You will need to have administrative permissions to a Slack application
IMPORTANT!: Having a Slack application is NOT the same as having a Slack account/ channel.
In order to proceed with this demo you will need to have a Slack app ready to test with. Building a test app from the Slack API Docs page is really simple, especially if you already have a Slack account. Please see Step 1.1 for more details.

The steps will be as follows:

  • Set up the Slack trigger using the Slack app verification token.
  • Use text helper connector in order to obtain your user's unique ID.
  • Using the Slack connector and ID, glean said user's email address from their Slack profile.
  • Cross compare your email results with Airtable's database records.
  • Send said user an automated slack message based on the outcome of the comparison.

The completed workflow looks like this:

slack-complete-flow

So lets begin!

1 - Setting up Slack

The first step is to go to your Tray.io dashboard, click on the 'Create new workflow' button in the top right corner and name your project workflow. This can be edited later if need be.

Select the Slack trigger itself, and choose your authentication as appropriate.

If you have not already completed Slack authentication setup, please go through the tutorial outlined above now.

You MUST have a Slack application in order to complete this tutorial. If you don't have one yet, follow setup 1.1 below. Otherwise please skip this step and move on to the Slack trigger setup outlined in 1.2.

1.1 - Slack app setup

Go to the Slack API site and click through the 'Start Building' button.q

slack-app-build

Name your app and choose the Slack account you wish to associate with this build (note that it is impossible to create and app without already having a Slack account):

slack-app-create

Once your new app is created it should display as follows:

slack-demo-apps

1.2 - Slack trigger setup

With your Slack trigger highlighted in your workflow, you will see input options now available in the Properties Panel on the right hand side.

The slash command requires a signing secret, you will need to be logged into your Slack account / application. Head to the main documentation site and select the "Your apps" button in the top right hand corner.

slack-your-apps

Once here, you will see your apps available. Click through the relevant application and you will redirected to the 'Basic Information' page.

Scroll down until you see a section named 'App Credentials'. Within the subheading 'Signing secret' you will see a randomized security password.

slack-credentials-signing-secret

Copy this information and paste it into the 'Slash command signing secret' text box in a new slack authentication.

slack-signing-secret-box

While the the 'Response message' is optional your workflow is best served by having it populated. Use the below example for how your input should look once all of the above has been completed.

slack-trigger-all-inputs

1.3 - Slack Slash setup

Now that you have your trigger initialised, go the icon in the top left hand corner of your dashboard and click through.

slack-get-url1

Here you will come to your workflow settings. Within this area copy the 'Public workflow URL'. We will need this at a later step so keep it safe for now.

slack-get-url2

Head back to your Slack basic information page (where we got our validation token from earlier). Click on 'Add feature and functionality' and within the new dropdown space select the 'Slash commands' box:

slack-add-slash

Click on 'Add New Command':

slack-new-slash

You will find yourself on a page called 'Create new command' as displayed below.

slack-create-slash

Paste your public URL you saved from earlier into the 'Request URl' input. In regards to the rest make sure you specify the name of your command, and have the 'Escape channels...' option ticked (else your output will not be as expected within your workflow).

slack-slash-info-complete

This will now mean that your Slack Slash command will be registered on the Slack application side of things so to speak, and will be able to work in conjunction with your Tray.io workflow.

2 - Using the text helper connector

Add the 'Text helper' connector from the connectors panel to your workflow.

Make sure the helper is highlighted and within the properties panel you will see your input options once more.

As you can see, due to the nature of this connector you wont need any authentication setup.

For more details on what Helpers can do please see their main page.

There are three required fields. Since we are utilising the Slack slash command, we will need to have some text to provoke our trigger into action.

slack-text-input

The best way to populate this text field is to either hard-code it to look for a certain word or phrase, or better yet, have the Slack trigger react to an automated jasonpath. This is usually much better for your project long term generally speaking, and can be done using the drag and click connector-snake method outlined below:

JSONPATHS: For more information on what jsonpaths are and how to use jsonpaths with Tray.io, please see our Intro page and Data Guide for more details.
CONNECTOR-SNAKE: The simplest and easiest way to generate your jsonpaths is to use our feature called the Connector-snake. Please see the main page for more details.

Fill in the other fields as per your preference. In our example we have chose to use '@' and '|'.

You must make sure that your type-selector is set to string, aka displaying the A symbol (whereas your previous input will be displaying the jasonpath icon if you used the connector-snake).

slack-type-selector
Just to be clear, the reason we need to get the user ID is so that we can make our slash command user specific. The `user_id` that is generated in the output of the trigger is the ID of the REQUESTER (the one who wrote the Slash command), and NOT the ID of the user who's details we need.

3 - Get email addresses

The next stage involves using the user ID we gleamed from the previous step, in order to get said user's specific email address.

Add a Slack connector to your workflow and select the operation 'Get user' from the dropdown options. For your input, use the connector-snake once more to input the following: \$.steps.text-helpers-1.result.

slack-get-email

This stage basically takes the results from the previous step (our user's ID) and proceeds to utilise that as a way to locate said user's, Slack account's associated email address.

Now that we have one comparable available (the Slack email address), we need the Airtable email address to cross reference.

The next stage uses the Airtable connector. Assuming you have already signed in to your Airtable account and set up a Tray.io-Airtable authentication for it, please move on the to following.

If not, go to the Airtable service connector page for instructions on how to do so before moving on (this should only take a moment of your time).

Drag and drop the Airtable connector to the next stage of your workflow. In the properties panel select the 'List records' operation.

You will now need two properties: your Base and your Table IDs.

Find your Base ID by first making sure you are already logged into your Airtable account. Then go to the Airtable API page. Here you will see a list of your available workspaces and the projects associated with them.

Click through the relevant project:

slack-airtable-api-dashboard

You will come to an autogenerated API documentation page. In the first section ('INTRODUCTION') your Base ID will be listed.

You can also recognise your Base ID as the sequence that should start with appXXXXXXXX.

slack-airtable-baseID

In order to find your Table ID, simply open your project from your main dashboard page (NOT the API page - please see below).

slack-airtable-dashboard

In the URL you will see your Table ID as highlighted below.

You can also recognise your Table ID as the sequence that should start with tblXXXXXXXX.

slack-airtable-tableID

The final input is the Formula. Using the given Base and Table ID's to specify in which table to search for, this formula will (via the use of interpolation), cross compare if the Airtable email address found in said table, is the same as the email address found during our first Slack connector step, aka the Slack user email address: Work Email=\$.steps.slack-1.user.profile.email

We are essentially cross comparing if the Slack user has the same email address in their Slack profile as what is listed in the Airtable spreadsheet.

slack-airtable-search

4 - Boolean setup

Here we include a step called the 'Boolean connector'. This is part of the core connectors readily available, and gives us the option of two separate actions depending on the results of the previous step.

This is the main principal of the boolean condition as a whole. Using a comparison type, you specify what you are looking for and if true/ false, the workflow acts accordingly.

In our case, if the condition returns TRUE, an automated message will be sent in return to the enquirer stating that the individuals details were not found in the system.

Should the result return FALSE, the requested user details are automatically sent back to the enquirers channel.

Start by adding the Boolean condition to the next stage of your workflow. The default operation should be pre-filled with 'Boolean condition' but make sure to check.

In the properties panel under the input section you will find a section called 'Conditions'.

slack-boolean1

Set your first condition to: \$.steps.airtable-1.records[0].fields['Contact number'] and your second to null. Change your type selector to Null specifically for this.

Also set your 'Comparision type' to 'Equal to' and make sure that your Strictness is 'Satisfy ALL conditions'. The end result should be similar to this:

slack-boolean2

Having set the conditions up for your boolean, now we need to set the pending results. Drag and drop a Slack connector to each branch of your boolean.

4.1 - Success: FALSE branch

Sine we have our boolean set up in such a way as it means that should we find the table cell is NOT empty/ null, and is therefore populated; a false result is in fact a successful one.

In the FALSE branch, set your operation to 'Send Ephemeral Response'. This is an operation that will mean the response URL will only be visible to the user.

Write your response message as you see fit, you may wish to include [Tnterpolation as you did previously in order to produce an autogenerated message that can include your results as demonstrated here:

slack-false-branch

4.2 - Failure: TRUE branch

If our workflow finds nothing (aka null), then the response generated will state as such following the TRUE branch line.

Once again write your response message as you see fit, in order to produce an autogenerated message that can include at least your original query (the user name for said query for example) your results as demonstrated here:

slack-true-branch

End Result

As a result of the above setup, your positive outcome will look similar to the below, with your negative simply having the TRUE branch message instead of the contact number results displaying:

slack-result-slack
slack-result-output2
BEST PRACTICES: Whenever you do decide to create your own workflow, please make sure you take a look at our Managing data best practices guide.

All Operations

Latest version:

9.0