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

Return to Top



Change Log

Changes for each release can be found on the Change Log page.

Return to Top



Usage

This section provides basic usage instructions for the package.

Return to Top



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.

Return to Top



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:

Return to Top



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
    }
}

Return to Top



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)

Return to Top



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.

Khoros Environment Variables

Environment Variable

Description

Example

KHOROS_URL

The base URL of the environment

https://community.example.com

KHOROS_TENANT_ID

The Tenant ID associated with your environment

abcde12345

KHOROS_DEFAULT_AUTH

The default authentication method you wish to use

session_auth

KHOROS_OAUTH_ID

The Client ID utilized by the OAuth 2.0 authorization grant flow

FXXXXXXb7owXXXXXXo+jFlPXXXXXXjZcWQXXXXXX6bo=

KHOROS_OAUTH_SECRET

The Client Secret utilized by the OAuth 2.0 authorization grant flow

1XXXXXX+/kZXXXXXXZZ9u1B5+1uXXXXXXfJCeOszYw=

KHOROS_OAUTH_REDIRECT_URL

The Redirect URL utilized by the OAuth 2.0 authorization grant flow

http://redirect.community.example.com/getAccessToken

KHOROS_SESSION_USER

The username to use with Session Key authentication

apiuser

KHOROS_SESSION_PW

The password to use with Session Key authentication

Ch@ng3M3!

KHOROS_PREFER_JSON

Boolean string indicating if JSON responses are preferred

True

KHOROS_LIQL_PRETTY

Boolean string indicating if reader-friendly formatting should be used

False

KHOROS_LIQL_TRACK_LSI

Boolean string indicating if queries should be captured in Community Analytics search reports

False

KHOROS_LIQL_ALWAYS_OK

Boolean string indicating if all responses should return a 200 OK status code

False

KHOROS_TRANSLATE_ERRORS

Boolean string indicating if errors in API responses should be made more relevant where possible

True

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")

Return to Top



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
)

Return to Top



License

This package falls under the MIT License.

Return to Top



Reporting Issues

Issues can be reported within the GitHub repository.

Return to Top



Roadmap

Upcoming improvements to the library can be found in the following locations:

Return to Top



Additional Resources

Additional resources for leveraging the Community APIs can be found in the official Khoros Developer Documentation.

Return to Top



Disclaimer

This package is considered unofficial and is in no way endorsed or supported by Khoros, LLC.

Return to Top