Slack and Simple K2 Integration

One of the big messaging apps for team collaboration is Slack and  is perfect platform to demo how to integrate K2 into it. This will be the first article on how we go about doing this.  Slack is free to use and so is great to demo with and it has an ever growing list of third party integration plugins to play with.

So before we start with the demo,what would we expect a K2 slack plugin to behave? I believe it behave in the following way.

  1. Send notifications of tasks that we have to actiontask
  2. Be notified of when task has been completed and what the action was or the workflow has moved to a certain stage or when there is a workflow escalation.
  3. To be able to action a task from inside Slackhomepage_example_hiretron
  4. To be ask Slack what are my outstanding tasks or what is the status of a certain workflow

So lets starts with points 1 and 2 and deal with simple notifications.

 

Building a Simple messaging app for Slack

Lets start with a simple example, where we can K2 notification messages to Slack, whether its a public message , message to a particular group or a message to an individual person.

First of all we need to sign up for Slack and create a team, which you can down from here . Now we have a slack team, we just need to here  to get access to API for Slack.

api_slack

We are starting simple, so click on “Incoming webhooks” and then click on the link ‘ incoming webhook integration

introwebhooks

Building the web hook url

  1. Choose the channel you want to send the messages to, don’t we will be able to override this later on.

introwebhooks12. Click on the green button ‘Add incoming Webhook integration’

3. You can how see your web hook url, copy that.

introwebhooks24. Further down you can also customize the actual message. I have opted for a K2 look.

introwebhooks35. Click on ‘Save’, we have now created are web hook for incoming messaging.

Slack endpoint assembly

Now we have the web hook, we can how write some code, so K2 can use it. We are going to use a endpoint assembly for this. So we are going to create a class that will take the endpoint and allow us to pass in a message, a optional username and optional group.

private static void PostMessage(Payload payload)
 {
 Encoding _encoding = new UTF8Encoding();
 Uri endpoint = new Uri("web hook here");

string payloadJson = JsonConvert.SerializeObject(payload);
 
 using (System.Net.WebClient client = new System.Net.WebClient())
 {
 System.Collections.Specialized.NameValueCollection data = 
new System.Collections.Specialized.NameValueCollection();
 data["payload"] = payloadJson;

var response = client.UploadValues(endpoint, "POST", data);

//The response text is usually "ok"
 string responseText = _encoding.GetString(response);
 }
 }

Simple code for posting a payload of information to the web hook url

public static void PostMessage(string text, string username = null, string channel = null)
 {
 Payload payload = new Payload()
 {
 Channel = channel,
 Username = username,
 Text = text
 };

PostMessage(payload);
 }

The actual public static method, we will be creating a SmartObject from and then using inside a workflow.

We can then build the solution and take the dll  and now tell K2 about it using the ‘Endpoint Assembly broker’. If you don’t know how to do that view my previous post on creating an Endpoint Assembly.

K2Service

Now just build a SmartObject that uses the service instance you just created.

Slack SMO

We can test it in the SmartObject tester

smotester

When it executes we get this response in Slack

smoslack

No that the SmartObject has been created, we can now use this method inside a workflow

Workflow

I am just going to use a simple workflow for this, that has one task and two actions.

test-workflow

We just going to use a SmartObject event to call the Slack notification SmartObject to send a message to the destination user when a task is generated and then a message to the originator when the task is approved or rejected.

SlackSMOEVENT1

SlackSMOEVENT2.PNG

SlackSMOEVENT4

We do something similar for the approve and reject activities, except we put in the originator name and the message is that the task has been approved or rejected depending on the activity.

When we run the workflow the destination user gets this message in Slack

task

With a link to the task, when they action the task the originator will get this message

task1

Next time we will expand on this by making the notifications more advanced and by allowing the user to ask questions about K2.

The source code for this example can be downloaded from here

Using The New Rest Broker

Hooray, it’s finally here, after months and months of beta testing. In 4.7  we finally get to use REST Services, without having to write a load of code to wrap around the REST service and then access it via the Endpoint assembly broker.

It’s really easy to setup and start using REST Services.

K2 Endpoint REST Broker, uses Swagger to define the Service Objects and methods. Swagger is becoming the open standard for describing REST APIS

Getting access to a Swagger Editor

To get a swagger definition of a REST Service you need access to a Swagger editor that can see the REST Service

  1. http://editor.swagger.io/#/ – Online Swagger Editor , if the Rest Service is accessible to the outside world
  2. https://github.com/swagger-api/swagger.io/blob/wordpress/tools/swagger-editor.md  – You can download a copy of the editor to install on a server where the REST service is accessible

swagger

Creating a Swagger definition file

To create a Swagger definition file using the swagger editor (same for both online and local version) follow the following steps

  • Click on ‘File’
  • Click on ‘Import URL’

Swagger1.PNG

  • Enter in the URL
  • If it can’t find the URL, uncheck ‘Use CORS proxy’
  • Once it has found the REST Service , click on ‘Import’
  • If there are no errors, click on ‘File’
  • Click on ‘Download JSON’

swagger2

  •  Take the .JSON file and copy it to the K2 server
  • Create a folder on the C:\  called ‘Swagger’
  • Copy file into the folder
  • Open up the SmartObject Tester Tool
  • Expand ‘ServiceObject Explorer’
  • Right click on ‘Endpoints Rest’ and click on ‘Register Service Instance’
  • In the section ‘Descriptor Location’ enter in the full path of the Swagger file we copied into the Swagger folder

rest

  • Click on ‘Next’ and then click on ‘Add’
  • K2 will now go through the Swagger file and create service objects based on the definitions in the Swagger file
  • You can now create SmartObjects as normal

 

Using K2 Framework (K2F) with Swagger and the REST Broker

K2F provides support for managing the swagger definitions of the REST Broker. It will do this in two ways.

  1. There will be a Web API Handler that accepts Posts, the idea being that when the global registry changes it will post to the service with the new host address and application name. The service then goes into the library and finds the correct swagger definition and updates it with the new host address. It then exports the swagger definition file to the  swagger folder on the server and then updates K2 with the new definition. ToDo
  2. In the portal you can view all the swagger definitions, where new ones can be added and old ones can be edited. Once created in the library, this will then create Swagger JSON file on the K2 Server.

swaggerdefintionlib

Add  a new Swagger file

demoswagger

  1. Click on ‘Add Swagger Definition’
  2. Form loads up where you can enter in the definition name, host address and the definition it self
  3. Click on ‘Submit’
  4. This will save the swagger definition in the library and also create its corresponding JSON file on to the server.
  5. You will still need to create the instance manually using the service object tester tool

savedswagger