Hybris Extension Administrator Guide

Transcription

1 Hybris Extension Administrator Guide

2 Table of Contents About this Guide... 4 Conventions Used in this Guide... 4 Typographical... 4 Icons... 4 Technical Requirements... 5 Software Requirements... 5 Pre-Requisites... 5 About GlobalLink hybris Extension... 6 Design Overview... 7 How Change Management Works... 9 Setup and Configuration Installation and Preliminary Setup Updating the GlobalLink Extension Extension Configuration Configuring the GlobalLink Server Connection Mapping Languages Error Notifications Feature Translation Optional Extension Configuration Configuring Deployment Properties Configuring Batching Default Source Language Default Selection Configuration Disallowing Translation Submissions From the Active Catalog Configuring Product Feature Translation Configuring Items as Non-Translatable Cron Jobs Viewing Cron Jobs Configuring Cron Job Schedules Setting Up Access Control Assigning Employees to User Groups Monitoring Translation Jobs This documentation is proprietary and is protected by U.S. and international copyright laws and trade secret laws. Copyright 2015 Translations.com, Inc. ("Translations.com") All rights reserved. No part of this documentation may be reproduced, copied, adapted, modified, distributed, transferred, translated, disclosed, displayed or otherwise used by anyone in any form or by any means without the express written authorization of Translations.com. Other names may be trademarks of their respective owners. Copyright 2015 Translations.com, Inc. Confidential Page 2 of 30

3 Viewing Translation Jobs Extending the GlobalLink Extension Copyright 2015 Translations.com, Inc. Confidential Page 3 of 30

4 About this Guide This section describes the conventions that convey instructions and other information. Conventions Used in this Guide Typographical The following table explains the typographical conventions used in this guide. Convention Bold Italic < > Application User interface controls, commands, and keywords in body text. User input entered. Generic parameters that must be replaced by specific code or text. Icons The following table explains the icon conventions used in this guide. Convention Application Note: This icon designates a note or helpful suggestion or reference relating to the surrounding text. Best Practice: This icon designates a suggestion for best practice relating to the surrounding text. Alert: This icon designates warning or alert relating to the surrounding text. In this situation, the user should exercise caution to avoid an undesirable result. This documentation is proprietary and is protected by U.S. and international copyright laws and trade secret laws. Copyright 2015 Translations.com, Inc. ("Translations.com") All rights reserved. No part of this documentation may be reproduced, copied, adapted, modified, distributed, transferred, translated, disclosed, displayed or otherwise used by anyone in any form or by any means without the express written authorization of Translations.com. Other names may be trademarks of their respective owners. Copyright 2015 Translations.com, Inc. Confidential Page 4 of 30

5 Technical Requirements 1 Software Requirements Following are the requirements for the GlobalLink hybris extension to function: Software hybris-multichannel-suite Version 5.4.x.x Pre-Requisites The extension installer files (GlobalLinkHybrisExtension_3.2.2.zip) are acquired from Translations.com. If the extension is being deployed on a hybris instance where only the PIM is deployed and hybris WCMS extension is not used, the extension GlobalLinkHybrisExtension_3.2.2_nocms.zip should be used. The translation project and user accounts are configured on GlobalLink Project Director. Copyright 2015 Translations.com, Inc. Confidential Page 5 of 30.

6 About GlobalLink hybris Extension 2 The GlobalLink hybris extension integrates seamlessly with hybris and allows users to initiate, track, and complete all facets of the hybris content translation process using the hybris user interface. The package consists of the following extensions: Global Product Cockpit An extended product cockpit with added functionality to submit and track translation requests for products and related hybris objects. Global WCMS Cockpit An extended CMS cockpit with added functionality to submit and track translation requests for WCMS pages. GlobalLink The core extension which contains the business logic and associated data models required to track and manage the translation requests. This module also installs two cron jobs which manage the data exchange with GlobalLink Project Director. Copyright 2015 Translations.com, Inc. Confidential Page 6 of 30.

7 Chapter 2 About GlobalLink hybris Extension GlobalLink hybris Extension Design Overview The schematic below shows a high level architecture of the solution. Step 1 Users can initiate product translation requests from the Global Product Cockpit and page translation requests from the Global CMS Cockpit. Copyright 2015 Translations.com, Inc. Confidential Page 7 of 30

8 Chapter 2 About GlobalLink hybris Extension GlobalLink hybris Extension Site Administrators can also use the Management Console (HMC) to submit translation requests for category content. Step 2 The translation job queue is a central data store for the hybris system which stores all tracking information related to translation management and reporting. For all translation requests, a new translation job is created on the Translation Job Queue, containing all the objects (Job Items) for which translation is requested. The status of the Job is set to QUEUED. Step 3 The SubmitToPDCron job is scheduled to run on the server at a periodic interval. This job processes all jobs in the job queue with status QUEUED. It prepares an XML extract of the hybris objects that require translation and sends them on to GlobalLink Project Director using the webservices API. On successful completion, the status of the job is changed to INPROGRESS. Step 4 GlobalLink Project Director processes the XML files and the content is translated within the GlobalLink translation workflow. On completion of the translation workflow, the files are available on the GlobalLink PD with status COMPLETE. Step 5 The FetchFromPDcron job polls GlobalLinkPD at regular intervals, requesting for all files that have completed the translation workflow. It then downloads the translated XML files and updates the translated strings in the language variants of the respective hybris objects. On successful import back into hybris, the status of the Job Item is set to TRANSLATED. Once all the items from a job are translated, the status of the job is also changed to TRANSLATED. Copyright 2015 Translations.com, Inc. Confidential Page 8 of 30

9 Chapter 2 About GlobalLink hybris Extension GlobalLink hybris Extension How Change Management Works Within the GlobalLink extension, we maintain a record of all translation requests. While submitting content for translation, hybris users have the option to submit only New and Changed content. An item is submitted for translation only if it s a new item (never been translated before) or has changed since the last time it was translated for that specific language. If the item has no translatable content, it will not be sent for translation. This helps in managing the translation lifecycle of your content and allows you to submit only incremental updates for translation. The process of detecting new and changed content within the GlobalLink extension is explained below: 1. At the time of submission creation, all items are added to the job with status QUEUED. 2. The ChangeDetection process for each translation requests detects if an existing translation request is INPROGRESS or COMPLETED for the specified item and target language. If no existing request is found, the item is treated as NEW (never been translated before) and will be submitted for translation. If an existing request is found in any of these states, this means that it has been translated before. The next step is to detect if it has changed. 3. For every translation request, all the translatable strings for the item are concatenated into a single string. A CRC is calculated and stored in the Last Translated data model within the GlobalLink extension. The next time the same item is translated, such a CRC is calculated again and compared with the last translation request for the same item and language that is stored in our records. If the CRC matches, then there is no change and the item is flagged with status NO_CONTENT, and not sent to GlobalLink. If the CRC does not match, that means that the item has changed and will be sent to GlobalLink. 4. If a queued item has no content for translation, its status is changed to NO_CONTENT. Copyright 2015 Translations.com, Inc. Confidential Page 9 of 30

10 Setup and Configuration 3 Installation and Preliminary Setup 1. Log in to the server where hybris is installed. 2. The directory where hybris is installed will be referred to as <hybris-home>. For example, <hybris-home> may refer to C:\Hybris\ on windows. 3. Create a new folder named globallink under <hybris-home>/bin. 4. If the hybris server is set up for PIM + WCMS, extract GlobalLinkHybrisExtension_3.2.2.zip to <hybris-home>/bin/globallink folder. For PIM + WCMS, append the following configurations to <hybris-home>/config/localextension.xml: <!--transperfect extension --> <extension dir="${hybris_bin_dir}/custom/globallink"/> <extension dir="${hybris_bin_dir}/custom/globalproductcockpit"/> <extension dir="${hybris_bin_dir}/custom/globalcmscockpit"/> 5. If the hybris server is set up for PIM only, extract GlobalLinkHybrisExtension_3.2.2_nocms.zip to <hybris-home>/bin/globallink folder. For PIM only hybris setup, append the following configurations <hybris-home>/config/localextension.xml: <!--transperfect extension --> <extension dir="${hybris_bin_dir}/custom/globallink"/> <extension dir="${hybris_bin_dir}/custom/globalproductcockpit"/> 6. Open command prompt and change working directory to: <hybris-home>/bin/platform> 7. Set the Ant environment: Windows : <hybris-home>/bin/platform :/>setantenv.bat Unix : <hybris-home>/bin/platform :/>./setantenv.sh 8. Run the following command to build the extension: <hybris-home>/bin/platform:/>ant clean all 9. On successful execution the following message should appear: BUILD SUCCESSFUL 10. Start the hybris server by running the following command: Copyright 2015 Translations.com, Inc. Confidential Page 10 of 30

11 Chapter 3: Setup and Configuration GlobalLink hybris Extension Windows : <hybris-home>/bin/platform />hybrisserver.bat Unix : <hybris-home>/bin/platform :/>./ hybrisserver.sh Updating the GlobalLink Extension To finish the installation of the extension, hybris must be updated. During the update, all new types and attribute data of the GlobalLink extension are created in the database. 1. Log in to the hybris Administration Console as a user with administrator credentials. 2. Go to the Platform tab and select Update. 3. In General Settings, select all four options as shown below. Copyright 2015 Translations.com, Inc. Confidential Page 11 of 30

12 Chapter 3: Setup and Configuration GlobalLink hybris Extension In Project data settings, select the three GlobalLink modules as shown below. 5. Click and wait until the process completes. 6. Restart hybris server. Copyright 2015 Translations.com, Inc. Confidential Page 12 of 30

13 Extension Configuration 4 The following configurations need to be set up prior to submitting content for translation. Server Configuration Language Mapping Configuring the GlobalLink Server Connection To configure a connection to Project Director Server: 1. Log in to Hybris Management Console as a user with administrator credentials. 2. Navigate to GlobalLink Configuration > Server Configuration. 3. Right-click Server Configuration and select Create GlobalLink Configuration. Copyright 2015 Translations.com, Inc. Confidential Page 13 of 30

14 Chapter 4: Extension Configuration GlobalLink hybris Extension Enter the configuration parameters as provided by your Translations.com account manager. The description for each option is provided below. Option Project Director URL Username Password Project Short Code Description The Project Director services URL. For example. Username to login to GlobalLink Project Director. Password for GlobalLink Project Director. Unique project identifier for Project Director. 5. Click. Mapping Languages The languages defined in hybris need to be mapped to the appropriate locale codes that will be used to identify them within GlobalLink Project Director. 1. To define the language map, open the saved GlobalLink Configuration and navigate to the Languages Section. 2. Right-click the header and select Create GlobalLink Language Mapping. Copyright 2015 Translations.com, Inc. Confidential Page 14 of 30

15 Chapter 4: Extension Configuration GlobalLink hybris Extension To map languages, select the hybris language from the Language column and select the corresponding locale Code from the Locale Code column. 4. Click Save. Error Notifications A list of addresses can also be configured to be sent a notification if any scheduled cron jobs encounter an exception. To configure the server, edit config/local.properties on the hybris server: mail.smtp.server={mail SERVER} mail.smtp.port=25 mail.smtp.auth=true mail.replyto={reply TO} Copyright 2015 Translations.com, Inc. Confidential Page 15 of 30

16 Chapter 4: Extension Configuration GlobalLink hybris Extension # User account and password used for the authentication with the SMTP server (optional) mail.smtp.user= mail.smtp.password= mail.use.tls=false Feature Translation By default, the GlobalLink extension extracst all product features for translation if the option to submit product features for translations was checked while submitting the products using the Translation Wizard. However, we also allow you to configure the list of features to include/exclude for translation. If you select Include only listed Features, only the listed Features will be considered localizable, and all others skipped. If you select Exclude only listed Features, all Features will be considered localizable, and only the listed Features skipped. Copyright 2015 Translations.com, Inc. Confidential Page 16 of 30

17 Optional Extension Configuration 5 The configuration options listed in this chapter are optional, but it is recommended to review these configuration options and implement them as desired in order to take full advantage of the customization options available in the GlobalLink extension. The parameters listed in this chapter must be implemented in the globallink/project.properties file if the parameter is not already listed by default. The configuration option for the Error Notifications section must be implemented in the config/local.properties file on the hybris server. Configuring Deployment Properties globallink.deployment=[dev] The globallink.deployment parameter defines the environment of the hybris installation. This variable is appended to the logs on Project Director and provides traceability to identify all activity initiated from this specific server. Configuring Batching globallink.job.submission.maxdocuments = 0 The globallink.job.submission.maxdocuments parameter defines the maximum number of items that will be grouped into a single submission. If this value is set to 0 (zero), there will be no batching. If the user submits 100 items and this value is set to 20, there will be 5 submissions in PD. Copyright 2015 Translations.com, Inc. Confidential Page 17 of 30

18 Chapter 5: Optional Extension Configuration GlobalLink hybris Extension Default Source Language globallink.wizard.sourcelanguage.isocode.default = en For cases where there are multiple language directions configured on Project Director, you can configure the default source locale by setting this parameter. This value needs to be the ISO code of the language as setup in hybris. Copyright 2015 Translations.com, Inc. Confidential Page 18 of 30

19 Chapter 5: Optional Extension Configuration GlobalLink hybris Extension Default Selection Configuration globallink.wizard.translateproductfeatures.default=true globallink.wizard.newandchanged.default=true The Submission Wizard is configured by default. Select the checkboxes to clear them if you want to change the defaults. Copyright 2015 Translations.com, Inc. Confidential Page 19 of 30

20 Chapter 5: Optional Extension Configuration GlobalLink hybris Extension Disallowing Translation Submissions From the Active Catalog The recommended workflow for translating content in hybris is to first translate the content from the staging (inactive) catalog and then sync it to the online (active) catalog. Users should be restricted from sending content for translation directly from the active catalog. It is therefore recommended to disallow a translation request for an item that is in an active catalog. The following two parameters show this configuration for products and CMS items. globallink.productlocalizabilityvoter.activecatalogdisabled=true globallink.cmsitemlocalizabilityvoter.activecatalogdisabled=true Configuring Product Feature Translation This configuration controls the behavior for handling features in the current target language have been: manually created/ not created by the GlobalLink ProductFeatureHandler, created by the ProductFeatureHandler, but the associated source language Feature has been removed. True: Features matching above criteria are removed when a translation update is done for the target language False : Features matching above criteria are not removed when a translation update is done for this target language. All such entries will be placed at the end of the value list for that language. globallink.productfeaturehandler.removeunknowntranslations=false Copyright 2015 Translations.com, Inc. Confidential Page 20 of 30

21 Chapter 5: Optional Extension Configuration GlobalLink hybris Extension Configuring Items as Non-Translatable By default, all item types that are derived from hybris Item model can be submitted for translation, even if the item is not a product. To disable the Translate option in the context menu for certain item types in the HMC, add the item type code to the parameter below as a comma separated value. globallink.configurablelocalizabilityvoter.disable=catalog Copyright 2015 Translations.com, Inc. Confidential Page 21 of 30

22 Cron Jobs 6 The process of preparing translation jobs, submitting content for translation to GlobalLink, and retrieving translated content is performed by two cron jobs that are installed as part of the GlobalLink extension for hybris: submittopdcronjob fetchfrompdcronjob Viewing Cron Jobs 1. Log in to HMC with administrator credentials. 2. Navigate to System > CronJobs. 3. Click the Comparator drop-down menu for the JobName attribute and select contains. 4. Enter PDCron as the value. 5. Click Search. Copyright 2015 Translations.com, Inc. Confidential Page 22 of 30

23 Chapter 6: Cron Jobs GlobalLink hybris Extension Configuring Cron Job Schedules Each Cron Job needs to be scheduled to run at a predefined interval. To setup the schedule for the cron jobs: 1. Double-click the desired Cron Job to open it. 2. Select the Time Schedule tab. Right-click the Triggers header and select Create Trigger. Copyright 2015 Translations.com, Inc. Confidential Page 23 of 30

24 Chapter 6: Cron Jobs GlobalLink hybris Extension Select the execution interval and configure the start time and frequency. 4. Click Save Copyright 2015 Translations.com, Inc. Confidential Page 24 of 30

25 Setting Up Access Control 7 The GlobalLink extension creates two user groups within hybris during the installation process. To view pre-defined GlobalLink User Groups: 1. Log in to HMC. 2. Navigate to User > User Groups. 3. In the Search area, adjust the Name attribute to show starts with as the Comparator and enter GlobalLink as the value. 4. Click Search. 5. The user groups have predefined access rights to the translation job queue as described below. ID Column GlobalLinkconfiggroup GlobalLinkusergroup Description Grants access rights to configure the extension in HMC. Grants access permission to users to submit content for translation from the cockpits and HMC. Copyright 2015 Translations.com, Inc. Confidential Page 25 of 30

26 Chapter 7: Setting Up Access Control GlobalLink hybris Extension Assigning Employees to User Groups Employees need to be assigned to the user groups in the previous section based on their roles within the organization. To assign employees to specific user groups: 1. Select Users > Employees. 2. Enter the name or ID of the Employee to be assigned to a GlobalLink group. 3. Click Search. 4. Double-click the selected employee. 5. Add the required GlobalLink Groups. 6. Click Save. Copyright 2015 Translations.com, Inc. Confidential Page 26 of 30

27 Monitoring Translation Jobs 8 Any user submitting content for translation using the GlobalLink extension queues the content for translation in the Translation Jobs. An administrator can monitor or view the items sent for translation by viewing the Translation Jobs and Translation Job Items within HMC. Viewing Translation Jobs A translation job is created for every submission request, and contains the following details: Column ID Name Requestor Origin Request Date Due Date Type Target Locale Description Translation Job Queue ID Combination of Project Short Code_Date Time stamp Username of the person who sent the hybris Items for translation Source Language The date the translation was queued Due Date for completing translation in Project Director This could either be any of the hybris Items: Category, Product, Page, or Component Target locale selected for sending translation To view the translations job: 1. Login to HMC. 2. Select GlobalLink > Jobs. Copyright 2015 Translations.com, Inc. Confidential Page 27 of 30

28 Chapter 8: Monitoring Translation Jobs GlobalLink hybris Extension Click Search, to view a list of all jobs in the system. Note: The GlobalLink > Last Translations is a reserved data model used to track information about all translation requests. Please do not alter/delete items within this without consulting your Translations.com account representative. 4. To view all items within a translation job, double click the job row. Copyright 2015 Translations.com, Inc. Confidential Page 28 of 30

29 Extending the GlobalLink Extension 9 Hybris is an e-commerce framework for PIM and Web CMS platforms. Clients can customize hybris extensively to define their own data models and web components. The GlobalLink extension for hybris provides a mechanism to submit products and web pages for translation from the hybris global cockpits. In some cases, the client may have a need to submit related items or products, e.g., submitting all of a product s variants and the original product, or identifying nested components in a CMS page and submitting them with the CMS page. Our adaptor is extensible and allows for adaptation to a client s custom data model and relations. In order to identify additional related items to be added to a translation request, Item Handlers must be defined for custom Items that have further nested items. To define ItemHandlers: 1. Define your own Handler which extends ItemModelHandler. Refer to the comments in the sample source code below for the explanation. public class ProductHandler extends ItemModelHandler private CommonI18NService public boolean supports(final ItemModel item) { // Define the itemmodel which this handler will support return (item instanceofproductmodel); Copyright 2015 Translations.com, Inc. Confidential Page 29 of 30

30 Chapter 9: Extending the GlobalLink Extension GlobalLink hybris Extension public Set<ItemModel>getNestedItems(final ItemModel item) { final Set<ItemModel> nested = new HashSet<ItemModel>(); // Add your custom logic here to get nested/related items return nested; } } 2. Compile your handler classes into a Jar and copy them to globallink/bin. 3. Add a reference to your custom handler classes to the item Handlers list in \globallink\resources\globallink-spring.xml as shown below. <alias alias="itemhandlers" name="defaultitemhandlers" /> <util:list id="defaultitemhandlers" valueype="org.gs4tr.projectdirector.adaptors.hybris.service.itemhandler"> <!-- Order is important if Items are instance of multiple types for which handlers exist --> <ref bean="keywordhandler" /> <ref bean="pageitemhandler" /> <ref bean="cmsnavigationnodehandler" /> <ref bean="contentslothandler" /> <ref bean="footercomponenthandler" /> <ref bean="navigationbarcomponenthandler" /> <ref bean="categoryhandler" /> <ref bean="producthandler" /> <ref bean="itemmodelhandler" /><!-- leave as last --> </util:list> 4. Restart hybris server. Copyright 2015 Translations.com, Inc. Confidential Page 30 of 30