Setting up the Twitter integration for documents

Using the "Tweet to Twitter" document handler, you can configure the document system to automatically publish tweets to twitter when new documents are added to the system.   This can be used to automatically tweet about new news articles once they are published and so forth.

First you need to apply for a developer account at Twitter.  Log-in to the Twitter account you are setting the integration up for.  Then head to the Developers dashboard, https://developer.twitter.com/en/portal/dashboard and apply for a Developer account.  Once you have been accepted as a developer, go to the "Projects & Apps" section and create a project.  Then create an app under that project.  Under "User authentication settings" in the app settings, click set up and make sure that the "App permissions" is set to "Read and write".  You will need write permissions for the app to be able to publish Tweets.  Under "Type of App", select "Web App, Automated App or bot".   You will also need to provide a callback URL and your website URL.  Even though this is not used by the Twitter integration for now, valid URLs are required.

Then go back to the app settings, go to the "Keys and tokens" tab and generate an API key undir "Consumer Keys".  Store the generated key and secret - you'll need those later.  Generate authentication tokens as well and store the "Access token" and "Access token secret", you'll also need those as well.

Once this has been done, you should not need to configure anything else in Twitter.

Start by installing the Lisa.Modules.Components.Twitter module to your project.  This will enable the "Tweet to Twitter" handler.  Find the keys and tokens you generated in the previous step and add them to your appsettings.json file.  There are four fields you need to provide and the format should be as follows:

"Twitter": {
	"AccessToken": "",
	"AccessTokenSecret": "",
	"ConsumerKey": "",
	"ConsumerSecret": ""
}

Put the "Access token" and "Access token secret" in the respective fields in the config.  API Key and API secret should be placed in the "ConsumerKey" and "ConsumerSecret" fields respectively.

Now run your solution and open the Veva backend and open the Documents backend.  Click the model you wish to integrate with Twitter, click the "Design" button and go to the "Settings" tab and scroll down to the "Document handlers" section.  You should see the "Tweet to Twitter" handler in the list of available handlers.  Click the plus button to add it to the list of active handlers.

The handler has some configurable options, you can optionally include a URL to the document, so the user can click that link in the Tweet to be taken back to your website.  If you include the URL, you can optionally have the URL shortened by checking "Shorten URL", this requires an API key for Bitly.  See below.  If you want the URL to point to the exact document you were creating, you can include in the URL which will be replaced by the ID of the document.

Finally, you need to specify the body of the Tweet.  You can type in any text you want and to include data from the document, use the syntax.  If your model has a field called "content", you can use to get data from that field.

If you opt to use the "Shorten URL" option, you will need to optain an API key from Bitly.  Head to the Bitly API dashboard at https://app.bitly.com/settings/api/ and create an access token.  Then add this to your appsettings.json file:

"Bitly": {
	"AccessToken": "your-access-token"
}

By default, the "Tweet to Twitter" handler publishes all new documents in the model to Twitter.  If you want to decide whether you want the document posted to Twitter everytime you add a document, you can do so by adding a condition.  Go to the designer for the model and add a boolean field

In this case we have added a boolean field called "Senda á Twitter".  Now save those changes and go to the "Settings" tab and expand the "Tweet to Twitter" handler to view it's settings.  Under "Only tweet if this is true", select the boolean field you just created.  Now, everytime a document is created, the user will have to explicitly check "Senda á Twitter" for the handler to run.