This article discusses installation and basic usage instructions for version 2 (v2) of the ServiceTrade Service Portal plugin. For information about the version 1 (v1) plugin, please review this article. For information on administering the portal as an office user, please review this article.
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 review 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 send that quote to them. For more information about quotes in ServiceTrade, please review this article.
- The Service Portal is a Wordpress Plugin.
- PHP 5.5 or above with mcrypt extension and cURL extension
- WordPress 4.7 or above
- WordPress must be able to send emails using wp_mail - we recommend WP-Mail-SMTP extension
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 PORTAL - VIDEO WALKTHROUGH
Please use this video walkthrough in conjunction with our written instructions in this guide (below the video).
INSTALLING THE PORTAL - WRITTEN WALKTHROUGH
IMPORTANT: If you currently using the v1 portal plugin, please follow these migration instructions to ensure that all your portal customer users are migrated to the v2 portal properly.
Step 1: Install the Service Portal 2.0 Wordpress Plugin
If installing anew, rather than upgrading, please continue following the instructions below:
- Download the portal plugin zip file from the ServiceTrade Extensions site.
- Log into WordPress as an admin and click on 'Plugins'
- Click 'Add New'
- Click 'Upload Plugin'
- Click the file chooser and select the portal zip file, then click 'Install Now'
- Once the portal is installed, click 'Activate'
Step 2: Configure the Plugin:
- In ServiceTrade, create a new user for the portal plugin to use. (We do NOT recommend using one of your existing users.) Grant that ServiceTrade user the 'Account Admin' role. IMPORTANT: It is highly recommended to not use a person's existing login for this or any other integration. Instead, acquire credentials for or create a dedicated ServiceTrade admin user that is obviously a bot. Example: "mycompanyname.servicetradeportal"
- Log into app.servicetrade.com as that newly created user and accept the ServiceTrade End-User License Agreement, then log out. Be certain that these credentials will log you into ServiceTrade before proceeding.
- Create a new WordPress page that will contain the portal. You may give this page any title that you wish, though we recommend a descriptive name such as 'Service Portal'. The content of the page should be just shortcode for the portal, which is: [servicetrade-service-portal][/servicetrade-service-portal]
- Make a note of the permalink for this page. You will need to enter it into the portal configuration page.
- Click on the 'ServiceTrade' option in the WordPress menu, then click 'Settings'.
- On the Portal configuration page, enter the following information:
Name: Enter the username for the ServiceTrade portal user that you just created.
Password: Enter the password for the ServiceTrade portal user that you just created.
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).
- If you want your customers to be able to request services through the portal, click the 'Request Service' checkbox.
- Click 'Save Changes'
Step 3: Adding the Login Widget to Your Site
- In the WordPress menu, click 'Appearance', then choose 'Widgets'.
- Drag the 'ServiceTrade Service Portal Login' widget to the Widget Area.
Step 4: Adding New Portal Users
- Under the ServiceTrade option in the WordPress menu, click Add User and fill out the form.
- It is also possible for users to request access through the login widget.
Step 5: Removing Portal Users
- Under the ServiceTrade user section, deactivate the given user.
- Then go the the user in the WordPress users section, and delete the user there.
- 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 will be able to 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.
FAQ 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 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.
- Revisit the technical requirements above. Your Apache error_log may reveal that you do not have mcrypt installed. Install mcrypt for PHP according to the relevant procedure for your distribution.
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.
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.
My Service Portal page looks different than I expect it to.
- Consult with your web designer, as the Service Portal uses your CSS.
- Use the WordPress built-in theme editor
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.
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.
Why are there settings for invoices, but my customers do not seem to be able to see invoices?
- Invoices are not yet supported in the Portal, but will be in the near future.
How to I upload documents to the portal?
- Understand that on the Portal we are showing 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?
- Understand that the Portal is a WordPress plugin, and that 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 email@example.com with WordPress Admin credentials, SSH info, and SSH credentials.