Ep2: Integrating Services

Intro

[0:00] Hey folks, today we're going to continue to iterate on the project management app we started in episode one. We're going to continue by integrating our first service. We're going to connect the Slack API so that we can send notifications to a team channel whenever a user completes a task. Let's get started.

Creating a Slack Service

[0:24] Okay, I'm back in the Synthetiq desktop application. I have the app we were building from last episode open in the workspace. Again, we're building a project management app, and we want to add functionality so that when a team member completes a task, it sends a Slack notification to a shared channel. Now we're going to accomplish this by creating a service. A service in the Synthetiq ecosystem is essentially a reusable module that connects to a third-party API. To create our Slack service, we'll go create a new chat.

And then as a shortcut, we'll select Service Writer New Service. And we'll just tell it, create me a Slack service. From there, the agent will go research the Slack API, its documentation, and then respond with all of the different functionality it can build for that service. For the purpose of this demo, we only really need some simple functionality, like the ability to send messages to a team channel. So we'll just tell the agent that.

We only need a service that has this limited functionality.

[1:32] Great. The agent will go, compile, plan, and you can see here it shows us that it's just going to build connection to the API for sending messages and viewing channels. That looks good to us, so we can click accept and proceed. And just like in the app building process, the agent will then build the service for us.

[1:57] And then when it's done, it will tell us everything it's built. Great, looks like the service is ready. From here, we can navigate over to our services tab.

Connecting the Service

[2:09] And we'll see Slack in the list. We can click on it and we'll want to connect it so we can use it locally. Now, this is an OAuth service, so we'll have to go over to Slack and get some credentials. Now we're going to take a minute and do some work inside of Slack to set up that connection. This is going to vary greatly between what type of enterprise environment you are in. Sometimes there is an admin or an IT admin that has the administrative access into Slack. In that case, they will be able to provide you with these credentials.

In the case that you have access to Slack, you can go ahead and do it yourself. We're going to go through this flow, but feel free to skip this section as this is Slack specific setup. Okay, so to get our credentials, we can actually ask the service agent where we get these credentials. And it's going to give us a guide and give us a link inside of Slack to set up our OAuth application.

Setting Up the Slack App

[3:04] So we'll go ahead and we'll click on this link. It'll take us inside of our Slack dashboard and we'll click create new app and we'll just do a blank app. We can name it after our project.

And we'll be sure to select the workspace that we want our app to work in.

[3:24] Okay, now we're just gonna have to set up some configuration values. So we'll have to set up a redirect URL. This is the redirect URL we will set up for all services inside of Synthetiq. And then we'll need some permissions. So we'll need to be able to have the chat write permission and the channels read permission.

[3:44] As well as the group read permission. Now, again, the agent gave us all these instructions, so that's how we know what scopes our service needs. And then from there, Slack will give us some credentials, namely the client ID and secret, which we will copy and paste into our service in Synthetiq.

Authenticating and Testing the Service

[4:06] And now with our credentials added, we'll actually be able to go back to the connections tab and log in to authenticate the service. This will take us through Slack's OAuth flow so that we authenticate as our Slack user. And just like that, our service is connected. So now with our service connected in Synthetiq, we can have the service writer agent test out the service to make sure it's all wired up correctly. Great, looks like everything's working.

It does give us a note, one thing before we can use it, is Slack applications need to be added to the channels in Slack. So we'll go ahead and do that. So I've gone ahead and popped open Slack. I have a test channel I want to use. And I'm just going to add that project manager Slack application we just made into the channel.

Versioning the Service and Editing the App

[4:57] Now, services can be versioned just like apps, since they are independent and can be used across multiple apps. So we'll go ahead and push a version of this service as well. And just like apps, services can be shared so that other users can build other apps on top of these services. You can even share it with your entire organization to make available in your orgs app store, but more on that later. Okay, now that we have our Slack service set up, let's use it on our app. So we'll open our app and we'll click Edit App.

And then we'll tell the operator agent that we want to send a Slack message to a shared team channel whenever somebody on the team completes a task. And that we want team owners to be able to decide what channel that team's board should send Slack messages to. So just like before, the operator agent is going to do some research, it's going to look at the app, and then it's going to present a plan to us about that feature.

So plan looks good. We'll click accept and proceed. And again, just like before, the agent is now gonna go do the implementation. So we'll speed this up out of the interest of time.

Deploying and Configuring for Production

[6:07] And when it's done, it's going to tell us what it built. Great, looks like it did it. And so we'll go over and we'll refresh our app. And we'll notice that there is now a new menu option called settings. So we'll scroll down to that and click it. And we have the ability to set the Slack channel for this team. So we'll select our test channel, we'll click save, and now we can actually try completing a task and seeing if it sends the Slack message.

Okay, we've completed the task. Let's pop over to Slack. And there it is. Now just like before, we're going to save our changes by pushing a new version. You can see now that Slack is being bundled with our app. Very cool. Okay, it's been published. And just like in the previous video, we can then go to the deployments tab and deploy our new version of our app.

Great. Okay, now that our changes have been deployed, we'll open up our app on our production URL. And we'll go over and we'll open the admin panel. And inside the admin panel, we'll see a tab for services. And we should see our new service, Slack, inside the list. We'll go ahead and click into Slack and we'll see a lot of options for how we can configure our service in production, mainly using system credentials or having each user supply their own credentials.

So for this case, for this app in this example, we're going to leave it at system credentials. We will deep dive into all of the different ways you can configure services as the admin of an app in production. But we'll leave this as is. And what we'll wanna do is we'll just want to add our client ID and client secret, like we did before. And then we will also have a new redirect URI for our production app. And that URL is gonna depend on where we've deployed our app to. So we'll wanna select and copy that redirect URI that's provided here.

And paste that into our Slack admin dashboard. And then once we have everything entered, we can click the connect button. And again, that will take us through the OAuth flow, but this time providing the credentials to our production application. Great, looks like we're connected. So now we can go ahead and we can test this on our production app. So we'll click into my team, I'll click into settings.

Verifying in Production

[8:29] I'll see I can still see the channels I've authorized. I'll click save. And then just like when we're testing and development, we'll go ahead and we'll complete a task. And then we'll look on Slack. And there we go. There's our task sent to our Slack channel. And with that, you've been able to see how we can quickly integrate a third party API into our application. The Synthetiq platform handles all of the implementation details, plumbing the authentication and the credential management.

Now, moving forward, we will continue to add more services into our app as well as integrate them into more complex workflows. So until next time.