Service Portal Installation Guide

Derek Torres
Derek Torres
  • Updated

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.

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

Service Portal users may 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.  To see how Service Link works and which types of information is displayed on a Service Link, please take a look at this article.

Service Portal users who are allowed access to see quotes may click on any quote to see that quote, even if you have not sent that quote to them.  For more information about quotes in ServiceTrade, please review this article.

Service Portal users who are allowed access to see prices may click on any invoice to see that invoice, even if you have not sent that invoice to them. For more information about invoices in ServiceTrade, please review this article.

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.

Usage 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

Installing the Service Portal

The steps below will walk you through installing Service Portal.

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 accordian.
  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 that 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 'ServiceTrade'.
  2. Click Add User.

  3. 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 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

 

Is there a demo portal that 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.  See the video walkthrough also, where we set up the portal from scratch on an example WordPress site.

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 document directly to Service Portal. You would upload documents to the relevant ServiceTrade Job. The Service Portal what 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.mycompany.com or client.mycompany.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.

Who do I contact for support during installation?

What is your scope of support?

We will provide Q&A assistance to any developers installing the portal.

General knowledge of WordPress and administering a web server is assumed.

Can ServiceTrade Support install the portal for me?

Absolutely.  We will set up your portal for you at our normal billable rate. 

Portal setup takes approximately 2 hours.

If you'd like us to install the portal for you, please send an email to support@servicetrade.com with WordPress Admin credentials, SSH info, and SSH credentials. 

Was this article helpful?

/