Add-on Social Media Connector: Documentation

The Social Media Connector is an independent Java program that can publish content to social media services (such as Twitter, Facebook etc.).

Table of Contents

This is a paid Sophora add-on. For details, please refer to our website.

Working with the Social Media Connector Add-on

Sophora’s add-on Social Media Connector supports you in updating your Facebook pages and Twitter channels with Sophora. Write and manage your content with Sophora and use the social media channels to spread your content. You can easily use existing content from Sophora or create new content in order to push it to social media. Links to the company’s website are set automatically if the check box is selected. Working with Sophora’s add-on saves time and extra work.  

Note: The following description “Working with the Social Media Connector Add-on” is only one way to use Sophora’s add-on. As an alternative solution, it is conceivable that the text for social media channels is written in separate document fields, similar to the input field “teaser”.
Sophora Add-on Social-Media-Connector

Publishing Content to Facebook

  • Select the icon Document Action, listed in the editor toolbar.
  • Choose Publish to SocialMedia via SocialMediaConnector.
  • A dialogue box in order to push content to social media will be opened. The document’s headline is set by default. You can use existing text or change it individually before pushing it to Facebook.
  • The URL of your Sophora document will be displayed as well when selecting Facebook Add URL.
Social media channels will be displayed depending on the given authorization of the editor. If the editor has no authorization for any social media channel, a corresponding response appears.

Publishing Content to Twitter

  • Select the icon Document Action, listed in the editor toolbar.
  • Choose Publish to SocialMedia via SocialMediaConnector.
  • A dialogue box in order to push content to social media will be opened. The document’s headline is set by default. You can use existing text or change it individually before pushing it to Twitter.
  • The URL of your Sophora document will be displayed as well when selecting Twitter Add URL.
If you want to use hashtags for Twitter, you just need to insert it into your text. After pushing your content to Sophora, your hashtag will be created automatically.
Sophora Add-on Social-Media-Connector Twitter

You don’t need to open documents first before pushing content to social media. You can push content directly from the search as well.

  • Execute a search.
  • Open the context menu of a search result you want to push content from. You can open the content menu via right click.
  • Select the icon Document Action.
  • Choose Publish to SocialMedia via SocialMediaConnector.
  • A dialogue box in order to push content to social media will be opened. The document’s headline is set by default. You can use existing text or change it individually before pushing it to social media.
Sophora Add-on Social Media Connector - Push Content to Social Media

Installation

When you install the Sophora Social Media Connector, it is recommended to use the following folder hierarchy:

cms-install-directory
		apps
				com.subshell.sophora.socialmediaconnector-1.53.0
						socialmediaconnector.sh
						...
				sophora-socialmediaconnector > Symbolic link to com.subshell.sophora.socialmediaconnector-1.53.0
				...
		socialmediaconnector
				config
						socialmediaconnector-config.json
				logs
				socialmediaconnector.sh > Symbolic link to ../apps/sophora-socialmediaconnector/socialmediaconnector.sh
		...

This hierarchy is analogous to the directory structure of the Sophora server.

Starting and Stopping

To start the Sophora Social Media Connector invoke the socialmediaconnector.sh as follows:

> cd cms-install-directory/socialmediaconnector
> ./socialmediaconnector.sh start

For configuration details see the following sections.

To stop the Sophora Social Media Connector prompt the following:

> cd cms-install-directory/socialmediaconnector
> ./socialmediaconnector.sh stop

Configuration

To change the configuration, edit the socialmediaconnector-config.json file which is located in the config subdirectory of the Social Media Connector installation. See example configuration below.

Twitter Configuration

To succesfully configure your social mediaconnector to connect with Twitter, you will need the following information:

  • the API key
  • the API secret
  • the access token
  • the access token secret

You will get those information when you add a new app to your Twitter account with read and write permissions. See https://apps.twitter.com/app/new, https://dev.twitter.com/docs/auth/oauth.

Facebook Configuration

In order to publish content to a Facebook page, you'll need a page access token and an application secret. Therefore you have to create a Facebook application in the Facebook Developers area and then request a page access token with the proper permission "manage_pages" and "publish_pages". See the Facebook documentation for further information about permissions and access tokens.

The following is a step-by-step guide to creating a page access token with the proper permissions.

  1. Create a Facebook app at https://developers.facebook.com/. If you already have an app you may skip this step.
  2. Generate a short-lived access token by going to the Graph API Explorer. Select the app you want to create the access token for. Click Get Token -> Click Get User Access Token. In the pop-up go to the Extended Permissions and select the "manage_pages" and "publish_pages" permissions. Now click Get Access Token. You will now have to grant access from a Facebook account that has acces to manage the target page. If you are logged in with that user already, a pop-up will appear automatically. Grab the generated (short-lived) Access Token.
  3. Go to https://developers.facebook.com/apps/ and select the app you just generated the access token for. Grab the App ID as well as the App Secret. Now we are going to generate a long-lived access token from the short-lived one. Call the following URL in a web browser of your choice replacing the place holders with the correct values: https://graph.facebook.com/oauth/access_token?grant_type=fb_exchange_token&client_id={app_id}&client_secret={app_secret}&fb_exchange_token={short_lived_token}. The response should contain your (long-lived) Access Token.
  4. Use your long lived access token to make another URL call to find your Account ID: https://graph.facebook.com/me?access_token={long_lived_access_token}
  5. Now we are finally able to generate a Permanent Page Access Token: https://graph.facebook.com/{account_id}/accounts?access_token={long_lived_access_token}. Grab the access token for your page.

Since other Facebook users should see the posts made by the app, you have to set the application status to public in the developers section. Do not forget to configure the app in the user's profile settings.

Example configuration

{
	vmargs: "-Xmx512m",
	
	sophoraServer: {
		host: "localhost:1199", // host URL and port of the sophora server
		username: "admin", 		// user name of the user to be used when logging into the server
		password: "admin" 		// user password of the user to be used when logging into the server
	},
	
	// Proxy Settings (optional)
	httpProxyHost: "",				// the http proxy host for connecting Twitter and Facebook (optional)
	httpProxyPort: 0,				// the port of the http proxy (optional)
	httpProxyUsername: "",			// the username for the http proxy (optional)
	httpProxyPassword: "",			// the password for the http proxy (optional)
	
	// Account Settings
	accounts:
		[
			{
				// Twitter
				id: "twitter_account_id", 		// this can be any custom identifier
				name: "My Twitter Account", 	// this should be a user readable name for the account
				type: "TWITTER", 				// specifies that this is a twitter account, note that this is case sensitive
				delay: 2000, 					// delay before content will be published in milliseconds (optional)
				
				loginData: {
					consumerKey: "<API key>", 					// Twitter API key
					consumerSecret: "<API secret>", 				// Twitter API secret
					accessToken: "<access token>", 				// Twitter access token
					accessTokenSecret: "<access token secret>" 	// Twitter access token secret
				}
			},
			{
				// Facebook
				id: "facebook_account_id", 		// this can be any custom identifier
				name: "My Facebook Profile", 	// this should be a user readable name for the account
				type: "FACEBOOK", 				// specifies that this is a Facebook account, note that this is case sensitive
				delay: 2000, 					// delay before content will be published in milliseconds (optional)
				
				loginData: {
					accessToken: "<access token>",	// Facebook page access token
					appSecret: "<application secret>"	// Facebook application secret (optional, depending on Facebook app setting 'App Secret Proof for Server API calls')
				}
			}
		]
}

Usage

To publish content to an external service you will have to use the Sophora client API. This can be easily done via a client script. Please see the following example script:

List<IContent> documents = context.getDocuments()
if (documents.size() != 1) {
   context.showMessageToUser("Select (only) one document!")
   return
}
INode document = documents.get(0)
String titleText = document.getProperty('sophora-content:title').getString()
IFieldsDialogBuilderContext dialog = context.dialog().withTitle('Push to Social Media').create()
  .addLabel('Enter text to push to  social media')
  .addField('twitterText', 'Twitter Text', text(titleText).multi().charCounter().maxChars(118))
  .addField('twitterAddUrl', 'Twitter Add URL', checkbox(true))
  .addField('facebookText', 'Facebook', text(titleText).multi().charCounter())
  .addField('facebookAddUrl', 'Facebook Add URL', checkbox(true))
  .addField('facebookShareLink', 'Facebook Share Link', checkbox(true))
  
IDialogResult dialogResult  = dialog.open()
if (dialogResult) {
     String twitterText = dialogResult.get('twitterText')
     boolean twitterAddUrl = dialogResult.get('twitterAddUrl')
     // A map is only needed if you want to specify several parameters, otherwise you can just use a String that contains the text to publish.
     Map twitterData = [
        'text' : twitterText,					// the text to publish
        'addDocumentUrl' : twitterAddUrl        // specifies whether the document delivery URL will be added at the end of the text to publish (default is 'true')
     ]
     String facebookText = dialogResult.get('facebookText')
     boolean facebookAddUrl = dialogResult.get('facebookAddUrl')
     boolean facebookShareLink = dialogResult.get('facebookShareLink')
     // A map is only needed if you want to specify several parameters, otherwise you can just use a String that contains the text to publish.
     Map facebookData = [
        'text' : facebookText,					// the text to publish
        'addDocumentUrl' : facebookAddUrl,	// specifies whether the document delivery URL will be added at the end of the text to publish (default is 'true')
		'shareLink' : facebookShareLink		// specifies whether the document delivery URL will be shared as a link on Facebook
     ]
      
     // Publish content to the external service(s) specified by the given account id(s).
     // The id(s) MUST exist in the socialmediaconnector-config.json.
     Map publishMap = [
        'twitter_account_id' : twitterData,
        'facebook_account_id' :  facebookData
     ]
     sophoraClient.publishToExternalService(publishMap, document.UUID) 
}

Parameter Overview

The following table is an overview of all possible parameters. If a parameter is not supported by a particular social media type, it will be ignored.

Parameter nameParameter typeDescriptionSupported by
textStringThe text to publish on the particular social media service.
Note that some social media services might have character limitations.
Twitter, Facebook
addDocumentUrlbooleanSpecifies whether the document delivery URL should be appended to the text to publish.
Note: If the document does not have a delivery URL, only the text will be published.
Twitter, Facebook
shareLinkbooleanSpecifies whether the document delivery URL should be shared as a link.
Note: If the document does not have a delivery URL, only the text will be published.
Facebook

Parameter 'addDocumentUrl'

If you want to use the parameter 'addDocumentUrl' you will have to configure your server and delivery properly.

It is necessary to configure the service within your web application accordingly. Therefore you have to make sure the servlet is set up in the web.xml as follows.

web.xml

[...]
<servlet>
  <servlet-name>urlServlet</servlet-name>
  <servlet-class>com.subshell.sophora.delivery.servlet.UrlForIdServlet</servlet-class>
</servlet>
 
<servlet-mapping>
  <servlet-name>urlServlet</servlet-name>
  <url-pattern>/system/servlet/urlService.servlet</url-pattern>
</servlet-mapping>
[...]

You will also have to configure the URL of the delivery in the sophora.properties of the server.

sophora.properties (Server) Example

sophora.replication.delivery.0.url=http://localhost:8080/
sophora.replciation.delivery.0.groups=group1

Publication information in the document

After publishing data to a social media service, information about the publication will be written back to the document. Each publication will add a data entry to the document. This entry contains the following information:

  • The ID of the published content in the social media service (sophora:contentId)
  • The ID of the account to which was published (sophora:publishedTo)
  • The date of publication (sophora:publicationDate)
  • The name of the user who triggered the publication (sophora:publishedBy)

This information is stored as "Yellow Data" (meta data that does not change the document). It can be accessed through the Sophora Client with the following call:

List<YellowData> publicationInfos = client.getYellowData(documentUuid, "sophora-nt:socialMediaPublication");