Its one thing to learn how to develop components on the community platform, but none of that is really helpful unless you know how to get started. This guide will give you some advice on how to setup your first community project. This includes the tools you will need to develop on the platform as well as some best practices you can use to ensure success.
[toc]
What Tools Do I Need?
Here is the basic list to get you started:
- A Windows Based PC. Your windows version should be capable of installing and running Internet Information Services (IIS).
- Visual Studio 2013 or Higher. It should be an edition able to work with asp.net web applications and class libraries. If you do not have Visual Studio there is a free community edition meant for individuals, open source developers and small professional teams. Be sure to review the license terms.
- SQL Server 2014 or Higher installed locally on your development PC. For local development SQL Server express is acceptable.
- Verint Community running locally on your windows development PC. This involves following all the installation steps including making sure you have installed IIS locally. Becasue this is a development machine all components can be installed on your single PC, though you may consider making the Job Service and Tomcat services manual services that you start when doing active development to preserve system resources.
Installing any of these tools is beyond the scope of this topic. If you are unfamiliar with any of these please refer to the manufacturer's documentation. It is also assumed that you know to work with projects in Visual Studio
Enable Developer Mode
It is highly recommended that you enable Developer Mode on the local community you just installed. This enables many advanced development features in the community itself that you may find useful as you get more involved in your custom development.
Simplified Job Service
The job service is a required component of Verint Community however when developing on a local development machine a separate service adds overhead and making debugging challenging. There are 2 alternatives to executing jobs over the windows service you can use for development only, never in production. This includes executing the job service manually from its executable or you can force all jobs to run in the community web process.
Run The EXE Manually
Inside the job service is Telligent.Jobs.Server.exe which is the main executable file that drives the job service. You can double click this file to execute it and it will begin to run in console mode. This approach is helpful as it shows jobs starting and will display any errors in the console. This does require that you have setup the job service correctly per the documentation as it pertains to connectionstrings.config, communityserver_override.config and permissions.
Run Jobs in the Web Process
You can also forgo the job service and allow jobs to be run as part of the web process. This is helpful when you need to debug custom jobs since you can attach your debugger to the web process as you would for other in-process code. To force jobs to run in process add the follwing to the <appSettings /> node of the community web.config:
<add key="RunJobsInternally" value="true" />
Be sure you have no other instances of the job service running via a windows service or the executable running in console mode. Also be sure not to deploy the web.config to production with this setting present.
Setting Up a Project
The project type we are going to be using is the Class Library project type in Visual Studio. This is because you will generally only be creating a compiled assembly(.dll) to be deployed to your community. You can still however add supplementary type files to this type of project like images or scripts making it the most ideal choice. It is also important to note a couple of things not to do when it comes to starting a new project.
Do not try and open your Verint Community as a Website in Visual Studio. Its not designed to be a website in this specific sense and when you try to build it you can have issues. Generally you will not be manipulating any files in Verint Community only adding new files, mostly assemblies.
Do not use runnable applications like console applications or new web applications. This to some extent includes test projects depending on the type of test. If you are an avid test driven developer this may set off an alarm but it shouldn't, in the Test Driven Development topic we address this. The main reason for this is all community APIs and components require they are running in a very specific context in order to function. There is no supported method of creating this context outside of a running community site so any community APIs can only run within the community application.
Open Visual Studio and start a new project of type Class Library.
Adding References
To use the community In-Process API, or create custom Plugins your project will need references to certain Verint Community libraries (.dlls). Which ones you need vary by what you are building so you should consult the appropriate topic for what you are currently working on or reference the Developer Documentation for a more technical reference.
In order to keep your project tidy and easily update your Verint Community DLL references later, it is a good idea to create a References or similarly named folder in your solution folder. Then from your Verint Community site's bin folder, locate and copy the .dll files you require for the components you are building to this new folder. Do not reference Verint Community DLLs to the site's bin folder directly.
While not by any means an inclusive list, most of the common Verint Community DLLs used for the majority of custom components are:
Telligent.Evolution.Components.dllTelligent.Evolution.Api.dllTelligent.Evolution.Core.dllTelligent.DynamicConfiguration.dll(If you are making Configurable Plugins)Telligent.Evolution.ScriptedContentFragmentExtensions.dll(When building widget server components like Factory Default Widget Providers)
Once all these files have been copied to the References folder, add references to these Verint Community.dll files in your Visual Studio project by browsing to them. You should also add a .NET framework reference to System.Web as many of the components require web tooling.
You are now ready to start your first component by adding a new class and going from there. It is also helps to keep things organized within the project. For example you can keep all your Plugins together in a folder and if you expose your own API you can keep that in an API folder. Additionally if this project will contain more than just community components it might be worth keeping everything together in a community folder and organized there or simply create a second project. If you already have code that is shared between multiple applications and all you want to do it create components to tie it into community it is suggested that you create the integration in a separate project and reference your shared library.
Using the Right APIs
When you add references to community DLLs you gain access to our supported set of APIs and extensibility points but you also have access to internal APIs that you should not use in your code. It is important to only use supported, documented APIs for several reasons:
- Documented and supported APIs are guaranteed to not break across upgrades. This means if you are on a version of community and upgrade, any code you wrote using a documented and supported API will work in the new version. The only exception to this may be if you are on an old version and upgrading several major versions and in one of the versions in between an API was deprecated. We provide at least 2 major versions notice before an API is removed.
- Documented and supported APIs are secure. User permissions are applied when getting data from these APIs which ensures that a customization will not accidentally provide access to sensitive data.
- Documented and supported APIs are reviewed for performance. This doesn't mean that if you use these APIs all your code will perform well. It simply means that an individual API when used appropriately should perform to our standards. For example when using the API paged lists will only return 100 items maximum to prevent loading whole data sets into memory. There still is a reasonable expectation that the implementation of these APIs is done in a performant way by the implementing developer.
It is important to be able to identify these supported APIs. The easiest way is via documentation. We document all of our supported APIs in our API Documentation. Additionally the topics in this training curriculum all outline safe API usage.
The other method is all of our supported APIs share a namespace pattern. All APIs have a specific namespace naming pattern that contains 2 key pieces of information. The first is the word Extensibility. If a namespace contains the word Extensibility it is considered an API. Here is an example:
namespace Telligent.Evolution.Extensibility.Version1
{
public interface IPlugin
{
//...
}
}
Because IPlugin is in the Telligent.Evolution.Extensibility.Version1 namesapce, it is a supported API. Another key piece of data in the namespace is Version1 as this is the way we denote what version of the API it is. If for some reason we wanted to change IPlugin we would create a new IPlugin in the next version in Telligent.Evolution.Extensibility.Version2 before removing version 1 in a few versions. Version is not required to be considered an API, only the word Extensibility.
If the namespace lacks the word Extensibility then it is not a supported API and you should not use it in your code. Look for an API equivalent or contact support for more help.
Custom Database Schema
There are many times when you need custom data structures for your application. It is acceptable to add custom tables and stored procedures to the Verint Community database with a few guidelines:
- No custom table should have a defined foreign key relationship to a core Verint Community table. You can still store a reference in your table, like an identifier to content but that integrity should be enforced by your application not at the database level.
- There should be no custom SQL written against Verint Community tables. This means no manipulating data in core tables and no selecting data from the database tables directly. If there is an acceptable database operation it will be documented as an API similar to other APIs.
If your custom data can live in another database, that is always the best solution since it does create a separation that makes upgrades safer and is less likely to impact performance. If that isn't feasible for some reason you can create things in the Verint Community database. You should either store objects in their own schema or provide objects with some sort of prefix that is separate from the Verint Community schema but meaningful to your situation. For example if you were writing a survey application something like tbl_surveys_Survey would be ok.