Introduction¶
The khoros library acts as a Python software development kit (SDK) to administer and manage Khoros Communities (formerly Lithium) online community platforms.
Installation¶
The package can be installed via pip using the syntax below.
pip install khoros --upgrade
You may also clone the repository and install from source using below.
git clone git://github.com/jeffshurtliff/khoros.git
cd khoros/
python3 setup.py install
Change Log¶
Changes for each release can be found on the Change Log page.
Usage¶
This section provides basic usage instructions for the package.
Importing the package¶
Rather than importing the base package, it is recommended that you import the primary khoros.Khoros
class using the syntax below.
from khoros import Khoros
This recommendation is because the best practice is to use the name khoros
when naming your object instance.
Initializing a Khoros object instance¶
The primary khoros.Khoros
object serves many purposes, the most important being to establish a
connection to the Khoros Community environment with which you intend to interact. As such, when initializing an
instance of the khoros.Khoros
object, you will need to pass it the community URL, the credentials
it will use and related information so that the connection can be established.
The khoros.Khoros
object can be initiated in three different ways:
Passing the information directly into the object¶
The community and connection information can be passed directly into the khoros.Khoros
object when
initializing it, as demonstrated in the example below.
khoros = Khoros(
community_url='https://community.example.com',
session_auth={'username': USERNAME, 'password': PASSWD}
)
Alternatively, configuration settings can be passed at once using the options
argument in the
khoros.Khoros
class, as shown below.
my_settings = {
'community_url': 'https://community.example.com',
'community_name': 'mycommunity',
'auth_type': 'session_auth',
'session_auth': {
'username': USERNAME,
'password': PASSWD
}
}
Leveraging a “helper” configuration file¶
As an alternative to passing the connection information to the khoros.Khoros
class in the ways
demonstrated above, a “helper” configuration file in yaml or
json format can be leveraged instead and passed to the
khoros.Khoros
class when initializing the object.
This is an example of how the configuration file would be written:
# Helper configuration file for the khoros package
# Define how to obtain the connection information
connection:
community_url: https://community.example.com/
tenant_id: example12345
# Define the default authentication type to use
default_auth_type: session_auth
# Define the OAuth 2.0 credentials
oauth2:
client_id: FLFeNYob7XXXXXXXXXXXXXXXXXXXXZcWQEQHR5T6bo=
client_secret: 1n0AIXXXXXXXXXXXXXXXXXXXX1udOtNaYnfJCeOszYw=
redirect_url: http://redirect.community.example.com/getAccessToken
# Define the session key authorization information
session_auth:
username: serviceaccount
password: Ch@ng3ME!
# Bulk Data API connection information
bulk_data:
community_id: example.prod
client_id: ay0CXXXXXXXXXX/XXXX+XXXXXXXXXXXXX/XXXXX4KhQ=
token: 2f25XXXXXXXXXXXXXXXXXXXXXXXXXa10dec04068
europe: no
# Define the preferred format for API responses
prefer_json: yes
# List the enabled discussion styles in the environment (blog, contest, forum, idea, qanda, tkb)
discussion_styles:
- blog
- contest
- forum
- idea
- qanda
- tkb
The file can then be referenced using the helper
argument when initializing the object instance, as shown below.
HELPER_FILE = "/path/to/helper.yml"
khoros = Khoros(helper=HELPER_FILE)
Utilizing environment variables¶
This third method of initializing a Khoros object instance is definitely the easiest, as it allows you to call
upon the khoros.Khoros
class without passing any arguments, as shown below.
from khoros import Khoros
khoros = Khoros()
This is accomplished by defining environment variables within your Operating System, either through the
graphical UI, the command-line or within the Python
IDE using the os
module and
adding entries to the
os.environ
dictionary, as shown below.
import os
os.environ['KHOROS_URL'] = 'https://community.example.com'
The environment variables leveraged in the khoros
library are listed below.
Environment Variable |
Description |
Example |
---|---|---|
KHOROS_URL |
The base URL of the environment |
|
KHOROS_TENANT_ID |
The Tenant ID associated with your environment |
|
KHOROS_DEFAULT_AUTH |
The default authentication method you wish to use |
|
KHOROS_OAUTH_ID |
The Client ID utilized by the OAuth 2.0 authorization grant flow |
|
KHOROS_OAUTH_SECRET |
The Client Secret utilized by the OAuth 2.0 authorization grant flow |
|
KHOROS_OAUTH_REDIRECT_URL |
The Redirect URL utilized by the OAuth 2.0 authorization grant flow |
|
KHOROS_SESSION_USER |
The username to use with Session Key authentication |
|
KHOROS_SESSION_PW |
The password to use with Session Key authentication |
|
KHOROS_PREFER_JSON |
Boolean string indicating if JSON responses are preferred |
|
KHOROS_LIQL_PRETTY |
Boolean string indicating if reader-friendly formatting should be used |
|
KHOROS_LIQL_TRACK_LSI |
Boolean string indicating if queries should be captured in Community Analytics search reports |
|
KHOROS_LIQL_ALWAYS_OK |
Boolean string indicating if all responses should return a |
|
KHOROS_TRANSLATE_ERRORS |
Boolean string indicating if errors in API responses should be made more relevant where possible |
|
If you are leveraging this library on a macOS or Linux operating system (e.g. Ubuntu Server) then you can simply
add the environment variables you wish to define to either the /etc/environment
file if you wish to apply
them to all users, or to your user’s ~/.bashrc
file for them to only apply to your user.
# Define environment variables for Khoros
KHOROS_URL='https://community.example.com'
Note
You will generally need to log out and log back in for the changes to take effect.
If you are leveraging this library on a Windows operating system (e.g. Windows 10) then you can add environment
variables for your user via the Command Prompt (i.e. cmd.exe
) or PowerShell.
Note
Using either of these two methods, you can add the environment variables using an interactive terminal
window or using a batch/script file. (Files should use the .bat
or .cmd
extension for the
Command Prompt and .ps1
for PowerShell.)
Command Prompt
@echo off
echo Defining the KHOROS_URL environment variable...
setx KHOROS_URL https://community.example.com
echo.
PowerShell
"Defining the KHOROS_URL environment variable..."
[Environment]::SetEnvironmentVariable("KHOROS_URL", "https://community.example.com/", "User")
Interacting with the Community APIs¶
Once the khoros.Khoros
object instance has been initialized, it can be leveraged to interact
with a Khoros Community environment in many ways, which will be fully documented shortly in the
documentation. The example below demonstrates how
a search can be performed using LiQL to return information from the environment in
JSON format.
response_json = khoros.search(
select_fields=('id', 'view_href'),
from_source='messages',
where_filter=('style', 'tkb'),
order_by='last_post_time',
limit=5
)
License¶
This package falls under the MIT License.
Reporting Issues¶
Issues can be reported within the GitHub repository.
Roadmap¶
Upcoming improvements to the library can be found in the following locations:
Additional Resources¶
Additional resources for leveraging the Community APIs can be found in the official Khoros Developer Documentation.
Disclaimer¶
This package is considered unofficial and is in no way endorsed or supported by Khoros, LLC.