Service Portal Installation Guide

Derek Torres
Derek Torres
  • Updated

Important Note: ServiceTrade Support can provide general guidance, but will not provide setup or maintenance for your Service Portal.

If you are interested in having ServiceTrade setup, handle ongoing maintenance, and support your Service Portal your organization will need to purchase an add-on subscription to the Technical Account Manager (TAM) Service. If you are interested in these services please contact your Account Manager. Click here to learn more about the scope of ServiceTrade support for Service Portal.

 

This article will walk users through installing and setting up the Service Portal.

Overview of the Service Portal

Click here for a general features overview on the Service Portal.

The ServiceTrade Service Portal WordPress plugin gives your customers a portal to their service history and upcoming services in ServiceTrade, directly from your website.

Through the Service Portal, your customers can access the following features:

  • A list of upcoming appointments, today's appointments, and recently completed jobs (completed in the past 90 days.)
  • Full job and deficiency history for each location and each asset.
  • A list of open quotes to be approved.
  • A service request form that allows them to request service for any asset or location.

When installed Service Portal users (your customers) may do the following:

  • Click on any job to see the Service Link for that job, even if you have not sent the Service Link for that job to them. 
  • Click on any quote to see that quote, even if you have not sent that quote to them.
  • Click on any invoice to see that invoice, even if you have not sent that invoice to them.

Prerequisites

  • ServiceTrade's Service Portal feature is available for Premium and Enterprise customers. If you are interested in upgrading to access this feature, please contact your ServiceTrade Account Manager or email am@servicetrade.com
  • Must be an Account Admin in ServiceTrade.

Technical Requirements:

  • The Service Portal is a WordPress Plugin.
  • PHP 7.2 or above, with OpenSSL support.
  • WordPress 5.0 or above.
  • WordPress must be able to send emails using wp_mail - we recommend WP-Mail-SMTP extension.
  • To customize your site, you need a basic understanding of WordPress and CSS.
    • Important Note: We do not support WordPress customization. Please get in touch with your Web Developer if you have questions about customization.

Browser Requirements:

End customers who use the portal must use one of the following supported browsers:

  • Google Chrome (latest version) on any operating system
  • Mozilla Firefox (latest version) on any operating system
  • Apple Safari (latest version) on any Apple-supported Mac OS version
  • Microsoft Edge (latest version) on any Microsoft-supported Windows version
  • Microsoft Internet Explorer (v11) on any Microsoft-supported Windows version

 

Step 1: Install the Service Portal WordPress Plugin

If installing anew, rather than upgrading, please continue following the instructions below:

  1. Download the portal plugin zip file from the ServiceTrade Extensions site.
    Download_WP_plugin.png
  2. Log in to WordPress as an admin.
  3. On the Navigation Bar, click on Plugins.
  4. Click Add New.
    Plugin_New.png
  5. Click Upload Plugin.
    Add_Plugin.png
  6. Click Choose File and select the Service Portal zip file.
  7. Click Install Now.
    Choose_File_Upload.png
  8. Once the portal is installed, click Activate.

Step 2: Create ServiceTrade Admin User for your Service Portal

  1. In ServiceTrade, create a new user for the portal plugin to use.
  2. Grant that ServiceTrade user the 'Account Admin' role.
    • Note: DO NOT use a person's existing login for this or any other integration.
      Instead, create a dedicated ServiceTrade admin user that is obviously a bot.

      Example: "mycompanyname.servicetradeportal"
      User_Setup.png
  3. Log into app.servicetrade.com as that newly created user.
  4. Accept the ServiceTrade End-User License Agreement.
  5. Log out of ServiceTrade.  
    • Note: Ensure these credentials will log you into ServiceTrade before proceeding.

Step 3: Create a New WordPress Page

  1. In WordPress, add a new page to your site, click on Pages in your Dashboard.
  2. Then click Add New Page.
    Pages_Add_New.png
    blank_totle_and_block.png
  3. Name the page 'Service Portal'.
  4. Paste the shortcode below for the portal, which is:[servicetrade-service-portal][/servicetrade-service-portal]
    Title_Block.png

  5. Click to expand the Permalink accordion.
  6. Make a record of the permalink for this page because you need it to enter the portal configuration page.
    Permalink.png
  7. Once done, click the blue Publish button.
    Publish.png

Step 4: Configure the WordPress Plugin Settings

  1. In WordPress, on the Navigation Bar, click 'ServiceTrade.'
  2. Then click 'Settings.' This will take you to the Configuration Page.
    Servicetradfe_settings.png
  3. Enter the following information on the Configuration Page:
    • Name:  Enter the username for the ServiceTrade portal user you just created. See Step 2.
    • Password:  Enter the password for the ServiceTrade portal user that you just created. See Step 2.
    • Admin Email:  Enter an email address that should receive service requests, new customer account notifications, and other messages from the plugin.
    • Portal Page URL:  Enter the full address of the new WordPress page that you just created (such as http://www.yoursite.com/service-portal)
    • Timezone:  Choose the time zone in which your customers should see times displayed (this should be your company's local time zone).
  4. If you want your customers to be able to request services through the portal, click the 'Request Service' checkbox.
  5. If you want your customers to be able to see canceled appointments in their job lists through the portal, click the 'Show Canceled Appointments' checkbox.
  6. Click 'Save Changes.'
    Configurations.png

Step 5: Adding the Login Widget to Your Site

  1. In the WordPress menu, click 'Appearance.'
  2. Then click 'Widgets.'
    plugins.png
  3. Under the Available Widgets Menu, find the 'ServiceTrade Service Portal Login' widget and click to drag it to the Widget Area to the right of the page.

Step 6: Adding New Portal Users

  1. In WordPress, on the Navigation bar, click on Settings.
  2. In the sub-menu that appears, click on General.
  3. Under New User Default Role select "Subscriber" from the dropdown menu.
  4. On the Navigation Bar, click 'ServiceTrade.'
  5. Click Add User.

  6. Follow these WordPress instructions.
    Note: It is also possible for users to request access through the login widget.

 

Removing Portal Users

  1. Under the ServiceTrade user section, deactivate the given user.
  2. Go to the desired user in the WordPress users section, and delete the user there.
    Note: Deleting users directly from the ServiceTrade users section does not currently work.

 

How Customer Access Works

The Service Portal finds your customers by searching in your ServiceTrade contact records for the customer's email address.

  • If the customer's email address matches one or more company-level contact email addresses in ServiceTrade, they can see jobs at locations under those companies.
  • If the customer's email address matches one or more location-level contacts in ServiceTrade, they will only be able to see jobs for those locations.

 

FAQs and Installation Troubleshooting

I'm testing my ServicePortal installation and getting a 'Failed to establish connection - please refresh your browser' error message. What do I do?

Make sure you are logged out of your Wordpress account when testing Service Portal

When setting up and testing the customer portal, you cannot be logged into the WordPress account while attempting to login to the portal for testing. Doing so will throw an error "Failed to establish connection - please refresh your browser and try again." 

You can either sign out of the Wordpress account and test the Service Portal login page, or you can open the Service Portal login page in an incognito window to ensure that you are not testing it as a signed-in WordPress user.

For further troubleshooting steps regarding this error message, check out our ServicePortal Troubleshooting article.

 

Is there a demo portal I can log into to see what the customer sees?

  • There is!  Go to www.aardvarkservice.net.  See the bottom right of the page.  Login information is printed right on the page, under the login box.

 

I get an error message at some point during installation.

Please carefully walk back through the installation steps above.

If you get the message: "ERROR: ServiceTrade API credentials are invalid." and you are certain that the username and password are correct, then this means that WordPress is having difficulty with the authentication. Type in an intentionally wrong password, click save, and then type in the correct password, clicking save again. This should force the WordPress plugin to re-authenticate.

If the error message is in the JS console, then SSH into your WordPress instance and tail -f on your Apache error_log while repeating the step that gives you an error.

I am being asked for API settings.

Please carefully walk back through the installation steps above, understanding that you need a ServiceTrade admin user to log the portal itself into ServiceTrade, and to allow data from ServiceTrade to flow into your website.

I don't see any content when I log into the portal.

Be sure to test what the customer would see in the portal by using an incognito window, or at least be signed out of WordPress. 

What happens when my customer requests a service through the portal?

  • An unscheduled Job will be created on the appropriate Location in your ServiceTrade account.
  • It's important to note that your customer must spell the name of the Location exactly as it is in your ServiceTrade account when they are requesting the service.

My user does not see anything when signed into the portal.

One of the following is happening: 

  • The portal is set up incorrectly, in which case no one would see any content.
  • The email address that is being used to log in does not match any company or location contacts within ServiceTrade.
  • There are server-side errors, which can be determined by right-clicking on the failing page, clicking "Inspect Element" and then clicking "Console."  Any error message will be in red.  A 500 or internal server error may appear.  If so, whoever has access to the web server should review Apache logs to determine what is going wrong. 

I am not getting notifications when new users sign up.  

Check the ServiceTrade settings within WordPress, and verify the notification email address. 

How do I customize the look of the Portal? 

Your web developer should be familiar with CSS and able to customize fonts, colors, etc.  It is usually straightforward to edit this CSS within WordPress Admin for the given theme that you are currently using.

For more information about customizing the CSS rules for your WordPress theme, please see these instructions.  The ServiceTrade Portal HTML is contained within a div element with a class name of servicetrade-portal. 

For instance, to make the border of all table headings in the Portal red, you could add the following custom CSS to your WordPress theme:

.servicetrade-portal th { border: 1px solid red; }


Can I change the content of the notification email that is sent when I approve an account?  

Not at this time, but we will add this in the future.


How do I upload documents to the portal?  

You cannot upload documents directly to Service Portal. You would upload documents to the relevant ServiceTrade Job. The Service Portal is essentially a collection of Service Links.  This article covers Service Link in full.


How do I start using the Service Portal before I have created a WordPress Site?

The Portal is a WordPress plugin, and having a WordPress site up and running is the first requirement.

If you do not wish to display a portal login widget or portal content across your site, or you do not wish to change your site to WordPress, you may consider creating a standalone WordPress site solely for the purposes of the portal.  This could be something like portal.yourcompany.com or client.yourcompany.com.  You could then link to the dedicated portal site from your main page or navbar. 


How do I import customer users?

There is no way to bulk import users at this time.

 

Does ServiceTrade Support my Service Portal?

  • ServiceTrade can set up and configure the customer portal as a professional service.
    As outlined in the Support Services Terms, ongoing maintenance and administration of the portal content and data is the customer's responsibility as the owners and operators.
  • For standard support included with the customer's subscription, ServiceTrade can provide general guidance but is not contractually obligated to directly resolve portal technical issues in real-time unless they affect the core ServiceTrade application.
  • ServiceTrade's goal is to empower customers to self-manage routine portal administration where possible. However, per the Support Terms, ongoing accountability for portal uptime and functionality ultimately resides with the customer and their Designated Contacts unless a paid support agreement is in place.
  • ServiceTrade setup, ongoing maintenance, and support of the customer portal can be purchased with a subscription to the Technical Account Management (TAM) service.
  • Please contact us if you need help designating Portal Administrators, have any other portal governance questions, or would like a quote to upgrade your support contract for full ServiceTrade management of the customer portal.

Was this article helpful?

/

Comments

0 comments

Please sign in to leave a comment.