Your online community is a great way for your members and customers to interact with your organization, and their user profile should be the centerpiece of their online experience: It should be the main place they visit to see the contributions, history, and activities that represent their journey.
By default, a user's profile Summary page lists the activities (e.g., writing a blog, replying to a Discussion) that they've completed on your community. You can add to this by using the external-activities functionality to also include activities that users complete on an external platform (such as completing an LMS-based training course, attending events where registration was done through a third-party registration system, and publishing journal articles via a journal-publishing system).
This functionality requires a product license and passing the information via our API. Once received, you can configure external activities to show on users' profiles on the External Activity Types page in the Admin interface.
IMPORTANT: API documentation:
- Canadian customers visit https://api.onlinecommunity.ca/
- All other customers visit https://api.higherlogic.com/
The best part is this data can also be leveraged via Automation Rules to award badges, send email, and add users to communities. Additionally, the data can be passed to other systems through another Higher Logic module, Activity Sync, so that you can forward your data to your AMS/CRM or other systems to which you may not be integrated.
The Higher Logic platform can accept a variety of activities from external systems. Before passing external activities via the API to Higher Logic, you or your fellow Super Admins must define external activity types in the Admin interface.
How it works
The remainder of this article details the configuration and use of the Higher Logic External Activity API Integration methodology. The first step is defining one or more external activity types within the Higher Logic platform. Each type will have an activity name, unique keys, point values, and the various date, text, and number fields that will be associated with an activity created within your community. These configurations are unique to your community.
After an activity type has been defined, it can be referenced in API calls to send these activities to your community. For example, if an activity took place in an online voting platform, an external activity could be created for the VOTING type, with the name of the ballot stored in one of the text fields and when the vote was cast in a date-time field.
To set up an external activity type:
- In the Admin Toolbar, click Admin.
- Navigate to Settings > External Content > External Activity.
NOTE: The columns on this page are described in detail in Add / Edit an External Activity Type, which details how to configure external activity types.
- The list defaults to the Active (external activity types) view. Click the Active dropdown and select:
- Inactive to filter on just those external activity types or
- Show All to populate the list with all of the external activity types in your community.
- Use the Yes/No toggles in the Show in Summary, Include in Activity Sync, and Active columns to manage your external activity types.
TIP: The record count above the table shows your total external activity types. Use the page navigator below the table to view additional external activity types in your community.
Edit the IAM Key
The IAM Key helps you control access to AWS resources. You use it to control who is authenticated (signed in) and authorized (has permissions) to use these resources.
- Click Edit Key.
- On the dialog, use the Regenerate buttons to regenerate a new key, a new password, or both.
TIP: If you generate a new password, be sure to note it somewhere before saving.
- Click Save.
Delete an External Activity type
- Click the down arrow to the right of an external activity type and select Delete.
- In the dialog, review the warning and click Delete to continue; otherwise, click Close.
- Review the list to ensure your external activity type is no longer listed.
Add / Edit an External Activity type
- Click Create to add an external activity type.
- Click Edit to the right of an external activity type.
NOTE: Both of these options take you to the Add/Edit page. The fields for the add and edit options are identical, with the obvious distinction being that they're blank when you are adding an external activity type. The information in this section is applicable to adding and editing.
The Details section
Use the fields and options in this section to configure the basics of the external activity type. Scroll down and click Save to preserve your selections.
NOTE: In the table, bold text indicates required fields.
Field | Description |
---|---|
Name | Name of the external activity type, such as "Blog." |
Plural Name | Plural form of the value specified above (e.g., the plural of "Blog" is "Blogs"). It will appear as the list heading on the user profile's My Contributions > Summary page. |
Description | Description of what this external activity type represents. |
Engagement Points Contribution Points Reputation Points Volunteer Points |
Higher Logic tracks these types of points. Users who have this external activity type added to their profile will receive the assigned number of points for completing these activities. |
Legacy Key | Reference key that will insert this external activity type via the Higher Logic API. Vendors can use the same Legacy Key across clients to keep their integration standard. |
View Permissions | Select a view permission setting to control who can see this external activity on individual profiles. Refer to View Permissions, below, for information on these settings. |
Show in Summary | Controls whether this external activity type displays on a user's My Contributions > Summary page. For example, registering for a course might not warrant showing on a profile, but completing a course might. If an external activity type is not shown in the Summary, it can still be used in Automation Rules. |
Include in Activity Sync | Controls whether this external activity type is written back to your AMS/CRM. This option is applicable only if you license the Activity Sync module. Also, note that Activity Sync is only supported with some AMS/CRM platforms. See Activity Sync for a list of supported AMS/CRM platforms. |
Active | Controls whether this external activity type is active. If not, the external activity type cannot be inserted via the API, will not show on users' profiles, and cannot be used in Automation Rules. |
View Permissions
You can select any of the following view permissions (or a combination of them) to limit who can see external activities on individual profiles.
- Public places no restrictions on who can view the external activity.
- Authenticated requires that a user be logged in to your community.
- Member requires that a user be a member of your community.
NOTE: This setting is recommended.
- The last group is a listing of all your Higher Logic-managed and AMS-managed security groups. Select from this group to limit view permissions to users in specific security groups (created and listed in Users > Security Groups; see Manage Security Groups).
NOTE: After this section has been completed and saved, you can add display data about the activity.
Add Display Data
By default, the API provides external activities with a name and description. You can further define an external activity with the fields in the Additional Display Data Configuration section. This is beneficial for those external activities that appear on user profiles as a type of contribution in the user’s contributions list.
You can configure additional data to appear as columns in the list or on the activity preview detail page. You can add up to nine additional columns (3 text, 3 date, and 3 numeric) per external activity type.
After an activity type has been created, it can be used in API calls to add external activities to a user’s profile.
NOTE: In the table, bold text indicates required fields.
Field | Description |
---|---|
Name | A descriptive indicator of the data that this field presents. |
Data Type | Which data field this information should be stored in: Date 1, 2, or 3; Number 1, 2, or 3; Text 1, 2, or 3 |
List Position | The column position in the table on the Summary page of a user's profile. |
Display Position | The display position on the detail page from the Summary page of a user's profile. |
Code | An optional code that can be used to map to a value in the external system. |
NOTE: If you have developed a standard set of External Activity Types, a script can be created to set them up, rather than having to manually create them. For more information, create a case.
Frequently asked questions
Q: What is the difference in the three Data Types (text, date, numeric) of the Additional Display Data Configuration section? Why wouldn't I just put the information in the text fields?
A: While dates and numbers can be stored in the text fields and displayed on the profile in that way, Automation Rules allow comparisons to be done on these data types, with numbers greater or less than and dates that happened in the last number of days. The current queries for External Activities are:
- 'has a specified type of activity that was added within the past specified number of days'
- 'has a specified type of activity with a title that contains the specified text that was added within the past specified number of days'
- 'has a specified type of activity with a description that contains the specified text that was added within the past specified number of days'
- 'has a specified type of activity with a Date1 within the last specified number of days that was added within the past specified number of days'
- 'has a specified type of activity with a Date2 within the last specified number of days that was added within the past specified number of days'
- 'has a specified type of activity with a Date3 within the last specified number of days that was added within the past specified number of days'
- 'has a specified type of activity with a Number1 greater than the specified value that was added within the past specified number of days'
- 'has a specified type of activity with a Number2 greater than the specified value that was added within the past specified number of days'
- 'has a specified type of activity with a Number3 greater than the specified value that was added within the past specified number of days'
- 'has a specified type of activity with a Number1 less than the specified value that was added within the past specified number of days'
- 'has a specified type of activity with a Number2 less than the specified value that was added within the past specified number of days'
- 'has a specified type of activity with a Number3 less than the specified value that was added within the past specified number of days'
- 'has a specified type of activity with a Number1 equal to the specified value that was added within the past specified number of days'
- 'has a specified type of activity with a Number2 equal to the specified value that was added within the past specified number of days'
- 'has a specified type of activity with a Number3 equal to the specified value that was added within the past specified number of days'
- 'has a specified type of activity with a Text1 that contains the specified text that was added within the past specified number of days'
- 'has a specified type of activity with a Text2 that contains the specified text that was added within the past specified number of days'
- 'has a specified type of activity with a Text3 that contains the specified text that was added within the past specified number of days'
Calling the External Activity API
Higher Logic's API has a variety of methods that allow other applications to interface with community data and functionality. While information about the full API is outside the scope of this article, visit the appropriate link below to learn more about other methods and authentication.
IMPORTANT: API documentation:
- Canadian customers visit https://api.onlinecommunity.ca/
- All other customers visit https://api.higherlogic.com/
To access the API, a vendor will need an IAM Key and password. These can be created at the top of the External Activity Types page. If you would like to have different IAM Keys associated with different vendors, create a Support case.
WARNING: Be careful with IAM Keys and passwords because they can give access to your community data to anyone who has them. Keep your IAM Keys and passwords private and only share them securely.
The External Activity methods in Higher Logic's API allow external activities to be created, updated, and deleted. To create an external activity, use the method provided on the Higher Logic create external activity page.
Unless required, fields do not need to be included in the call.
After an external activity has been created, you will use the LegacyActivityKey that is supplied or ExternalActivityKey (returned when the Create method is called) to make use of the Update and Delete methods. You don't have to update an external activity once created, but if you do, make sure you resend the full details of the activity, even if they aren't being changed by the update. Omitted values will be set to null.
More information about these methods can be found in our API documentation; visit the link below appropriate for you:
IMPORTANT: API documentation:
- Canadian customers visit https://api.onlinecommunity.ca/
- All other customers visit https://api.higherlogic.com/