Difference between revisions of "On Boarding Overview"

From Lingoport Wiki
Jump to: navigation, search
(Groups)
(Configuring the E-mail notification)
(39 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
== Introduction ==
 
== Introduction ==
   
The [[Terms_and_Definitions#LingoportSuite|Lingoport Suite]] consists of the Globalyzer Products and the LRM Product. The Globalyzer Products analyze code and identify [[Terms_and_Definitions#i18n|internationalization]] issues such as embedded strings and locale sensitive methods. LRM uses the resource files and tracks and manages translation. Both Globalyzer and LRM have projects. A [[Terms_and_Definitions#LingoportProject|Lingoport project]] consists of the [[Terms_and_Definitions#Globalyzerproject|Globalyzer]] project and an [[Terms_and_Definitions#LRMProject|LRM project]].
+
The [[Terms_and_Definitions#LingoportSuite|Lingoport Suite]] consists of the Globalyzer and LRM Product. Globalyzer analyzes code and identifies [[Terms_and_Definitions#i18n|internationalization]] issues such as embedded strings and locale sensitive methods. LRM uses the resource files and tracks and manages translation. Both Globalyzer and LRM have projects. A [[Terms_and_Definitions#LingoportProject|Lingoport project]] consists of the [[Terms_and_Definitions#Globalyzerproject|Globalyzer]] project and an [[Terms_and_Definitions#LRMProject|LRM project]].
   
When a Lingoport project is '''[[Terms_and_Definitions#onboarding|On-boarded]]''', the project is set up to get new code and resource files from the repository. Jenkins jobs analyze the code using Globalyzer and LRM and the results are pushed to the Lingoport Dashboard.
+
When a Lingoport project is '''[[Terms_and_Definitions#onboarding|on-boarded]]''', the project is set up to get new code and resource files from the repository. Jenkins jobs analyze the code using Globalyzer and LRM and the results are pushed to the Lingoport Dashboard. The on-boarding process includes the following:
   
 
* getting the necessary information about the [[Terms_and_Definitions#LRMProject|LRM project]], its target locales, etc.
 
* getting the necessary information about the [[Terms_and_Definitions#LRMProject|LRM project]], its target locales, etc.
* creating an LRM project using the command line
 
 
* creating a Globalyzer Lite project definition file
 
* creating a Globalyzer Lite project definition file
 
* setting up the [[Terms_and_Definitions#Jenkins|Jenkins]] jobs
 
* setting up the [[Terms_and_Definitions#Jenkins|Jenkins]] jobs
 
* verifying those jobs
 
* verifying those jobs
   
A project can only be on-boarded within a [[Terms_and_Definitions#groupname|group]]. That group must have been licensed.
+
A project can only be on-boarded within a [[Terms_and_Definitions#groupname|group]]. That group must have been licensed. If the Lingoport software have been installed, then there is a licensed group and there is a Jenkins job called '''<group name>.LicenseExpiration'''. When built, the output shows the details of the licenses.
   
 
In Jenkins and on the Dashboard, the Lingoport project will be referred to as '''<group name>.<project name>'''. For example given a group called "Acme" and a software project called "Weather", Jenkins and Dashboard will refer to it as '''Acme.Weather'''
 
In Jenkins and on the Dashboard, the Lingoport project will be referred to as '''<group name>.<project name>'''. For example given a group called "Acme" and a software project called "Weather", Jenkins and Dashboard will refer to it as '''Acme.Weather'''
  +
  +
=== Configuring the E-mail notification ===
  +
  +
To avoid an error message in the LicenseExpiration job, set up the E-mail notification in Jenkins.
  +
  +
# In Jenkins select '''Manage Jenkins''' and '''Configure System'''.
  +
# Scroll down to '''E-mail Notification'''. Here is a sample configuration for guidance.
  +
  +
[[File:Correct-email-config-1.png|700px]]
   
 
== Groups ==
 
== Groups ==
   
A Lingoport Group is associated with a license that defines how many projects can be created in the group. When installing with the Stack Installer, the "Company Name" is the current group.
+
A Lingoport Group is associated with an LRM license that defines how many projects can be created in the group. When installing with the Stack Installer, the "Company Name" is the current group.
   
  +
=== LicenseExpiration Jenkins jobs ===
The Stack Installer creates a Jenkins job which will show information about the Group and when the license expires.
 
  +
The Stack Installer creates a Jenkins job which will show information about one licensed Group and when its license expires.
   
 
[[File:license_after_install.jpg|700px]]
 
[[File:license_after_install.jpg|700px]]
   
The group is '''Acme'''. Select the job (Acme.LicenseExpiration). Select the top blue sphere under Build History. This will bring you to Console Output which looks like:
+
In the illustration above, the group is '''Acme'''. Select the job (Acme.LicenseExpiration). Select '''Build Now''' from the left side menu to run the Jenkins job. Once it has built, select the top sphere under Build History. If the sphere is red, there is a problem with the license. This will bring you to Console Output. The console output shows when the license expires for group Acme as well as the versions of the Lingoport components and other system information.
<pre>
 
Building in workspace /var/lib/jenkins/jobs/Acme.LicenseExpiration/workspace
 
[workspace] $ /bin/sh -xe /tmp/hudson5197610759813816370.sh
 
+ set +x
 
-rw-r--r--. 1 jenkins jenkins 425 Apr 10 12:28 /var/lib/jenkins/stack-installer/VERSION
 
STACK_INSTALLER_VERSION=1.9.17
 
COMMIT_HASH=84ed4823cb000db415c5025036a965f74c472155
 
SUITE_JENKINS_COMMIT_HASH=59eaaf6f1bc7d5515ea9e7c3e19ff7a636d8e09f
 
   
  +
The [[Terms_and_Definitions#LRMProject|projects]] under one group can get the group's defaults for the associated translation system. So if a group's configuration is set up for an SFTP communication with a TMS for instance, all projects under that group will by default use the same mechanisms (that SFTP) with the same settings unless explicitly changed. This can be changed to a project by project basis if desired.
GLOBALYZER_LITE_VERSION=5.3
 
GLOBALYZER_WORKBENCH_VERSION=5.3.0
 
GLOBALYZER_CLI_VERSION=5.3.0
 
   
  +
LRM projects are associated with a group. If LRM is installed without the Stack Installer (not recommended), the installer requires at least one group and its license. The license for a group is obtained from support@lingoport.com based on the commercial agreement between the client and Lingoport. Each project within a group must have a unique name.
LINGOPORT_RESOURCE_MANAGER_VERSION=3.2
 
   
  +
=== Adding or updating a new LRM License/Group ===
LINGOPORT_DASHBOARD_CLIENT_VERSION=5.6.1
 
  +
To add new groups after installing the system, contact Lingoport and arrange for a new group. Lingoport will provide a license key for a given number of projects. The '''ManageLicenses''' job can also be used to update an existing or expired license. With the new license information, execute the ManageLicenses Jenkins job:
LINGOPORT_DASHBOARD_SERVER_VERSION=5.6.1
 
SONARQUBE_VERSION=5.6.3
 
   
  +
[[File:ManageLicenses.PNG|700px]]
INSTALLATION_FINISHED=2017-04-10
 
Acme.LicenseExpiration
 
=================================================================
 
CHECK_LICENSE for GROUP Acme
 
License line for Acme: Acme 10 2018-01-01 177
 
Number of days left on license for Acme: 177 days
 
Email Renewal Threshold: 30 days
 
 
END CHECK_LICENSE
 
==========================================================
 
</pre>
 
   
The [[Terms_and_Definitions#LRMProject|projects]] under one group get the group's defaults for the associated translation system. So if a group's configuration is set up for a Lingotek's community for instance, all projects under that group will by default use the same mechanisms (Lingotek) with the same settings.
 
   
  +
=== Creating a new LicenseExpiration job for a new group ===
LRM projects are associated with a group. If LRM is installed without the Stack Installer, the installer requires at least one group and its license. The license for a group is obtained from support@lingoport.com based on the commercial agreement between the client and Lingoport. Each project within a group must have a unique name.
 
  +
In order to be notified that a group's license is about to expire, a simple Jenkins Job can be setup per licensed group.
   
  +
* Copy an existing LicenseExpiration Jenkins job (New Item) whose name is in the form <code><group_name>.LicenseExpiration</code>, such as <code>Acme.LicenseExpiration</code> under the <b>4 - License Expiration</b> tab.
To add new groups after installing the system, execute the ManageLicenses Jenkins job:
 
  +
[[File:New_item.png|500px]]
   
[[File:ManageLicenses.PNG|700px]]
 
   
  +
* Set the job to be triggered every night, for instance using <b>Build Periodically</b> set to <code>H 2 * * *</code>
  +
[[File:Build_trigger.png|500px]]
   
Alternatively, use the <code>--create-group</code> command on lrm-cli.jar command line. You need to have requested a license key for the new group from Lingoport before creating the group. For instance:
 
   
  +
* Set an <b>Execute Build Script</b> to <code>$LRM_HOME/bin/job_checklicense.sh 30</code> if you want to be notified 30 days before the license will expire
> java -jar $LRM_HOME/lrm-cli.jar --create-group --group-name group1 --date "2016-06-01" --number-of-licenses 10 --license-key <license-key>
 
   
  +
[[File:Execute.png|500px]]
To update the license of an existing group, used the <code>--update-license</code> command on lrm-cli.jar command line. You need to have requested a license key for the new group from Lingoport before updating the group.For instance:
 
   
  +
* Set the email notification:
> java -jar $LRM_HOME/lrm-cli.jar --update-license --group-name group1 --date "2016-06-01" -number-of-licenses 10 --license-key <license-key>
 
  +
** Set the recipients for the email. This email will alert the recipients of an renewal of the license for that group is upcoming. You may want to include <code>support@lingoport.com</code>.
  +
** Check the <code>Send e-mail for every unstable build</code> check box and optionally the <code>Send separate e-mails to individuals who broke the build</code>
   
  +
[[File:Email_notification.png|500px]]
Once a group has been created, the database and the file structure are updated. The Jenkins LicenseExpiration job should show the change to the license.
 
  +
  +
If you want to test it:
  +
* Modify the Jenkins job and set the Execute Script threshold set to a very large number (5000) and select "Build Now". The email should get sent to the list of recipients.
  +
  +
<code>$LRM_HOME/bin/job_checklicense.sh 5000</code>
  +
  +
* Reset the Execute Script threshold to 30 and "Build Now" again: No emails should be sent.
  +
<code>$LRM_HOME/bin/job_checklicense.sh 30</code>
  +
  +
[[File:Build_now.png|500px]]
  +
  +
The console output of the Jenkins job shows when the LRM license will expire and when email notification will be sent.
   
 
====Group Name====
 
====Group Name====
Line 90: Line 93:
 
* % (percentage)
 
* % (percentage)
   
== Jenkins job and Projects ==
+
== Jenkins jobs and Projects ==
 
When the Stack Installer creates the Jenkins jobs, it orders them into various tabs. Here is an example showing the <group>.<project> for Acme.Weather:
 
When the Stack Installer creates the Jenkins jobs, it orders them into various tabs. Here is an example showing the <group>.<project> for Acme.Weather:
   
Line 96: Line 99:
   
   
  +
The <b>1 - Automation</b> tab contains on-boarded jobs which generate the status of the project and pushes it to the dashboard, and pseudo-localizes resource files if necessary. These jobs tend to run whenever files are pushed to the repository for the project.
 
  +
* Any job that starts with '''Lingoport.''' is a template under the <code>Templates</code> tab and can be used to simplify the on-boarding process. To on-board an LRM job, use the '''Lingoport.SampleLRM''' template as a starting place.
The <b>1 - Automation</b> tab contains on-boarded jobs which generate the status of the project and pushes it to the dashboard, and pseudo-localizes resource files if necessary. These jobs tend to run whenever files are pushed to the repository for the project. See <code>''$LRM_HOME/bin/job_automate.sh''</code>, <code>''$DASHBOARD_HOME/bin/job_lite.sh''</code>, <code>''$DASHBOARD_HOME/bin/job_lrm_and_lite.sh''</code>
 
* Any job that starts with '''Lingoport.''' is a template and can be used to simplify the on-boarding process.
 
* ''$DASHBOARD_HOME'' refers to the home of the Dashboard Client, not the Dashboard Server.
 
** E.g. <code>''/var/lib/jenkins/lingoport/dashbaord-client-<version>''</code>
 
   
 
[[File:automation_tab.jpg|800px]]
 
[[File:automation_tab.jpg|800px]]
   
The <b>2 - Nightlies</b> tab contains on-boarded jobs which run every day or every night and provide an update to the dashboard and an email to a set of recipients based on the configured frequency. See <code>''$LRM_HOME/bin/job_nightly.sh''</code>
+
The <b>2 - Nightlies</b> tab contains on-boarded jobs which run every day or every night and provide an update to the dashboard and an email to a set of recipients based on the configured frequency. The job name should be the same as the LRM Automation job with a ''-Nightly'' suffix.
* It also contains the license check for a group (not a project). The name of the Jenkins job is <code><group_name>.License_Expiration</code>.See <code>''$LRM_HOME/bin/job_checklicense.sh 30''</code> (if 30 days is set as the threshold)
 
   
 
[[File:nightlies_tab.jpg|800px]]
 
[[File:nightlies_tab.jpg|800px]]
   
The <b>3- PrepKit</b> tab contains on-boarded jobs which are triggered by a human intervention to send the kits for translation based on the configured translation endpoint. See <code>''$LRM_HOME/bin/job_prepkit.sh''</code>
+
The <b>3- PrepKit</b> tab contains on-boarded jobs ending in ''-PrepKit'' which are triggered by a human intervention to send the kits for translation based on the configured translation endpoint. Prep kits can also be triggered from the Lingoport Dashboard. The job name should be the same as the LRM Automation job with a ''-PrepKit'' suffix.
   
 
[[File:prepkit_tab.jpg|800px]]
 
[[File:prepkit_tab.jpg|800px]]
   
The <b>4- License Expiration</b> tab contains on-boarded jobs which are run every night to warn you if your license is about to expire. See <code>''$LRM_HOME/bin/job_checklicense.sh''</code>
+
The <b>4- License Expiration</b> tab contains on-boarded jobs which are run every night to warn you if your license is about to expire. The job name should <code>''GroupName.''LicenseExpiration</code>.
   
 
[[File:license_tab.jpg|800px]]
 
[[File:license_tab.jpg|800px]]
 
Each tab has a job setup during configuration via scripts (or manually if you prefer). After the first project has been on-boarded, on-boarding a new job consists in copying an first project's jobs and configuring a set of xml files.
 
   
 
== Next Step ==
 
== Next Step ==
  +
[[Before On-Boarding]]
 
  +
The next step is to do the actual on boarding. Select the link below that describes your situation.
  +
  +
*[[On Boarding an LRM Project]]
  +
*[[On Boarding a Globalyzer Project]]
  +
*[[On Boarding a project with both LRM and Globalyzer]]

Revision as of 22:53, 23 December 2019

Introduction

The Lingoport Suite consists of the Globalyzer and LRM Product. Globalyzer analyzes code and identifies internationalization issues such as embedded strings and locale sensitive methods. LRM uses the resource files and tracks and manages translation. Both Globalyzer and LRM have projects. A Lingoport project consists of the Globalyzer project and an LRM project.

When a Lingoport project is on-boarded, the project is set up to get new code and resource files from the repository. Jenkins jobs analyze the code using Globalyzer and LRM and the results are pushed to the Lingoport Dashboard. The on-boarding process includes the following:

  • getting the necessary information about the LRM project, its target locales, etc.
  • creating a Globalyzer Lite project definition file
  • setting up the Jenkins jobs
  • verifying those jobs

A project can only be on-boarded within a group. That group must have been licensed. If the Lingoport software have been installed, then there is a licensed group and there is a Jenkins job called <group name>.LicenseExpiration. When built, the output shows the details of the licenses.

In Jenkins and on the Dashboard, the Lingoport project will be referred to as <group name>.<project name>. For example given a group called "Acme" and a software project called "Weather", Jenkins and Dashboard will refer to it as Acme.Weather

Configuring the E-mail notification

To avoid an error message in the LicenseExpiration job, set up the E-mail notification in Jenkins.

  1. In Jenkins select Manage Jenkins and Configure System.
  2. Scroll down to E-mail Notification. Here is a sample configuration for guidance.

Correct-email-config-1.png

Groups

A Lingoport Group is associated with an LRM license that defines how many projects can be created in the group. When installing with the Stack Installer, the "Company Name" is the current group.

LicenseExpiration Jenkins jobs

The Stack Installer creates a Jenkins job which will show information about one licensed Group and when its license expires.

License after install.jpg

In the illustration above, the group is Acme. Select the job (Acme.LicenseExpiration). Select Build Now from the left side menu to run the Jenkins job. Once it has built, select the top sphere under Build History. If the sphere is red, there is a problem with the license. This will bring you to Console Output. The console output shows when the license expires for group Acme as well as the versions of the Lingoport components and other system information.

The projects under one group can get the group's defaults for the associated translation system. So if a group's configuration is set up for an SFTP communication with a TMS for instance, all projects under that group will by default use the same mechanisms (that SFTP) with the same settings unless explicitly changed. This can be changed to a project by project basis if desired.

LRM projects are associated with a group. If LRM is installed without the Stack Installer (not recommended), the installer requires at least one group and its license. The license for a group is obtained from support@lingoport.com based on the commercial agreement between the client and Lingoport. Each project within a group must have a unique name.

Adding or updating a new LRM License/Group

To add new groups after installing the system, contact Lingoport and arrange for a new group. Lingoport will provide a license key for a given number of projects. The ManageLicenses job can also be used to update an existing or expired license. With the new license information, execute the ManageLicenses Jenkins job:

ManageLicenses.PNG


Creating a new LicenseExpiration job for a new group

In order to be notified that a group's license is about to expire, a simple Jenkins Job can be setup per licensed group.

  • Copy an existing LicenseExpiration Jenkins job (New Item) whose name is in the form <group_name>.LicenseExpiration, such as Acme.LicenseExpiration under the 4 - License Expiration tab.

New item.png


  • Set the job to be triggered every night, for instance using Build Periodically set to H 2 * * *

Build trigger.png


  • Set an Execute Build Script to $LRM_HOME/bin/job_checklicense.sh 30 if you want to be notified 30 days before the license will expire

Execute.png

  • Set the email notification:
    • Set the recipients for the email. This email will alert the recipients of an renewal of the license for that group is upcoming. You may want to include support@lingoport.com.
    • Check the Send e-mail for every unstable build check box and optionally the Send separate e-mails to individuals who broke the build

Email notification.png

If you want to test it:

  • Modify the Jenkins job and set the Execute Script threshold set to a very large number (5000) and select "Build Now". The email should get sent to the list of recipients.

$LRM_HOME/bin/job_checklicense.sh 5000

  • Reset the Execute Script threshold to 30 and "Build Now" again: No emails should be sent.

$LRM_HOME/bin/job_checklicense.sh 30

Build now.png

The console output of the Jenkins job shows when the LRM license will expire and when email notification will be sent.

Group Name

A group name must conform to the following specification: A set of alphanumeric characters without the following special characters:

  • < (less than)
  • > (greater than)
  •  : (colon)
  • " (double quote)
  • / (forward slash)
  • \ (backslash)
  • | (vertical bar or pipe)
  •  ? (question mark)
  • * (asterisk)
  • (space)
  •  % (percentage)

Jenkins jobs and Projects

When the Stack Installer creates the Jenkins jobs, it orders them into various tabs. Here is an example showing the <group>.<project> for Acme.Weather:

All tabs.jpg


The 1 - Automation tab contains on-boarded jobs which generate the status of the project and pushes it to the dashboard, and pseudo-localizes resource files if necessary. These jobs tend to run whenever files are pushed to the repository for the project.

  • Any job that starts with Lingoport. is a template under the Templates tab and can be used to simplify the on-boarding process. To on-board an LRM job, use the Lingoport.SampleLRM template as a starting place.

Automation tab.jpg

The 2 - Nightlies tab contains on-boarded jobs which run every day or every night and provide an update to the dashboard and an email to a set of recipients based on the configured frequency. The job name should be the same as the LRM Automation job with a -Nightly suffix.

Nightlies tab.jpg

The 3- PrepKit tab contains on-boarded jobs ending in -PrepKit which are triggered by a human intervention to send the kits for translation based on the configured translation endpoint. Prep kits can also be triggered from the Lingoport Dashboard. The job name should be the same as the LRM Automation job with a -PrepKit suffix.

Prepkit tab.jpg

The 4- License Expiration tab contains on-boarded jobs which are run every night to warn you if your license is about to expire. The job name should GroupName.LicenseExpiration.

License tab.jpg

Next Step

The next step is to do the actual on boarding. Select the link below that describes your situation.