Connector - Global

The connectors are the tool for integrating with other systems and software. The have two sets of configuration options - global (concerning the whole system or all groups that have this connector enabled) and local (concerning only the group your changing them for)

Method: get

Authorization is required. Get the global details of a connector.

Request

HTTP request

GET https://<YOUR_DOMAIN>/api/v1/en_US/connector/global/{connectorId}

Parameters

propertyvaluedescription
connectorId guid The connector's ID

Request body

Do not supply a request body with this method.

Response

If successful, this method returns a response JSON with the following structure:

{
  "success": true,
  "message": "Nisi proident tempor cillum sint duis eu elit dolor Lorem amet qui officia occaecat.",
  "timestamp": "2014-03-03T23:20:23Z",
  "errors": [],
  "object": {
    "id": "e532e792-4101-4ef5-8cd7-68380bbbc112",
    "type": {
      "id": 4,
      "name": "Authentication provider - Facebook.com",
      "thumbUrl": "http://demo.hivesocialnow.com/App_Themes_Main/images/admin/facebook.jpg"
    },
    "name": "Authentication provider - Facebook.com",
    "description": "Provides ability for users to sign in with their Facebook account",
    "accessTypeId": 2,
    "accessTypeName": "Private",
    "isEnabled": true,
    "createdOn": "2014-03-03T23:20:23Z",
    "author": {
      "id": "6b05b94e-e7c6-4bab-9377-e89ae1651425",
      "alias": "labore labore",
      "extendedAlias": "aute commodo eiusmod nisi labore",
      "slug": "Home",
      "avatarUrl": "http://demo.hivesocialnow.com/bigavatar/bc7fbf51-7930-4550-98b0-6a3ff6111ebe.jpg",
      "url": "http://demo.hivesocialnow.com/blog/GeorgiRaykov/site/profile/"
    },
    "modifiedOn": "2014-03-03T23:20:23Z",
    "editor": {
      "id": "6b05b94e-e7c6-4bab-9377-e89ae1651425",
      "alias": "labore labore",
      "extendedAlias": "aute commodo eiusmod nisi labore",
      "slug": "Home",
      "avatarUrl": "http://demo.hivesocialnow.com/bigavatar/bc7fbf51-7930-4550-98b0-6a3ff6111ebe.jpg",
      "url": "http://demo.hivesocialnow.com/blog/GeorgiRaykov/site/profile/"
    },
    "groups": [
      {
        "id": "e532e792-4101-4ef5-8cd7-68380bbbc703",
        "name": "fugiat",
        "slug": "Home",
        "thumbUrl": "http://demo.hivesocialnow.com/logo/72_635267855582630000.png",
        "url": "http://demo.hivesocialnow.com/Home/"
      }
    ],
    "settings": {
      "applicationId": "111198818571111",
      "applicationSecret": "111145990c25f117f4aa04e7bec11111"
    },
    "accessWarnings": []
  }
}

The general response properties are described on the Response format page. Here are the list of the specific properties for this method.

propertyvaluedescription
name string The connector identifier in the list. Can be modified only for the creatable ones.
description string A few words about the connector. Can be modified only for the creatable ones.
connectorType object Defines the connector type with its id, name and thumbnail as the visual representation.
accessTypeId integer The id of the connector administration access type. The access types can be:
  • 1 - Public. Is visible for the groups other than the root one. If there are local settings that can be managed for this connector, they will be available for the group's administrator.
  • 2 - Private. It is not visible for any other group beside the root one. No settings can be managed (even if there are local ones) by the subgroup administrators.
accessTypeName string Public or Private, according to the above row.
isEnabled boolean Whether this connector is enabled globally in the system. If disabled it will not operate at all in any group.
createdOn date When the connector was created in ISO 8601 string format and UTC time zone.
author object some common properties of the user that created the record: id, alias, extendedAlias, slug, avatarUrl, url (of the profile page)
modifiedOn date When the connector was last modified in ISO 8601 string format and UTC time zone.
editor object some common properties of the user that modified the record last: id, alias, extendedAlias, slug, avatarUrl, url (of the profile page)
groups List (object) list of group objects, for which this connector is enabled
settings object the properties of this object are different for each of the connector types. You can review them in detail below.

The difference between the properties of each type of connector is in the object.settings object properties. There you can find all the specific configuration of the connector type - Facebook, Linkedin etc.

These settings objects can be defined as follows:

Authentication provider - Edu1World.org

Provides ability for users to sign in with their Edu1World account

"settings":  {}

All edu1world.org authentication settings are precoded.

Authentication provider - Facebook.com

Provides ability for users to sign in with their Facebook account

"settings":  {
	"applicationId":  "111111111111111",
	"applicationSecret" : "11111111111111111111111111111111"
}
propertyvaluedescription
applicationId string Your Facebook application id
applicationSecret string Your Facebook application secret

Authentication provider - Twitter.com

Provides ability for users to sign in with their Twitter account

"settings":  {
	"applicationId":  "111111111111111",
	"applicationSecret" : "11111111111111111111111111111111"
}
propertyvaluedescription
applicationId string Your Twitter application id
applicationSecret string Your Twitter application secret

Authentication provider - LinkedIn.com

Provides ability for users to sign in with their LinkedIn account

"settings":  {
	"applicationId":  "111111111111111",
	"applicationSecret" : "11111111111111111111111111111111"
}
propertyvaluedescription
applicationId string Your LinkedIn application id
applicationSecret string Your LinkedIn application secret

Authentication provider - SalesForce.com

Provides ability for users to sign in with their SalesForce account

"settings":  {
	"applicationId":  "111111111111111",
	"applicationSecret" : "11111111111111111111111111111111"
}
propertyvaluedescription
applicationId string Your SalesForce application id
applicationSecret string Your SalesForce application secret

Paypal connector

Paypal is a managing HiveSocial's premium content payments. This connector details are set in the web.config file.

"settings":  {
	 "currency": "USD",
	 "merchantEmail":  "domain@domain.com"
}
propertyvaluedescription
currency string the selected currency for your transactions
merchantEmail string Your Paypal merchant account

ChatVilla connector

Chatvilla is a real time chat application module. These are the ChatVilla application global settings. In each group you will need to set a local settings too.

"settings":  {
	 "apiUrl": "http://domain.com",
	 "scriptUrl":  "http://domain.com/script",
	 "inheritSettings":  false,
	 "applicationId": "e532e792-4101-4ef5-8cd7-68380bbbc703",
	 "applicationSecret": "secretKey",
	 "allowGuest":  false
}
propertyvaluedescription
apiUrl string the URL of the ChatVilla application API you want to use
scriptUrl string The URL of the integration Javascript you want to use
inheritSettings string Whether the local connectors to inherit the parent group's ChatVilla connector settings by default
applicationId string Your ChatVilla application id
applicationSecret string Your ChatVilla application secret
allowGuest boolean Whether to allow users not logged in your HiveSocial system, to use chat application in this group.

SalesForce.com connector

Here are included all the instances of this connector type created by the administrator.

"settings":  {}

The settings are managed only on the local group level, as Local connectors

Method: list

Authorization is required.

Request

HTTP request

GET https://<YOUR_DOMAIN>/api/v1/en_US/connector/global/list

Parameters

Do not supply a request parameters with this method.

Request body

Do not supply a request body with this method.

Response

If successful, this method returns a response JSON. It will contain all the available global connectors in its object.connectors array

Method: create

Authorization is required.

Currently you can create instances only from the "SalesForce connector", which is typeId of 1

Request

HTTP request

POST https://<YOUR_DOMAIN>/api/v1/en_US/connector/global/add

Parameters

Do not supply a request parameters with this method.

Request body

propertyvaluedescription
typeId integer The connector type that you want to create. currently only 1 is allowed
connector object The created connector object. It has the properties presented in the next table.

SalesForce connector object properties

propertyvaluedescription
apiUrl string The URL of the SalesForce API you want to be used. It is provided by SalesForce within your application settings.
apiVersion string Which API version you need to be used. Ex. "v29.0"
company string Which from your SalesForce application companies you need to be used. Should exist in your SalesForce.com application.
token string Provided by your SalesForce application configuration.
sfAccountUsername string The username of the SalesForce.com account to be used for interaction with SalesForce system. Note: This user will be used as author of the automatically synchronized content, and should have the proper read, write, update and delete permissions.
sfAccountPassword string The password of the SalesForce.com account.
hsAccountEmail string The email of the HiveSocial account to be used for interaction with HiveSocial system. Note: This user will be used as author of the automatically synchronized content. The groups permission will be overrided.
postSynchTypeId integer HiveSocial posts<> SalesForce cases synchronization type. Can be:
  • 0 - None. Posts will not be synchronized.
  • 1 - Manual. By clicking the corresponding functionality buttons manually by the administrators.
  • 2 - Automatic on post create AND edit | HiveSocial -> SalesForce
postConditionalEscalationTypeId integer If and how the HiveSocial's post should be escalated to SalesForce, if they do not get the "Resolved" status in a certain period. The escalation types could be:
  • 0 - None. Posts will not be automatically escalated to SalesForce, only manually by administrators, by clicking the corresponding button.
  • 1 - Automatic HiveSocial -> SalesForce, if the posts are not resolved within the predefined period.
postConditionalEscalationPeriod integer The period in which the posts should get the "Resolved" status in order not to be automatically escalated to SalesForce, if the proper escalation type is selected.
postAuthorSynchTypeId integer From who's name to create the post in SalesForce. Currently the only option is 0, by the appointed by the connector default SalesForce user.
postPriority string One of the SalesForce post priorities, which should be preselected for all posts that are escalated from HiveSocial to SalesForce. The available options by default are:
  • None
  • High
  • Medium
  • Low
postOrigin string One of the SalesForce post origins, which should be preselected for all posts that are escalated from HiveSocial to SalesForce. The available options by default are:
  • None
  • Phone
  • Email
  • Web
postAccountName string The exact name of the account for which the escalated posts should be subscribed to.
postCommentSynchTypeId integer HiveSocial post comments <> SalesForce case comments synchronization type. Can be:
  • 0 - None. Post comments will not be synchronized.
  • 1 - Automatic on comment create AND edit OR post escalation| HiveSocial -> SalesForce.
leadSynchTypeId integer HiveSocial user profiles <> SalesForce leads synchronization type. Can be:
  • 0 - None. User profiles will not be synchronized.
  • 1 - Post author on escalation. Only the post author's profile will be synchronized upon post escalation.
  • 2 - Post and comment authors on escalation. The post author's profile and the profiles of all commentators will be synchronized upon post escalation.
  • 3 - All regular users on schedule
  • 4 - All members users on schedule
  • 5 - All moderator users on schedule
  • 6 - All regular & member users on schedule
  • 7 - All regular & member & moderator users on schedule
  • 8 - All member & moderator users on schedule
  • 9 - All users on schedule
profileControlsLeadPhoneId guid The ID of the HiveSocial field which value to provide to SalesForce as the lead phone.
profileControlsLeadCompanyId guid The ID of the HiveSocial field which value to provide to SalesForce as the lead company.
profileControlsLeadStreetId guid The ID of the HiveSocial field which value to provide to SalesForce as the lead street.
profileControlsLeadCityId guid The ID of the HiveSocial field which value to provide to SalesForce as the lead city.
profileControlsLeadStateId guid The ID of the HiveSocial field which value to provide to SalesForce as the lead state.
profileControlsLeadPostalCodeId guid The ID of the HiveSocial field which value to provide to SalesForce as the lead zip code.
profileControlsLeadCountryId guid The ID of the HiveSocial field which value to provide to SalesForce as the lead zip country.
profileControlsLeadWebsiteId guid The ID of the HiveSocial field which value to provide to SalesForce as the lead zip website.
contactSynchTypeId integer HiveSocial user profiles<> SalesForce contacts synchronization type. Can be:
  • 0 - None. User profiles will not be synchronized.
  • 1 - Post author on escalation. Only the post author's profile will be synchronized upon post escalation.
  • 2 - Post and comment authors on escalation. The post author's profile and the profiles of all commentators will be synchronized upon post escalation.
  • 3 - All regular users on schedule
  • 4 - All members users on schedule
  • 5 - All moderator users on schedule
  • 6 - All regular & member users on schedule
  • 7 - All regular & member & moderator users on schedule
  • 8 - All member & moderator users on schedule
  • 9 - All users on schedule
profileControlsContactAccountId guid The SalesForce account Id to be matched. If the HS field is not matched to an existing SF account name, the default connector account will be used instead
profileControlsContactPhoneId guid The ID of the HiveSocial field which value to provide to SalesForce as the contact phone.
profileControlsContactStreetId guid The ID of the HiveSocial field which value to provide to SalesForce as the contact street.
profileControlsContactCityId guid The ID of the HiveSocial field which value to provide to SalesForce as the contact city.
profileControlsContactPostalCodeId guid The ID of the HiveSocial field which value to provide to SalesForce as the contact zip code.
profileControlsContactCountryId guid The ID of the HiveSocial field which value to provide to SalesForce as the contact country.
schedulerType string What kind of scheduling should be used for the automatic synchronization. The available options are:
  • daily
  • period
schedulerDailyTime date When, during the day, to execute the synchronization in ISO 8601 date string and UTC time zone.
schedulerPeriod integer On how long periods to execute the synchronization in number of hours.

Response

If successful, this method returns a response JSON.

The general response properties are described on the Response format page. Here are the list of the specific properties for this method.

propertyvaluedescription
success Boolean Whether the requested operation is successful or not
message String Human readable error information
errors List (object) List of validation errors, if any. The "key" property value is matched to one of the record's fields
object object The object that caused the validation errors or that was created. Have in mind that, if the server requires string trimming or data manipulation after the user submission, it is applied in this object. In this way the returned object can differe from the posted one.

Method: update

Authorization is required.

Request

HTTP request

PUT https://<YOUR_DOMAIN>/api/v1/en_US/connector/global/{connectorId}

Parameters

propertyvaluedescription
connectorId integer In id of the updated record

Request body

propertyvaluedescription
connector object The updated connector POST object. It depends on the type of the connector, as described in the following tables.

Connector object for type 3: Authentication provider - Edu1World.org

The update method does not support updating this type of connector.

Connector object for type 4: Authentication provider - Facebook.com

propertyvaluedescription
isEnabled boolean Whether the connector is globally enabled
applicationId string Your facebook application Id
applicationSecret string Your facebook application secret

Connector object for type 5: Authentication provider - Twitter.com

propertyvaluedescription
isEnabled boolean Whether the connector is globally enabled
applicationId string Your Twitter application Id
applicationSecret string Your Twitter application secret

Connector object for type 6: Authentication provider - LinkedIn.com

propertyvaluedescription
isEnabled boolean Whether the connector is globally enabled
applicationId string Your LinkedIn application Id
applicationSecret string Your LinkedIn application secret

Connector object for type 7: Authentication provider - SalesForce.com

propertyvaluedescription
isEnabled boolean Whether the connector is globally enabled
applicationId string Your SalesForce application Id
applicationSecret string Your SalesForce application secret

Connector object for type 8: Paypal connector

The update method does not support updating this type of connector. The settings for the Paypal integration are set in the web.config file.

Connector object for type 2: ChatVilla

propertyvaluedescription
isEnabled boolean Whether the connector is globally enabled
apiUrl string Your ChatVilla API URL
scriptUrl string Your ChatVilla script URL
inheritSettings boolean Whether the local connectors to inherit the parent group's ChatVilla connector settings by default
applicationId string Your ChatVilla application Id
applicationSecret string Your ChatVilla application secret
allowGuest boolean Whether to allow users not logged in your HiveSocial system, to use chat application in this group.

Connector object for type 1: SalesForce connector

propertyvaluedescription
apiUrl string The URL of the SalesForce API you want to be used. It is provided by SalesForce within your application settings.
apiVersion string Which API version you need to be used.
company string Which from your SalesForce application companies you need to be used. Should exist in your SalesForce.com application.
token string Provided by your SalesForce application configuration.
sfAccountUsername string The username of the SalesForce.com account to be used for interaction with SalesForce system. Note: This user will be used as author of the automatically synchronized content, and should have the proper read, write, update and delete permissions.
sfAccountPassword string The password of the SalesForce.com account.
hsAccountEmail string The email of the HiveSocial account to be used for interaction with HiveSocial system. Note: This user will be used as author of the automatically synchronized content. The groups permission will be overrided.
postSynchTypeId integer HiveSocial posts<> SalesForce cases synchronization type. Can be:
  • 0 - None. Posts will not be synchronized.
  • 1 - Manual. By clicking the corresponding functionality buttons manually by the administrators.
  • 2 - Automatic on post create AND edit | HiveSocial -> SalesForce
postConditionalEscalationTypeId integer If and how the HiveSocial's post should be escalated to SalesForce, if they do not get the "Resolved" status in a certain period. The escalation types could be:
  • 0 - None. Posts will not be automatically escalated to SalesForce, only manually by administrators, by clicking the corresponding button.
  • 1 - Automatic HiveSocial -> SalesForce, if the posts are not resolved within the predefined period.
postConditionalEscalationPeriod integer The period in which the posts should get the "Resolved" status in order not to be automatically escalated to SalesForce, if the proper escalation type is selected.
postAuthorSynchTypeId integer From who's name to create the post in SalesForce. Currently the only option is 0, by the appointed by the connector default SalesForce user.
postPriority string One of the SalesForce post priorities, which should be preselected for all posts that are escalated from HiveSocial to SalesForce. The available options by default are:
  • None
  • High
  • Medium
  • Low
postOrigin string One of the SalesForce post origins, which should be preselected for all posts that are escalated from HiveSocial to SalesForce. The available options by default are:
  • None
  • Phone
  • Email
  • Web
postAccountName string The exact name of the account for which the escalated posts should be subscribed to.
postCommentSynchTypeId integer HiveSocial post comments <> SalesForce case comments synchronization type. Can be:
  • 0 - None. Post comments will not be synchronized.
  • 1 - Automatic on comment create AND edit OR post escalation| HiveSocial -> SalesForce.
leadSynchTypeId integer HiveSocial user profiles <> SalesForce leads synchronization type. Can be:
  • 0 - None. User profiles will not be synchronized.
  • 1 - Post author on escalation. Only the post author's profile will be synchronized upon post escalation.
  • 2 - Post and comment authors on escalation. The post author's profile and the profiles of all commentators will be synchronized upon post escalation.
  • 3 - All regular users on schedule
  • 4 - All members users on schedule
  • 5 - All moderator users on schedule
  • 6 - All regular & member users on schedule
  • 7 - All regular & member & moderator users on schedule
  • 8 - All member & moderator users on schedule
  • 9 - All users on schedule
profileControlsLeadPhoneId guid The ID of the HiveSocial field which value to provide to SalesForce as the lead phone.
profileControlsLeadCompanyId guid The ID of the HiveSocial field which value to provide to SalesForce as the lead company.
profileControlsLeadStreetId guid The ID of the HiveSocial field which value to provide to SalesForce as the lead street.
profileControlsLeadCityId guid The ID of the HiveSocial field which value to provide to SalesForce as the lead city.
profileControlsLeadStateId guid The ID of the HiveSocial field which value to provide to SalesForce as the lead state.
profileControlsLeadPostalCodeId guid The ID of the HiveSocial field which value to provide to SalesForce as the lead zip code.
profileControlsLeadCountryId guid The ID of the HiveSocial field which value to provide to SalesForce as the lead zip country.
profileControlsLeadWebsiteId guid The ID of the HiveSocial field which value to provide to SalesForce as the lead zip website.
contactSynchTypeId integer HiveSocial user profiles<> SalesForce contacts synchronization type. Can be:
  • 0 - None. User profiles will not be synchronized.
  • 1 - Post author on escalation. Only the post author's profile will be synchronized upon post escalation.
  • 2 - Post and comment authors on escalation. The post author's profile and the profiles of all commentators will be synchronized upon post escalation.
  • 3 - All regular users on schedule
  • 4 - All members users on schedule
  • 5 - All moderator users on schedule
  • 6 - All regular & member users on schedule
  • 7 - All regular & member & moderator users on schedule
  • 8 - All member & moderator users on schedule
  • 9 - All users on schedule
profileControlsContactAccountId guid The SalesForce account Id to be matched. If the HS field is not matched to an existing SF account name, the default connector account will be used instead
profileControlsContactPhoneId guid The ID of the HiveSocial field which value to provide to SalesForce as the contact phone.
profileControlsContactStreetId guid The ID of the HiveSocial field which value to provide to SalesForce as the contact street.
profileControlsContactCityId guid The ID of the HiveSocial field which value to provide to SalesForce as the contact city.
profileControlsContactPostalCodeId guid The ID of the HiveSocial field which value to provide to SalesForce as the contact zip code.
profileControlsContactCountryId guid The ID of the HiveSocial field which value to provide to SalesForce as the contact country.
schedulerType string What kind of scheduling should be used for the automatic synchronization. The available options are:
  • daily
  • period
schedulerDailyTime date When, during the day, to execute the synchronization in ISO 8601 date string and UTC time zone.
schedulerPeriod integer On how long periods to execute the synchronization in number of hours.

Response

If successful, this method returns a response JSON

The general response properties are described on the Response format page. Here are the list of the specific properties for this method.

propertyvaluedescription
success Boolean Whether the requested operation is successful or not
message String Human readable error information
errors List (object) List of validation errors, if any. The "key" property value is matched to one of the record's fields
object object The object that caused the validation errors or that was updated. Have in mind that, if the server requires string trimming or data manipulation after the user submission, it is applied in this object. In this way the returned object can differe from the posted one.

Method: update-status

Authorization is required.

Request

HTTP request

PATHC https://<YOUR_DOMAIN>/api/v1/en_US/connector/global/{connectorId}/status

Parameters

propertyvaluedescription
connectorId integer In id of the updated record

Request body

propertyvaluedescription
isEnabled boolean Whether the connector is globally available

Response

If successful, this method returns a response JSON with the following structure:

The general response properties are described on the Response format page. Here are the list of the specific properties for this method.

propertyvaluedescription
success Boolean Whether the requested operation is successful or not
message String Human readable error information
errors List (object) List of validation errors, if any. The "key" property value is matched to one of the record's fields
object object The updated connector object

Method: test SalesForce connector

Authorization is required. This method will test the SalesForce integrations information.

Request

HTTP request

POST https://<YOUR_DOMAIN>/api/v1/en_US/connector/global/test/salesforce-connection

Parameters

Do not supply a request parameters with this method.

Request body

propertyvaluedescription
apiUrl string The URL of the SalesForce API you want to be used. It is provided by SalesForce within your application settings.
apiVersion string Which API version you need to be used.
company string Which from your SalesForce application companies you need to be used. Should exist in your SalesForce.com application.
token string Provided by your SalesForce application configuration.
sfAccountUsername string The username of the SalesForce.com account to be used for interaction with SalesForce system. Note: This user will be used as author of the automatically synchronized content, and should have the proper read, write, update and delete permissions.
sfAccountPassword string The password of the SalesForce.com account.

Response

If successful, this method returns a response JSON with the following structure:

{
	"timestamp": "2014-03-03T23:20:23Z",	
	"success": true,
	"message": "connection successfully established!",
	"errors":[],
	"object": {}
}

The general response properties are described on the Response format page. Here are the list of the specific properties for this method.