Task Management deployment
The Task Management component is a standalone application that offers an efficient and scalable task management for Sense/Net ECM (or any other 3rd party client application).
Before reading this article, please take a look at the main Task Management article for information about the components described here.
This article is for operators about deploying and maintaining the Task Management component. Developers may take a look at the following article about extending the Task Management framework with custom tasks.
Deploying the component
As the Task Management application is a standalone component, it has its own install package that contains the following items:
- the central web application
- the service that keeps the agents alive
- the agent tool
As you can see on the architecture diagram below, it is advisable to deploy the central web app on one machine (it does not consume much resources) and the service and agent tools on a different (possibly virtual) agent machine (or machines) that are dedicated to this purpose. Resource needs depend on the resource consumption of the executor tools (e.g. whether they need more CPU, RAM, or both).
The install package is a web deploy package that you can install through IIS Manager. You have to do the following:
- Right click on the webserver root and select "Add Website...".
- Fill the necessary properties and create the site.
The url components (Host name and Port) are particularly important here. In a production environment this always should be a 'named url', e.g. taskmanagement.example.com. In a local development environment it is OK if you use localhost and simply assign a unique port number here. It can be a number of your choice, just make sure that no other site uses the same port. Make note of the url you constructed here, you will need it later during configuration in the following cases:
- Sense/Net ECM connects to the task management web application using this url
- task agents will also connect to the task management web using this url
- Configure the app pool identity to be a user (usually a domain user account) that has permissions for the database.
- Right click on the new site and select Deploy / Import Application, and select the package you received as an Enterprise customer.
- Please leave everything as-is and simply proceed to the Next page.
- On the database dialog page make sure that the "SQL Database" option is selected. Click "Next".
- Please install the package as a full site (leave the first text box empty).
- Provide a connection string to your database server:
- the first one will be added to the web.config of the task management web app to connect to the task database
- the second will be used only by this web deploy session to actually create the task database
- Ignore the warning about deploying into the root and hit OK
The installed application's web folder will contain a TaskManagement subfolder, containing the Windows service (SenseNetTaskAgentService.exe) and the task agent tool (SenseNetTaskAgent.exe). There is also a TaskExecutors subfolder here which is empty as of now.
You have to configure the agent: this is where you will need the url of the Task Management website you installed previously.
Deploying executor tools
Task executor tools are not part of the task management install package. We ship them with Sense/Net ECM, so you will find them in the web folder of Sense/Net ECM after you installed the product:
- <Sense/Net ECM webfolder>\TaskManagement\TaskExecutors
If you do not have Sense/Net ECM installed yet, do not worry! You can copy executors later - just do not forget to restart the service (see next chapter) after you did so.
Please copy all the available task executor tools (their folders) from the Sense/Net web folder to the TaskExecutors subfolder of your Task Management website. You should have the following folder structure at the end:
Deploying to agent machines
If you are deploying to a production environment, this is the point where you should copy the TaskManagement subfolder (containing the service, the agent and all the executors, seen on the screenshot above) to the agent machines. If you are just evaluating the product, you do not have to employ agent machines, you can simply register the service from where it is located now, from the task management website you installed above.
A dedicated agent machine is a Windows Server (2008 or above), usually a virtual machine. You have to copy the TaskManagement subfolder (prepared above) manually to all agent machines. An agent machine will run the windows service which will keep the configured number of agent processes alive. Check the task agent article for details about task management component.
- Copy the TaskManagement subfolder to all agent machines to any location. This folder is the only item to deploy to an agent machine.
Register the service
- Register the service from command line
- open a command line prompt as an administrator
- go to your .Net Framework directory (by default C:\Windows\Microsoft.NET\Framework64\v4.0.30319)
- execute the following command: installutil c:\...\taskmanagement\TaskManagement\SenseNetTaskAgentService.exe
- Set the service to be executed in the name of an administrator user, and start the service (in Services app in Windows)
You should see the service process and the configured number of agents running in Windows Task Manager:
Configuration and maintenance
In this section we list all the configurable values and provide best practices for operating this system.
You can find the settings for task management in the following settings file in the Content Repository:
You have the following options there:
- TaskManagementUrl: the url by which the portal will access the Task Management web application that you deployed above (e.g. https://taskmanagement.example.com) for registering tasks.
- TaskManagementApplicationUrl: the base url of your client application (in our case the url of Sense/Net ECM itself) that will be used by the task management application for callbacks (e.g. finalizing tasks).
- TaskManagementAppId: this is an identifier that must be unique among the client applications that connect to the same Task Management web application. Please set this manually to a value that is unique in your environment (e.g. SenseNet.Test for the test server and SenseNet.Production for the production server).
The Task Management application identifies client applications based on this identifier. Please make sure that you have set this manually to a unique value in all your Sense/Net ECM instances, otherwise you may see unknown tasks on your task monitor page.
For developers: optionally you may modify the behavior of the Task Managment framework with the following web.config key:
- TaskManager: you may configure a custom task manager class here to customize registering and finalizing tasks. See the details here.
Task Management web application
On the web server you have to make sure that the WebSocket protocol is installed so that SignalR (that we use for agent-web communication) can operate correctly.
Client application authentication
You have the following options in the web.config of the central web application:
- taskManagement/appAuth: the usernames/passwords for every client application (in our case: a Sense/Net ECM instance). They are used for authentication when the Task Management web application calls the callback methods of client applications (e.g. task finalizers, security checks). See an example in the Authentication section below.
An exact mirror of these values are stored in the config file of the Task Agent tool, see below.
Network load balancing
If you want to deploy Task Management web in a load balanced (NLB) environment, you have to set the following configuration to true in the web.config:
- SignalRSqlEnabled: a value stating that you want to enable SQL backend for SignalR (true/false).
Connection strings in the web.config:
- TaskDatabase: tasks are saved into the database and removed after they were completed. This connection string is mandatory.
- SignalRDatabase (optional): when you use multiple web servers, SignalR needs to store its messages in the database. By default this is the same as the task database above, but you can store these records in a completely different database if you want to. This is absolutely optional even in an NLB environment.
Task Agent Service
The service config file (SenseNetTaskAgentService.exe.config) contains the following option:
- TaskAgentCount: the number of running agents. After starting the service, you should see the given number of agent tools running in Windows task manager (default: 3).
The number of agents per machine depends on the environment and the characteristics of the task executors. We suggest you start with the default value and then try to scale up or down your environment: for example use a higher number of virtual machines or increase the number of agents per machine instead.
The agent has its own configuration file (SenseNetTaskAgent.exe.config) containing the following options:
- taskManagement/appAuth: the usernames/passwords (for every client application) passed to the executors. The agent itself does not use these values. They will be used by the executors to authenticate themselves on the appropriate portal. See an example in the Authentication section.
- TaskManagementUrl: the url by which the agent will access the Task Management web application (e.g. https://taskmanagement.example.com).
- UpdateLockPeriodInSeconds: time interval for refreshing the lock on the executing task (default: 15).
- ExecutorTimeoutInSeconds: maximum executor inactivity (default: 30).
- HeartbeatPeriodInSeconds: time interval for sending heartbeat messages to the task management center so it can monitor the status of the agent (default: 30).
The agents will connect to the Task Management web application using basic authentication, using the username and password provided in this configuration file. So it is advisable to protect the web application with SSL/TLS.
In this section we list a couple of issues you may encounter during and/or after installation.
Performance counter cache in the registry
The task agent service starts the agent exe correctly, but the agent crashes immediately. In the event log (SenseNet or SnTask section) you may find the following error:
System.InvalidOperationException: Cannot load Counter Name data because an invalid index was read from the registry.
Please rebuild the performance counter log in the registry using the following command line tool (as an administrator):
C:\Windows\system32>lodctr /r C:\Windows\system32>winmgmt.exe /RESYNCPERF
Or in case of a 64-bit system:
C:\Windows\SysWOW64>lodctr /r C:\Windows\SysWOW64>winmgmt.exe /RESYNCPERF
Please restart the task agent service and check whether the agent tools are still crashing.
The task agent service starts the agent exe correctly, but the agent crashes immediately. Or maybe the agent starts correctly but when uploading a document to the portal, preview generation does not start (e.g. you see a Pending state on the Task Monitor page).
There is a possibility that this is a file system permissions issue - but no errors in the event log (Sense/Net, SnTask or Application). Please make sure that you execute the service in the name of an administrator user. As a test, please start the task agent tool manually (by double-clicking the SenseNetTaskAgent.exe), as an administrator user. If that starts working and generating preview images correctly, than this is most likely a permission issue with the user set up for the service. Please make sure that it is put into the local Administrators group.
Content Repository permissions
On the UI you see that preview generation starts for a document, you see the loader, but no images are generated.
First try to to hit F5, maybe it is just a client-side issue. If that doesn't help, please check that the administrator user configured for preview generation (builtin\admin by default) has all the necessary permissions. The best solution is to make sure that the Administrators group has all permissions (including Save, Add new, Take ownership and Set permissions) for the workspace or library in the Content Repository.
If you are using Nginx for load balancing the Task Management web, there is a possibility that you encounter the following issue.
There are 400 Bad request errors in the SnTask event log.
Please add the following headers to the requests made by the agents toward the Task Management web application:
proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade";
SignalR SQL errors
You may see SQL-related SignalR errors in the SnTask event log after deploying Task Management in an NLB environment, with SQL SignalR switched to true in the web.config.
You may try to delete the following 3 tables from the SQL database manually. Do not worry, SignalR wil re-create them after you restarted the Task Management web site.
SignalR.Messages_0 SignalR.Messages_0_Id SignalR.Schema
There are multiple components in this system that needs to be connected. This means we will have to deal with multiple authenticated connections. We describe them all in this section.
Task Management web app
Currently there is no authentication between the agents and the central task management web app, as their should be in the same internal network that is inaccessible from outside.
The client application (in our case a Sense/Net ECM installation) REST API needs to authenticate requests. As the Task Management app is capable of executing tasks for multiple client applications, we need to configure a list of usernames/passwords, for every registered app id. We need to configure this list in two places:
- the task management web.config (for client app callbacks)
- the task agent tool config (for passing user credentials to executors, who may also want to access the Sense/Net ECM application, e.g. for downloading documents)
In both configuration files above you can use the following format for user credentials:
<taskManagement> <appAuth userName="" password=""> <add appId="app1" userName="dom\u1" password="pw1"/> <add appId="app2" userName="dom\u2" password="pw2"/> </appAuth> </taskManagement>
The users defined in these config sections have to have full permissions for the content you want to generate preview images for. Please note that you can define either an appid-specific user (as recommended) or use a global one (set on the appAuth node), if you have the same user with the same password in multiple environments (use the latter option only in dev environments please). If you change the password of any of these admin users on the portal, you will need to make the same change in these config files too.
If no username and password is provided, the agents and executors will try to connect to the portal using NTLM (Windows) authentication.
- Task Management
- Task Management - for Developers
- Content Repository
- OData REST API
- How to create a custom OData action
- Generic Sense/Net OData action