DEV Community: Alan Lee

Using Twitter API and Reshuffle to manage Social Media Contests and Giveaways

Alan Lee — Fri, 19 Feb 2021 18:06:00 +0000

Social media contests and giveaways can be an incredibly powerful marketing strategy to jumpstart an online conversation about your business. When running one of these campaigns, you can ask your audience to like, follow or retweet as a way of growing your business’s engagement with the customers, which in turn, can lead to increasing the brand’s awareness. Hosting a promotional event gives the people who are not already following you the ability to learn about your business from seeing others engage with an entry. It’s a win-win situation, people have a chance at a free prize, and your brand increases in user engagement and awareness.

So, let’s say your marketing team came up with a great promotional campaign for Twitter and is asking the audience to retweet the post for a chance to win an amazing prize.

The next step is to figure out a way to choose a winner. Depending on how you ask users to enter, there are several ways you can pick winners for your giveaway. Many services are available online where you can copy and paste the campaign tweet URL and it’ll randomly choose a user. This approach will definitely work but may come with downsides. The most common, the service being limited to only driving one user action (retweets, replies, likes).

In this article, I will show you a way to manage a promotional campaign using the Twitter API and handling everything programmatically using Reshuffle. We'll be focusing on ‘retweets’ but you can easily customize the code to your needs with the many endpoints Twitter API has available.

Reshuffle is an open source, lightweight, and event-driven framework that helps you integrate services — these integrations and workflows are created inside a Reshuffle App. The objects that let you interact with these services are called connectors.

Prerequisites

In order to use the Twitter API, you will need a Twitter developer account - apply for access. Go to the app page and create a new Twitter app. When you have an app approved, save the API key and API secret as we will need it later on for configuration. To obtain the API keys check out the documentation.

This example will be using PostgreSQL to store the retweeters’ data. A table labeled ‘tweets’ with the columns of ‘id’ as the primary key and username will be needed. Have the database URL ready for configuration. If you prefer to store the data with a different service like Google Sheets, check the documentation here.

How to Build It

Our goal is to be able to fetch data from all the retweets posted on a specific tweet, and save the user’s screen name and tweet ID to the database. The data stored will count as an entry for the campaign. With the Twitter credentials on hand and a database created, we’re ready to move on to building this.

To get started, first we need to bring in the required packages. Then initiate a Reshuffle app and configure the Twitter, PostgreSQL and Cron connector. If you’re wondering, “Why or what is Cron?”, it’s the tool that will tie this application together, more explanation to come when we make use of it.

Note: If you are connecting to a database protected by ssl, you will need to include an ssl option in the pgsql configuration. Please see documentation for more information.

const { Reshuffle, CronConnector } = require("reshuffle");
const { TwitterConnector } = require("reshuffle-twitter-connector");
const { PgsqlConnector } = require("reshuffle-pgsql-connector");

const app = new Reshuffle();

//cron config
const cronConnector = new CronConnector(app);

//pgsql config
const pg = new PgsqlConnector(app, {
 url: process.env.POSTGRES_URL,
});

//twitter config
const twitter = new TwitterConnector(app, {
 customerKey: process.env.TWITTER_CUSTOMER_KEY,
 customerSecret: process.env.TWITTER_CUSTOMER_SECRET,
});

 // Code listed further down
 // will be inserted here


app.start(8000);

Reshuffle connectors provide events and actions that allow developers to easily build custom workflows and integrations. With the connectors configured, we can now make use of what they can offer.

To get the data on the retweeters, we will use the statuses/retweets/:id.json endpoint from the Twitter API. This is made easy with the Twitter connector GET action, simply pass on the endpoint as an argument along with the ID of the tweet you want to get the retweeters data on.

Tweet IDs can be found in the tweet url:

const retweeters = await twitter.GET("statuses/retweets/1349430236383825921.json");

Running the above line will return a collection similar to this:

With that, we’re now able to get a list of retweeters. However, there is an issue here. Twitter will only return a collection of up to 100 user retweets per call and does not have a way to paginate.

We can solve this by periodically calling the API and saving the results to the database. If you recall in the configuration, we also added the Cron connector, here we will make use of it.

As Reshuffle is an events-based system, you develop code to handle these events. The Cron connector can be used to fire an event every "x" amount of time, which lets us call the API
Periodically.

Note: I wrapped the twitter call in a function here to make code inside the event handler a little more neat

const usersRetweeted = () => {
 return Promise.resolve(
   twitter.GET("statuses/retweets/1350179812422258688.json")
 );
};

cronConnector.on({ expression: "25 * * * * *" }, async (event, app) => {
 const userList = await usersRetweeted();
 userList.forEach(async (tweet) => {
   await pg.query(
     `INSERT INTO retweets(id, username) VALUES ('${tweet.id}',   '${tweet.user.screen_name}')
      ON CONFLICT (id) DO NOTHING`
   );
 });
});

Note: If you’re unfamiliar with these cron expressions, visit crontab.guru to help generate one. The example above runs every 25minutes

After the API call, you can see we use the PostgreSQL connector to insert a new row with the retweeter’s data. With the id as the primary key, there won’t be any duplicate retweets saved into the database.

With this, we can run this for as long as the campaign duration. Afterwards, we use the PostgreSQL connector again to retrieve the number of entries so we can randomize and select the winner.

const pickWinner = async () => {
   const {
     rows: [{ count }],
   } = await pg.query("SELECT COUNT(*) FROM retweets");

   const randomNum = Math.random() * count - 1;

   const {
     rows: [{ username }],
   } = await pg.query(
     `SELECT USERNAME FROM retweets LIMIT 1 OFFSET ${Math.abs(randomNum)}`
   );
   return username;
 };
 console.log(await pickWinner());

You can customize this shuffle code to output multiple users, depending on how many winners your giveaway will have. Though you should probably comment out the code above until after the campaign has ended, or you can utilize the HTTP connector that lets you trigger logic when an HTTP endpoint is hit.

Like the other connectors, you will need to require it in the code and configure it like so:

const { Reshuffle, HttpConnector } = require("reshuffle");
 //http config
 const httpConnector = new HttpConnector(app);

Here is an example of how to use this:

httpConnector.on(
 {
   method: "GET",
   path: "/pick-winner",
 },
 async (event, app) => {
   const winner = await pickWinner();
   event.res.json({ winner });
 }
);

When the endpoint is hit, the output should look something like this:

With minimal code, I hope you can see how easy it is to set up and manage your campaign with the Twitter API combined with Reshuffle. Try different endpoints to create something unique that fits your giveaway!

Full Documentation of connectors:
Twitter Connector
PostgreSQL Connector
HTTP Connector
Cron Connector

Now, Make it Happen

As your developers and project management teams experience the ease of working with integrated applications, we encourage you to consider where else integrating workflows would benefit your teams. With so many different tools, the more you can consolidate them into one common interface, the easier people can get work done.

Reshuffle is continually listening to what our customers need and desire. Don’t see a Connector to a service you’d like to integrate? Send a tweet to @ReshuffleHQ to let us know which Connector you’d like us to develop next.

Sync Github Issues with Asana Board Tasks

Alan Lee — Mon, 25 Jan 2021 17:28:04 +0000

Github issues are a great way to keep track of enhancements, bugs and tasks for your project. It provides a forum like space for outside developers to give feedback. It’s a great tool for smaller teams to keep track of tasks but as your product grows, and more repositories are made, going back and forth between repositories for task management is just not ideal.

Most teams are using project management tools like Asana. But what about the bug tracking from the repositories? It would be quite bothersome to scroll through and find all ‘bug’ labeled issues and then add them onto an Asana board. Is there a way to synchronize Github issues to be automatically added as a task on Asana? Certainly, there are a number of solutions that can be found on the web.

Having one platform to track all project tasks and bug reports would create a much more efficient workflow for the entire team. In this article, we’ll see a bi-directional sync between Asana and Github. To keep things simple, any new issues created on Github with the label of ‘bug’ will automatically be added as a task on Asana, if the task is marked as complete on Asana, the issue will be closed on Github’s end. This will be a great starting point to show how easily customizable it is for you and your team's needs.

In this example, you will not only learn how to integrate these, but also see how you can customize the integration to fit your team’s workflow using Reshuffle.

Prerequisites

Before we jump in with the code, we’ll need to get credentials set up with Github and Asana.

Github:

Log in and generate a token here
Save the token somewhere, as you'll need it soon

Asana:

Log in and go here
Under Personal Access Token' > + New Access Token
Name the token and save the token somewhere, you’ll use it soon
You’ll need the workspace ID. To find this, go to the Asana Admin Console page and it will be in the URL:

How to Build It

To get started, first we need to bring in the required packages to build this example. Then initiate a Reshuffle app and configure the Github and Asana connectors with the credentials we saved earlier.

Note: To test this example locally, a tool like ngrok can be used to generate a url that exposes your localhost over SSL for Asana and Github Connectors as the baseUrl

const { Reshuffle, HttpConnector } = require("reshuffle");
const { AsanaConnector } = require("reshuffle-asana-connector");
const { GitHubConnector } = require("reshuffle-github-connectors");

 const app = new Reshuffle();

 //Github Config
 const githubConnector = new GitHubConnector(app, {
   token: process.env.GITHUB_TOKEN,
   runtimeBaseUrl: process.env.RUNTIME_BASE_URL,
 });
 // Asana config
 const asanaConnector = new AsanaConnector(app, {
   accessToken: process.env.ASANA_ACCESS_TOKEN,
   baseURL: process.env.RUNTIME_BASE_URL,
   workspaceId: process.env.ASANA_WORKSPACE_ID,
 });

 // Code listed further down
 // will be inserted here
app.start()

Reshuffle Connectors provide events and actions that allow developers to easily build custom workflows and integrations. With the connectors configured, we can now make use of what they can offer.

First up, we’ll build a one way sync from Github to Asana. As Reshuffle is an event-driven framework, we’ll need to define the event we want to listen to. In this case, from Github’s end, we will listen to the ‘issues’ event on a given repository.

// will see this action in play further down
const project = await asanaConnector
.sdk()
.projects.findById(process.env.ASANA_PROJECT_ID);

githubConnector.on(
 {
   owner: process.env.GITHUB_OWNER,
   repo: process.env.GITHUB_REPO,
   githubEvent: "issues",
 },
 async (event, app) => {
   // handler code will come here  
 }
);

Next, we will need to handle the event that has been triggered. When an issue is either ‘opened’ or ‘reopened’, we will first fetch all the tasks in Asana with the tag of ‘bug’, using the findByTag action provided by the Asana Connector - to prevent any duplicate tasks from being created, we’ll compare the names between the Github event title and the Asana task name.

Note: For simplicity, we are only going to compare the names to prevent duplicates, you and your team can handle this your own way to keep things more unique.

If there are no duplicate names, it will continue to create the new task on the Asana board using the createInWorkspace action. This action will need the workspace ID (found on the project object retrieved earlier from the Asana connector) and followed by the task data to be saved on the board.

Note: findByTag takes in an ID relating to certain tags in Asana, in this case, the tag passed in is the ‘bug’ tag.

const { data } = await asanaConnector
   .sdk()
   .tasks.findByTag("1199621513855890");

const foundTask = data.find((task) => {
 return event.issue.title === task.name;
});
if (["opened", "reopened"].includes(event.action) && event.issue.labels[0].name === "bug") {
 if (foundTask) {
   return;
 } else {
   const task = await asanaConnector
     .sdk()
     .tasks.createInWorkspace(project.workspace.gid, {
       name: event.issue.title,
       projects: process.env.ASANA_PROJECT_ID,
       tags: "1199621513855890",
     });
 }
}

Note: the key ‘projects’ in the task data determines which project you want this task to be placed in.

Similar to the event where an issue is opened, we can also decide what happens when the issue is closed. We can either mark it as complete or just delete it completely from the board. Here I am choosing to delete it. With the same strategy as before, find the matching task name, if it is found, we can simply delete the task using the ‘delete’ action.

if (event.action === "closed") {
 if (foundTask) {
   await asanaConnector.sdk().tasks.delete(foundTask.gid);
 }
}

With that, we can create and delete Asana tasks when opening / closing an issue on Github’s end. This is awesome, but the example wouldn’t bi-directional if I didn’t include how events are handled from Asana’s side.

Very similar to how we handle things with Github events, we’ll need to define an Asana event to listen to. In this case, to keep this example from going on too long, we’ll only handle the event when a task on Asana is marked ‘complete’.

asanaConnector.on(
 { gid: process.env.ASANA_PROJECT_ID, asanaEvent: "changed" },
 async (event, app) => {
   if (event.change.field === "completed_at") {
     //get the details for the completed task
     const taskDetails = await asanaConnector
       .sdk()
       .tasks.findById(event.resource.gid);
   //more handler code to come
   }
 }
);

When this event is triggered, we will need to grab the full details of the task that triggered the event using the findById action. Then we will check to see if this event has the same tag ID used in the Github event. If there’s a match it's safe to assume this task was created from Github, but to be sure, we will get the list of open issues and compare the names as we did before. If there’s a match on the name, we can update the issue to close it.

if (taskDetails.tags[0].gid === "1199621513855890") {
 const { data } = await githubConnector.sdk().issues.listForRepo({
   repo: process.env.GITHUB_REPO,
   owner: process.env.GITHUB_OWNER,
   state: "open",
 });
 const foundIssue = data.find((issue) => {
   return issue.title === taskDetails.name;
 });
 if (foundIssue) {
   await githubConnector.sdk().issues.update({
     repo: process.env.GITHUB_REPO,
     owner: process.env.GITHUB_OWNER,
     issue_number: foundIssue.number,
     state: "closed",
   });
 }
}

With that, we have completed a simple bi-directional sync between Asana and Github. If you are interested in developing this further to suit you or your team's needs, please check out the documentation for the connectors.

Full Documentation:

Now, Make it Happen

Track your SMS campaigns in Google Analytics with Reshuffle and Twilio

Alan Lee — Wed, 13 Jan 2021 18:02:40 +0000

Google Analytics is a powerful tool that provides valuable information about your website. It lets you know who your visitors are, what content they want to see, and how they behave when interacting with the application. Most of the time, this data is collected on the client, being that it's the browser, you’ll have easy access to user specific attributes. Client-side tracking is also very simple to configure, Google Analytics (GA from here on) provides a snippet of code that’s as easy as copying and pasting into the HTML to implement.

What if you or your marketing team wanted to track “offsite” events, like triggering an action while not interacting with the website or app? Let’s say you have an SMS marketing campaign powered by Twilio, and instead of using the new Messaging Insights in Twilio’s dashboard for analytics, your marketing team prefers GA. The solution for this is server-side tracking, rather than data collection from the web browser (client), events are collected on the backend server. This type of tracking is often seen as difficult to build but in this article, we’ll see how easy it is to send custom events directly to GA with Reshuffle.

How to Build It

We’ll continue with the SMS example to send data directly to GA anytime a Twilio number receives an incoming text message. You’ll notice two services at play here. Reshuffle makes it easy to build integration between services, so you can deliver unique experiences and outcomes for the business and customers.

To get started, we’ll need credentials from the services:

Tracking ID from GA:

Log in to Google Analytics Platform
Click on 'Admin' > 'Create a property'
Enter a property name
Click on 'Show Advanced Options'
Switch on 'Create a Universal Analytics property'
Select 'Create a Universal Analytics property only'
In Website URL, use your Reshuffle runtime URL
Click 'Next' then 'Create'
Copy your tracking ID (e.g. UA-XXXXXXXXX) as you will need it later in the configuration portion.

Twilio Credentials:

Create a free Twilio account
Copy the Account SID, Auth Token and generate a phone number as you will need it later in the configuration portion

Note: Please see instructions on how to test Twilio webhook locally. To set up the webhook, select phone number, scroll all the way down to messaging, add method and path, save.

See links for full documentation:

Let’s start coding. We'll need to require the packages for this example. Then initiate a Reshuffle app and configure Twilio and GA connectors with the credentials we got earlier.

const { Reshuffle, HttpConnector } = require("reshuffle");
const { TwilioConnector } = require("reshuffle-twilio-connector");
const { GoogleAnalyticsConnector } = require("reshuffle-google-connectors");

 const app = new Reshuffle();

 const twilioConnector = new TwilioConnector(app, {
   accountSid: process.env.TWILIO_ACCOUNT_SID,
   authToken: process.env.TWILIO_AUTH_TOKEN,
   twilioNumber: process.env.TWILIO_NUMBER,
 });

 const gaConnector = new GoogleAnalyticsConnector(app, {
   trackingId: process.env.GOOGLE_UA_TRACKING_ID,
 });

 // Code listed further down
 // will be inserted here

app.start()

As Reshuffle is an event-driven framework, we’ll need to define what event we need to listen to. In this case, with the Twilio connector, we can listen to incoming SMS on the Twilio number.
We are able to extract both the message and the phone number from the event. If you or your marketing team want to save this information, we can do that using another Reshuffle connector, but we’re here to send this event directly to GA. To do this, we use the GA connector action trackEvent.

Note: Parameters for trackEvent(category: string, action: string, label?: string, value?: string|number)

 twilioConnector.on({ method: "POST", path: "/sms" }, async (event, app) => {
   const messageReceived = event.req.body.Body;
   const fromPhoneNumber = event.req.body.From;
   console.log(`New SMS received from ${fromPhoneNumber}: ${messageReceived}`);

   await gaConnector.trackEvent(
     "SMS", //category
     "SMS Received", //action
     "user engagement" //label
   );
 });

And that's it! With minimal code you can send custom events directly to GA for your marketing team to review. If you try this out, your realtime GA dashboard would look something like this:

Now, Make it Happen

Programmatically Remind Your Teammates on Slack to Review GitHub PRs

Alan Lee — Thu, 17 Dec 2020 17:50:56 +0000

The Github integration for Slack is great for team productivity. Having the ability to give Slack channels full visibility into Github projects, for real-time notifications, is an amazing way to keep the development team on the same page. However, this can become a double-edged sword. Developers may decide to ignore these messages being sent because it may be information overload.

I’ve been in a similar situation where pull requests needed approval from reviewers but they wouldn’t check the channels or their emails. The only thing that got their attention were direct messages. This hindered delivery and having to ping the reviewer myself was becoming a pain.

As great as the Github app for Slack is, I wanted something more custom that would suit my needs. For example, whenever a pull request is made with reviewers, only send direct messages to those who have been requested.

In this article, we will use Github, Slack, and Reshuffle to create the workflow to directly message the reviewers on a pull request.

How to Build It

Before getting started with the code, we’ll need to get credentials set up with Github and Slack.

Github

Log in and generate a token here
Save the token somewhere, as you''ll need it soon

Slack

Create a new Slack App here
Enter the App name and select the workspace
Click on Create App
Click on your new App
The signing secret is under Basic Information > App Credentials
The token is under Settings > Install App > OAuth Access Token
Save the token and signing secret somewhere, as you''ll need it soon

See links for full documentation:

With the credentials saved somewhere safe, we can begin by instantiating a Reshuffle app and configuring the connectors.

Note: The Github Connector requires a runTimeBaseUrl. A tool like ngrok can be used to generate a url that exposes your localhost over SSL.

const { Reshuffle, CronConnector } = require("reshuffle");
const { GitHubConnector } = require("reshuffle-github-connector");
const { SlackConnector } = require("reshuffle-slack-connector");

const app = new Reshuffle();
// Cron config
const cronConnector = new CronConnector(app);
//Github Config
const githubConnector = new GitHubConnector(app, {
 token: process.env.GITHUB_TOKEN,
 runtimeBaseUrl: process.env.RUNTIME_BASE_URL,
});
const slackConnector = new SlackConnector(app, {
 token: process.env.SLACK_TOKEN,
 signingSecret: process.env.SLACK_SIGN_SECRET
});

 // Code listed further down
 // will be inserted here

app.start();

Reshuffle Connectors provide events and actions that allow developers to easily build custom workflows and integrations. We’re now able to take advantage of what they can do.

We’ll continue by getting a list of the user’s Github handles and their Slack IDs. In order to get this data, we use a method on Slack Connector that exposes Slack's web client actions.

Note: In this example, display_name is being assumed to be the same as the Github handle. You can definitely add your own profile fields that suit your team.

const slackUsers = await (async () => {
 const webClient = await slackConnector.getWebClient();
 const { members } = await webClient.users.list();
 let usersHash = {};
 members.forEach((member) => {
   usersHash[member.profile.display_name] = member.id;
 });
 return usersHash;
})();

Next, we’ll write a helper function to handle the event when a pull request is created, this will take in a list of reviewers from Github, the user list from Slack, and the link url to the pull request. If there are no reviewers, we’ll simply post to the general channel, otherwise, we match the reviewers to the slack members list and send them a direct message.

const messageHelper = async (
 ghReviewers,
 slackList,
 prLink,
 pending = false
) => {
 if (ghReviewers.length == 0) {
   await slackConnector.postMessage(
     "general",
     `${pending ? "Pending pull request" : "New pull request"} - ${prLink}`
   );
 } else {
   ghReviewers.forEach(async ({ login }) => {
     if (slackList.hasOwnProperty(login)) {
       await slackConnector.postMessage(
         slackList[login],
         `${
           pending ? "* Pending review *" : "* New review requested *"
         } ${prLink}`
       );
     }
   });
 }
};

To tie everything together, we configure the Github Connector to trigger an event anytime a pull request is created.

Note: See the full list of available events here

We can get the list of requested reviewers from the event object, passing onto our helper, which is only called if the event action matches “opened” or “reopened”.

githubConnector.on(
 {
   owner: process.env.GITHUB_OWNER,
   repo: process.env.GITHUB_REPO,
   githubEvent: "pull_request",
 },
 async (event, app) => {
   const {
     pull_request: { requested_reviewers },
     pull_request: { html_url },
   } = event;
   if (["opened", "reopened"].includes(event.action)) {
     const reviewers = requested_reviewers.map((reviewer) => reviewer);
     await messageHelper(reviewers, slackUsers, html_url);
   }
 }
);

Note: For more information on the parameters of postMessage check the docs.

With that, we’re finished, any time a pull requests is created with reviewers, they are directly messaged.

As a bonus, if the reviewers forget about the pull request, we can use the Cron Connector as a scheduler to check for any open PRs on the repository and message the reviewers.

cronConnector.on({ expression: "0 12 * * 3 *" }, async (event, app) => {
 const { data } = await githubConnector.sdk().pulls.list({
   owner: process.env.GITHUB_OWNER,
   repo: process.env.GITHUB_REPO,
   state: "open",
 });
 data.forEach(async ({ html_url, requested_reviewers: reviewers }) => {
   await messageHelper(reviewers, slackUsers, html_url, true);
 });
});

This example provides a good starting point to how you can easily create a custom workflow for your team's needs using Reshuffle.

Now, Make it Happen

Recurring Jira tickets with Reshuffle

Alan Lee — Thu, 03 Dec 2020 22:49:40 +0000

If you’re using Jira and have projects with repeating tickets that need to be added monthly, weekly or even daily, you know it can require painstaking manual labor to administer to all relevant projects, using up valuable time instead of solving the bigger problems. You could spend an hour or more configuring a system to automate this or even pay for a plugin on Jira, but, there is an easier way of doing this...and it's free!

How? Simply use Reshuffle connectors to easily create the integration.

How to Build It

Reshuffle makes it easy to build integrations that complete complex tasks, so you can deliver unique experiences and outcomes for the business and for customers.

Imagine you want a recurring issue to remind you to check npm dependencies every week. Creating the issue manually can become tiresome. In this example, you'll see how simple it is to use the Cron connector as a scheduler to automate the creation of recurring Jira tickets every predefined period of time.

See links for full documentation:
Reshuffle
Atlassian Jira Connector
Cron Connector

const app = new Reshuffle()
const jira = new JiraConnector(
   app, {
       host: process.env.HOST, // Your Jira instance url
       protocol: process.env.JIRA_PROTOCOL, // ‘http’ or ‘https’
       username: process.env.JIRA_USERNAME, // username or email
       password: process.env.JIRA_TOKEN,
       baseURL:  process.env.RUNTIME_BASE_URL
   });

const cronConnector = new CronConnector(app)

Now that we have the connectors configured, we need to find the project and issue type IDs using the Jira Connector actions. These IDs will be used later on to create the new ticket.

const project = await jira.sdk().getProject("YOUR PROJECT NAME");
const { id: projectId, issueTypeId = project.issueTypes[0].id } = project;
//issueTypes[0] are regular tasks on jira

Next, we’ll create a function to check if the recurring ticket already exists on the board. This will ensure that there won’t be any duplicates created.

const checkIssues = async () => {
    const boardIssues = await jira.sdk().getIssuesForBoard(1);
    for (const issue of boardIssues.issues) {
      const { fields } = issue;
     if (
        fields.summary === "CHECK NPM DEPENDENCIES" &&
        fields.status.name !== "Done"
      ) {
        return true;
      } else {
        continue;
      }
    }
    return false;
  };

Reshuffle is an events-based system, and you develop code to handle these events. The cron connector can be used to fire an event every "x" amount of time, which lets us check the issues periodically. If you’re unfamiliar with these expressions, visit crontab.guru to help generate one.

//this expression is set to every minute, just to see if everything is working properly
cronConnector.on({ expression: "1 * * * * *" }, async (event, app) => {
  const foundIssue = await checkIssues();
  if (!foundIssue) {
    const recurringIssue = {
      fields: {
        project: { id: projectId },
        issuetype: { id: issueTypeId },
        summary: "CHECK NPM DEPENDENCIES",
        description: "Recurring Issue - Every 1 minute",
      },
    };
    await jira.sdk().addNewIssue(recurringIssue);
    console.log("Issue created");
  } else {
    console.log("Issue already exists");
  }
});

Inside the event handler, we use the function created earlier to check if the task already exists. If it doesn’t, we create a new one using the Jira connector action.

Lastly, let's initiate the integration by starting the Reshuffle App:

app.start();

See how easy it is? You can do this so quickly and really make it much easier to automate recurring Jira tickets without having to pay for plugins or searching through the community boards for hour-long solutions.

Now, Make it Happen

How to Automatically Connect Jira Tickets to Google Sheets with Reshuffle

Alan Lee — Fri, 20 Nov 2020 17:35:25 +0000

If you’re using Jira, you know how it is to juggle dozens, if not hundreds, of tickets. Notifications pile up and tracking every new ticket gets complex, to say the least. Generating reports, and providing ongoing visibility for people who do not use Jira every day is also a big pain.

Well, if your company is using Google Sheets for reports and tracking, you can integrate Jira to it and set it up so that anytime a new Jira ticket is created, it will automatically update a Google spreadsheet. Now, all your Jira tickets will be in one easy to view spreadsheet and you can manage them in one place!

How? Simply use Reshuffle connectors to easily create the integration.

In this article, you will learn how to build a Jira to Google spreadsheet integration that lets people keep track of Jira tickets using an interface they’re already familiar with.

Lets Build It

Reshuffle makes it easy to build integrations that complete complex tasks, so you can deliver unique experiences and outcomes for the business and for customers.

In this example, you'll see a simple way to create a two way sync between Jira and Google Sheets. New issues created on Jira will add a new row to the spreadsheet containing the basic fields from the Jira issue. In turn, updates from the Google spreadsheet will also update the issue on Jira's end.

See links for full documentation:

Let's get started by instantiating a Reshuffle app and the two connectors listed above.

const app = new Reshuffle();
// Jira Config
const jira = new JiraConnector(app, {
  host: process.env.JIRA_HOST,
  protocol: process.env.JIRA_PROTOCOL, // 'http' or 'https'
  username: process.env.JIRA_USERNAME, // username or email
  password: process.env.JIRA_TOKEN,
  baseURL: process.env.RUNTIME_BASE_URL,
});

// Google Sheets Config
const googleSheets = new GoogleSheetsConnector(app, {
  credentials: {
    client_email: process.env.GOOGLE_CLIENT_EMAIL,
    private_key: process.env.GOOGLE_PRIVATE_KEY.replace(/\\n/g, "\n"),
  },
  sheetsId: process.env.GOOGLE_SHEET_ID,
});

Now that we have the connectors configured, we need to define the event we want to listen to, using the connectors on() method. For Jira, we will be listening to any new issues created. We will extract the issue's id, summary, description and status. We will then use the Google Sheets Connector to add these fields to our spreadsheet.

jira.on({ jiraEvent: "jira:issue_created" }, async (event, app) => {
  //Extract Jira fields from event
  const {
    id,
    fields: {
      summary,
      description,
      status: { name },
    },
  } = event.issue;

  //Use google sheets connector to add these fields as a row in the spreadsheet
  const sheetId = 0;
  const values = [
    id,
    summary,
    description,
    name,
    event.issue.fields.assignee
      ? event.issue.fields.assignee.displayName
      : "Not Assigned",
  ];
  await googleSheets.addRow(sheetId, values);
});

The next step is turning this example into a two way sync. To achieve that, we will set up a second event to listen to with the Google Sheets Connector. The connector will listen to changes made to the spreadsheet and allow us to process them.

Notice the empty {}, no need to give it options but see documentation for all that are available.

Inside of the handler, we will only process the changes made to an existing row. We can extract the previous and current row inputs to compare later on.

googleSheets.on({}, async (event, app) => {
  if (event.worksheetsChanged[0] && event.worksheetsChanged[0].rowsChanged[0]) {

    const { curr, prev } = event.worksheetsChanged[0].rowsChanged[0];

   //additional code to follow

  }

});

To keep track of the changes, we’re using an object to store the summary and description fields. Updating the status field will require more work, so we will need to find the transition IDs using a separate Jira connector action.

// continuing from the code above
let updates = { fields: {} };
// Find transition Ids
let transitionId = {};
const { transitions } = await jira.sdk().listTransitions(curr["Issue ID"]);
for (const status of transitions) {
  if (!transitionId[status.name]) {
    transitionId[status.name] = status.id;
  }
}
// additional code to follow

We can now iterate through the inputs and check if anything has changed by comparing the values.

for (const key in prev) {
  //skipping assignee and issue id fields in this example
  if (prev[key] !== curr[key]) {
    if (key === "Assignee" || key === "Issue ID") {
      continue;
    }
    if (curr[key] in transitionId) {
      transitionId = { id: transitionId[curr[key]] };
      await jira.sdk().transitionIssue(curr["Issue ID"], {
        transition: {
          id: transitionId.id,
        },
      });
    } else {
      updates = {
        fields: { ...updates.fields, [[key.toLowerCase()]]: curr[key] },
      };
    }
  }
}
// updates description/summary field
await jira.sdk().updateIssue(curr["Issue ID"], updates);

Lastly, let's initiate the integration by starting the Reshuffle App:

app.start();

See how easy it is? You can do this so quickly and really make it much easier to track new Jira tickets in Google Sheets bidirectionally. Check out the video demo to see it in action!

Now, Make it Happen

How to Retrieve a Movie's Official Poster with Reshuffle Open Source

Alan Lee — Thu, 12 Nov 2020 19:02:57 +0000

You know the name of your favorite movie, so how cool would it be to be able to retrieve any official movie poster just based on the movie’s title? While this may be a personal fun project for you and your friends, you also might be in a business where retrieving an image based on an associated name may be helpful — let’s say in marketing, you want to call up the product image by just using the product name. With Reshuffle open source integration framework, you can easily do this by setting up an API endpoint to retrieve the image, or as in our example below, the movie poster.

In this example, you’ll see how easy it is to integrate multiple services with Reshuffle, so you don't have to spend valuable development time configuring them. These integrations and workflows are created inside a Reshuffle App. The objects that let you interact with these services are called Connectors.

Let's Build It

This is a two-stage process. The code first uses Reshuffle's Entertainment Identifier Registry (EIDR) connector to resolve the movie name into a standardized movie ID. It then uses the Movies Anywhere API to look up the official movie poster image with the given ID.

See links for full documentation:

Let's get started by instantiating a Reshuffle app and the three connectors listed above.

// Initialize the Reshuffle application and connectors
const app = new Reshuffle();
const eidr = new EIDRConnector(app);
const http = new HttpConnector(app);
const ma = new MoviesAnywhereConnector(app);

Using the on() method of the HTTP Connector, we will be listening to an HTTP GET request on the "/" path. Inside Reshuffle, the request is transformed into an event.

http.on({ method: "GET", path: "/" }, async ({ req, res }) => {
  // Get the movie name from the query string
  const name = req.query.name;
  if (typeof name !== "string" || name.trim().length === 0) {
    return res.status(400).send(`Invalid movie name: ${name}`);
  }
  const nm = name.trim();

  // Get the image width from the query string, or default to 400
  const width = req.query.width || 400;
  const wd = typeof width === "string" ? parseInt(width, 10) : width;
  if (typeof wd !== "number" || isNaN(wd) || wd <= 1 || 8192 < wd) {
    return res.status(400).send(`Invalid width: ${wd}`);
  }

Moving forward with a valid movie name, we will use the EIDR connector with its simpleQuery method to resolve the provided name into an EIDR ID.

For more information regarding the object passed to simpleQuery, please take a look at the readme

  // The following blocks of code will follow directly after the previous, until it reaches the final `});`
  // Lookup the movie name in EIDR. If the movie is found, we get back a unique ID
  const movies = await eidr.simpleQuery({
    name: nm,
    movie: true,
    valid: true,
    StructuralType: "Performance",
  });
  if (movies.length < 1) {
    return res.status(404).send(`Movie not found: ${nm}`);
  }
  const id = movies[0].ID;
  // The movies array may contain multiple objects that reference the same movie, but with a different EIDR ID, we take [0] since they will all point to the same title.

If the query doesn't find a match with the provided movie name, it will be resolved into an empty array, there is a conditional block here to handle this case.

When the query passes the check above, we move on to where we will use the EIDR ID along with the Movies Anywhere connector. Keep in mind, not all movies are part of the Movies Anywhere service, so some may be resolved into undefined.

  // Lookup the movie ID in Movies Anywhere. Movies Anywhere's title service
  // provides metadata for movies, including a URL for the poster image
  const title = await ma.getTitleByEIDR(id);
  if (!title) {
    return res.status(404).send(`Movie not found: ${nm}`);
  }

Now that we have found the movie with the EIDR ID, we will create a url with the object resolved and return the image in the HTTP response.

  // Fetch the image
  const url = `https:${title.boxart}.jpg?w=${Math.round(wd)}`;
  const rs = await fetch(url);
  if (rs.status !== 200) {
    return res.status(500).send(`Unable to load poster image: ${nm}`);
  }
  // Return the image in the HTTP response
  const blob = await rs.blob();
  return res
    .set({ "Content-Type": blob.type, "Content-Length": blob.size })
    .send(Buffer.from(await blob.arrayBuffer()));

//end
});

Lastly, we need to start the Reshuffle App.

app.start(8000);

Try it out

If you copied the code from the repo, install the example and start the Reshuffle server:

npm install reshuffle-movieposter-example
npm run start

This will start a web server at local port 8000. Then point your browser to the local URL (http://localhost:8000/?name=superman) to see the poster frame.

It should look like this:

Try different movie names, but be aware that not all movies are part of the Movies Anywhere service, so some may not resolve into a poster image.

Let us know what you think

Reshuffle is continually listening to what our developers need and desire. Don’t see a Connector to a service you’d like to integrate? Send a tweet to @ReshuffleHQ to let us know which Connector you’d like us to develop next.

Tracking Twitter mentions with Monday.com

Alan Lee — Fri, 06 Nov 2020 19:07:35 +0000

Monitoring social media mentions is an essential part of any business. It gives brands an opportunity to track, analyze and respond to conversations about them on social media. In this quick tutorial, I will show you an example how you can a setup a simple Twitter mentions tracker with Monday.com.

In this article we will be using Reshuffle's open source integration framework to easily integrate Twitter and Monday services to meet your brands needs for social monitoring.

Let's build it

Normal setup and configuration could take a while in order to get these services to work together. Reshuffle is an open source, lightweight, and event-driven framework that helps you build integrations that completes complex tasks.

These integrations and workflows are created inside a Reshuffle App. The objects that let you interact with these services are called connectors.

The first thing we need to do is to declare a Reshuffle App and a Twitter connector that will search for any @mentions or #hashtag passed in.

  const app = new Reshuffle();
  const twitter = new TwitterConnector(app, {
    customerKey: process.env.TWITTER_CUSTOMER_KEY,
    customerSecret: process.env.TWITTER_CUSTOMER_SECRET,
  });

To keep track of mentions, we will be pushing them onto a Monday board using the Monday connector.

  const monday = new MondayConnector(app, {
    token: process.env.MONDAY_TOKEN,
    baseURL: "https://localhost:8000",
  });

Now that we have the connectors declared, we can start using them.

First thing is to make a new board from your Monday dashboard. Get the board ID from the url (eg. new-board-name.monday.com/board/2193445), this will be used to get the board data like column IDs, item names etc. Make a new board with columns that look similar to this.

Column	Type
tweet	Long-text
user	Text
created-at	Date

(async () => {
    const boardItems = await monday.getBoardItems(BOARD_ID);

    for (let id in boardItems.items) {
      if (!tweetsCache[boardItems.items[id].name]) {
        tweetsCache[boardItems.items[id].name] = { fetched: true };
      }
    }
  })().catch(console.error);

As you can see above, we use the BOARD_ID to fetch any items that is currently on the board using the getBoardItems method. For each of the row names, we will be using the Twitter IDs, as you will see later on. This function will run before any Twitter connector actions to prevent duplicate tweets from being saved onto the board.

With this duplicate check in place, we can move on with the Twitter connector.

We need to define the event to listen to using the Twitter connector's on() method. In this case, we will listen for search events.

  twitter.on({ search: "@reshuffleHQ" }, async (event, app) => {
    for (const tweet of event.tweets) {
      if (!tweetsCache[tweet.id]) {
        tweetsCache[tweet.id] = {
          user: tweet.user.screen_name,
          date: tweet.created_at,
          tweet: tweet.text,
        };
        addNewItem(tweet)
      }
    }

We will get an array of tweets from the event object. You can see in the if block, we run a check on the object from earlier, to prevent duplicate tweets from being added onto the Monday board. If the tweet does not exist in the object, we can continue to adding a new row with the addNewItem function we will create.

const createItems = async (tweetInfo) => {
    monday
      .getColumn(BOARD_ID)
      .then((res) => {
        return res.boards[0].columns.map(({ title }) => title);
      })
      .then(async (title) => {
        const testObj = {
          [title[1]]: () => tweetInfo.text,
          [title[2]]: () => tweetInfo.user.screen_name,
          [title[3]]: () =>
            new Date(Date.parse(tweetInfo.created_at))
              .toISOString()
              .split("T")[0],
        };

        const testQuery = await monday.createItem(
          BOARD_ID,
          JSON.stringify(tweetInfo.id),
          testObj
        );
      });
  };

In this function, we will be using multiple methods from the Monday connector. First we use the getColumn, to get the titles of each column, then we create an object using the column titles as the key. Finally, we can pass it through to the createItem method to generate a row that will look something like this.

Last but not least, let's initiate the integration by starting the Reshuffle App

app.start();

With minimal code, Twitter mentions are easily tracked with the Monday board. Now its your turn to get creative! Find new solutions to monitoring social mentions, maybe extend this functionality by tracking the frequency of daily mentions.