Download

Setup & First Steps
with Exply

1. System Requirements

  • Java Version 8 (newer versions will not work currently)
  • Minimum 4GB RAM for the server
  • Root Access for installation

2. Setup

2.1 Setup Exply On Premises (Self-Hosted)

2.1.1 Installing Exply on Debian

Installing Exply on Debian is actually the easiest way and can be done by using the following command:

  1. dpkg -i exply-stable.deb
  2. systemctl enable exply-server.service
  3. systemctl start exply-server.service
  4.  
  5. # for logs
  6. journalctl -u exply-server.service

Make sure that you have JAVA version 8 installed and active.

  1. # only if your Java version is not 8
  2. sudo apt install openjdk-8-jre-headless
  3. sudo update-alternatives --config java

After you started the Exply Server Service, you should be able to login using a web-browser and visit: localhost:5050

Continue with the basic Exply Configuration

2.1.2 Installing Exply on Debian-based Linux-distributions like Ubuntu & Knoppix

Installing Exply on Debian-based Operating Systems (OS) is as easy as for Debian itself. Just use the following command.

To see a full list of Debian-based OS check out the following Wikipedia page: Debian-based Linux-distributions

  1. # only if your Java version is not 8
  2. sudo apt install openjdk-8-jre-headless
  3. sudo update-alternatives --config java
  4.  
  5. sudo dpkg -i exply-stable.deb
  6.  
  7. sudo systemctl enable exply-server.service
  8. sudo systemctl start exply-server.service
  9.  
  10. # for logs
  11. sudo journalctl -u exply-server.service

After you started the Exply Server Service, you should be able to login using a web-browser and visit: localhost:5050

Continue with the basic Exply Configuration

2.1.3 Installing Exply on FreeBSD

Unfortunately we have no package for FreeBSD — yet.

Therefore please follow our step-by-step guide:

  1. Install Java 8 (JRE)

  2. Create a new User for Exply

  3. Download latest Exply Tar-Archive

  4. Extract Exply Files

  5. Create an Exply Service

  6. Continue with first Expy configuration

2.1.3.1 Install Java 8 (JRE)

Ubuntu 18.04 LTS is shipped with Java 10. Currently Exply only supports Java 8. Therefore you need to install Java 8 in parallel and set the Java default to 8.

For more information please refer to https://www.digitalocean.com/community/tutorials/how-to-install-java-on-freebsd-10-1

  1. # only if your Java version is not 8
  2. sudo apt install openjdk-8-jre-headless
  3. sudo update-alternatives --config java

2.1.3.2 Create a new User for Exply

  1. sudo su
  2. pw groupadd exply
  3. pw useradd exply -d /nonexistent -s /usr/sbin/nologin -g exply -w no -c "system user for Exply daemon"
  4. pw usershow exply

2.1.3.3 Extract Exply Files

  1. sudo su
  2. cd /var
  3. tar -xzf exply-stable.tgz
  4. chown -R exply:exply exply/

2.1.3.4 Create an Exply Service

  1. search Java8 Home, probably at /usr/local/openjdk8 (if not adjust template for /etc/rc.d/exply below)

  2. append exply_enable="YES" to /etc/rc.conf

  3. create /etc/rc.d/exply with the following content (below)

  1. #!/bin/sh
  2.  
  3. # add the following line to /etc/rc.conf to enable exply:
  4. # exply_enable="YES"
  5. rcvar=exply_enable
  6.  
  7. . /etc/rc.subr
  8.  
  9. name=exply
  10. desc="Exply server daemon, see /var/exply/app"
  11.  
  12. command_start_exply="cd /var/exply/app && JAVA_HOME=/usr/local/openjdk8 EXPLY_DATA_DIR=/var/exply/Data bin/server"
  13. command_args="-P /var/run/${name}.pid -f -t exply-server-daemon -u exply bash -c '${command_start_exply}'"
  14. command="/usr/sbin/daemon"
  15.  
  16. pidfile="/var/run/${name}.pid"
  17.  
  18. load_rc_config $name
  19. run_rc_command "$1"

2.1.3.5 Start Exply Service

service exply start

2.2 Setup Exply for JIRA

After you've downloaded and installed Exply to your JIRA instance, just start Exply from the main JIRA navigation bar.

Setting up Exply for JIRA is as easy as you can imagine. Your JIRA configuration is automatically detected. The only thing you need to do add your Tempo API-Key (security token). Adding your Tempo security token only applies, if you use the Tempo Plugin for JIRA.

Just follow the links provided in the welcome screen. They're leading you directly to your personal Tempo page, where you find your personal security token. Just copy the security token to your Exply for JIRA configuration page and paste it in the corresponding field.

Setting up Tempo and JIRA for Exply
How to configure Exply for JIRA

Wonder how to setup your first widgets? Check out the Dashboards & Widgets-Section below.

3. Before you start - Basic Exply Configuration

On the first start an admin user is created automatically:

username: admin
password: password

We strongly recommend to change the default password.

After you're logged in, you can add more users in the User Management via the menu.

Authentication against external Services

Beside local Exply users we support authentication against:

  • Twitter
  • GutHub
  • Atlassian Crowd

Please contact us at support@exply.io if you want to use one of those services.
Note that you must add the users in Exply in order to set their permissions and configuration.

3.1 Reducing Memory Consumption

By default the main Exply process consumes 1 GB of memory. This is usually a fair trade–off between performance and resource footprint.

If you want to change it you might experience poor performance or out of memory errors. However you can give it a try by editing the exply-server.conf and the exply-server.service. You will find commented placeholders to adjust the memory consumption.

We recommend the minimal and maximal head size to be equal and not more than 50 % of the available memory. NewSize should be 1/3 of the heap size. Be sure to keep the settings in the two files in sync.

exply-server.conf

This file resides in /etc/init with the follow default content.

description "Exply on Premise main server"
start on filesystem or runlevel [2345]
stop on runlevel [!2345]
 
respawn
umask 022
#nice
#chroot /
chdir /var/exply/app/
#limit core <softlimit> <hardlimit>
#limit cpu <softlimit> <hardlimit>
#limit data <softlimit> <hardlimit>
#limit fsize <softlimit> <hardlimit>
#limit memlock <softlimit> <hardlimit>
#limit msgqueue <softlimit> <hardlimit>
#limit nice <softlimit> <hardlimit>
#limit nofile <softlimit> <hardlimit>
#limit nproc <softlimit> <hardlimit>
#limit rss <softlimit> <hardlimit>
#limit rtprio <softlimit> <hardlimit>
#limit sigpending <softlimit> <hardlimit>
#limit stack <softlimit> <hardlimit>
setuid exply
setgid exply
console log # log stdout/stderr to /var/log/upstart/
 
env EXPLY_DATA_DIR=/var/exply/Data
# env JAVA_OPTS="-Xms1024M -Xmx1024M -XX:NewSize=341M -XX:MaxNewSize=341M"
 
exec /var/exply/app/bin/server 

exply-server.service

This file resides in /lib/systemd/system with the follow default content.

[Unit]
Description=Exply on Premise main server
 
[Service]
Type=simple
User=exply
Group=exply
Restart=always
 
Environment="EXPLY_DATA_DIR=/var/exply/Data"
# Environment="EXPLY_DATA_DIR=/var/exply/Data" 'JAVA_OPTS=-Xms512m -Xmx512m -XX:NewSize=170m -XX:MaxNewSize=170m'
 
WorkingDirectory=/var/exply/app/
ExecStart=/var/exply/app/bin/server
 
[Install]
WantedBy=multi-user.target

Depending on your operating system you can adjust the memory allocation in a similar way:
just make sure Exply starts with the correct JAVA_OPTS.

4. How to use Exply

Exply allows you to unlock the value in your data by creating Dashboards which contain Analytics Widgets. 

5. Dashboards

5.1 How do I create a new Dashboard?

After you logged in to Exply you'll see the welcome screen with two main options:

  • Create a Dashboard
  • Open a Dashboard

To create a new dashboard just click the corresponding button on the welcome screen.

Title Screen after logging in to Exply

By clicking "create a dashboard" you'll see the following screen with several options:

Creating a new Dashboard in Exply
  1. The Dashboard Overview shows all your exisiting dashboards (as a list or as tiles). The overview allows you to also quickly create a new Dashboard by clicking the plus-symbol in the bottom right corner.
  2. Giving your dashboard a useful name is essential and best when you choose one that represents the content of the Dashboard. Everyone using it will directly know what he's going to see. Especially when you have a lot of dashboards, this comes in handy.
  3. For the Widget Group name apply the same rules and principles like for the Dashboard name.
  4. The Main Menu gives you direct access to all the like Dashboards, Importer Settings, User Management, Documents & Fields Customization, etc.
  5. You can find the Dashboard options at the top right corner behind the 3-dot menu providing you options to edit, export or delete the Dashboard.
  6. One of the concepts of Exply are the different levels of filtering the data. Every Dashboard and Widget Group has this option. You can add different data filters to limit the shown data, e.g. by project, team member, etc.
  7. The Time Selector widget comes automatically with every new Widget Group, to limit the shown data for a certain time span. Notice: Removing the Time Selecter widget maybe results in really long loading times (browser is maybe not responding for a while), especially when absolutely no other filters are applied.
  8. Widget Group options are available for every Widget Group. They allow you to move them up & down, promote them to a Global Group and duplicate or remove them.
  9. Widgets represent analysis, e.g. logged hours per project, timeline of created issues, and so on. Build and customize your Dashboards by adding new widgets. You can move and scale Widgets as you like.
  10. Sometimes you want to compare several projects, teams or different time spans (this vs last month). Widget Groups can help you to easily achieve this by adding a data filter for the first project to the first Widget Group and the second project to the second Widget Group, and so on. Widget Groups are like Dashboards within Dashboards.
  11. Like explained at number 10
  12. Save your dashboard to let your changes take effect or cancel all changes to discard them.

First of all - it's useful to set an individual dashboard title, f.e. customer name, project name, team name, etc.

That way you instantly know what the dashboard's content is. Especially when you end up having a lot of them, and you will, that's for sure ;-)  Also your customers or project teams will really appreciate the appropriate naming and it makes it way easier to talk about it.

In our example we want to get an overview regarding the project "General Products Website". So we give the dashboard this project name.

The first part of our dashboard shall provide us a quick overview and is named the same way. This also makes it easier for everyone to quickly know what they're looking at.

You'll find the corresponding fields in the upper left corner.

5.2 Data Filters

Dashboard Edit Mode Configuring Data Filters in Exply

Right beneath the dashboard title you'll find the data filter options for your dashboard.

Data Filters are the basis for all your analysis. They limit the shown data within the widgets, e.g. customers, projects, teams, etc.

There're basically three hierarchical levels of data filters:

  1. Permission within User Management
  2. Filters for Dashboards & Widget Groups
  3. Explorative Filters through Widgets

They work from outside to inside like follows:

User Permissions > Dashboard Data Fields > Widget Data Selections

Starting with the users. By default every new user is not allowed to see any data. Access rights need to be granted explicit through an admin. Users can then only view and access dashboards they are allowed to see. In addition to viewable dashboards the specific data types (e.g. work logs, time records, etc.) and containing data fields (e.g. project name, customer name, etc.) need to be shared with the user.

For example, if a dashboard that is used for an overview contains five projects (Project A, B, C, D, E) and the user (e.g. customer) is only allowed to see two (Project A & B) of them. Set correctly he will only see the data of those within the dashboard.

Let's look at another example. The user mentioned above stays with his permissions (Project A & B). But this time the project dashboard is only showing Project A & E. Therefore the customer will only see Project A within the dashboard, because Project B isn't assigned.

Note: If you don't limit your data through data filters, you will get all data.

Selecting Data Types in Exply

Step 1: Select the Data Type you want to view, e.g. Working Time Entries

Select type of data that needs to be filtered

Step 2: Select the document field you want to filter, e.g. Projects, Customers, etc.

Cause we want to create a dashboard showing only the data related to the project "ZiffCorp Consulting", we're filtering them.

First we select "Name of Project" as document field.

After that we can choose from various types of operators like equals (default), contains, ends with, starts withmatches and all the opposite ones. We're using the default (equals) to choose the project directly in the next field. But if you want to choose every project besides the internal one, you can choose "equals not" instead of selecting every single project except internal.

To select the wanted project just start to type in the name and the integrated auto completion will show you relevant results. You don't need to fill in the complete name, just click on the result you need and it will be selected.

Step 3: Select the corresponding Projects, Customers, Teams, etc. that you want to filter

Repeat this step if you need to select more projects. In our case we're typing "Ziff" into the operand field and get all results matching the term.

6. Widgets

6.1 What are Widgets?

Widgets are used to display your data in various kinds of ways.

6.2 How do I create Widgets?

After having set the dashboard data context we're ready to create the first dashboard widgets.

By clicking on the "Add new Widget" button we get to the widget edit mode where the Bar Chart widget is selected by default.

6.2.1 Bar Chart

View JIRA Worked Hours per Tempo Account & Team Member
View JIRA Worked Hours per Team
View JIRA Worked Hours per Team Member
Configuration of the Bar Chart in Exply

6.2.2 Timeline Chart

View JIRA Worked Hours per Day and Project
Configuration of the Timeline Chart in Exply

Next we'll want to see the billable worked hours per epic and day/month/etc. to identify peaks and valleys for this project.

We therefore add a new widget and choose Timeline Chart.

Within the configuration we set the following options:

  1. Time-Field set to "Date of Creation"
  2. Granulairty is set to "automatic" per default, showing the optimal time period for the given data
  3. Choose "Billable Hours" for Value Field and
  4. "Epic" as Stacking Field

The Timeline Chart can be viewed as vertical bar chart, showing each point in time as separate bar, or area chart where all points are connected over time.

Furthermore the Maximum Number of stacks limits, as the name suggests, the number of stacked elements. In addition to that the Maximum Number of decimals narrows down the shown decimals.

6.2.3 Results Table

6.2.4 Quota Tile

Configuration of the Quota Tile in Exply

The Quota Tile enables you to define a fixed value per time span to quickly see how much of this value has been used within the defined period and how many value per day have to be done to reach the defined value, depending on the assigned people.

For Example: Billable Hours

Ongoing projects have often a fixed amount of hours that are guaranteed to be done per month (e.g. week, quarter, year).

In our example this specific amount of hours is 240 per month. 

  1. Set the Value Field to Billable Hours
  2. Select the corresponding months
  3. Type the amount of hours in the field behind to time span
  4. Repeat for further periods if needed
  5. Enter the appropriate unit, e.g. hours

The Quota Tile sets its background color automatically depending on the ratio between defined value and used value. You can change it to your prefered color if you want.

Please keep in mind that the Quota Tile depends on the selected time span of the corresponding widget group.

6.2.5 Pivot Table

Next we create a Pivot Table showing all the team members with the epics they worked on, including the amount of time needed.

In our example we're performing the following steps to get the need pivot table:

  1. Choose "working time entries" as document type to pivot over
  2. Select "Name of Project" as first grouping field
  3. "Name of Creator" to get the team member second
  4. "Epic" to get their corresponding working time entries per Epic third

Note: The grouping field "Name of Project" is not necessary if an adequat data filter is set for the dashboard.

Saving the Dashboard

After we created the first three widgets, we're ready to save the actual state of our dashboard by clicking "save" in the upper right corner.

There you have it - your first small project overview dashboard! Congratulations! :-)

Visit the Knowledge Base to get more information on how to work with Exply.