Self-Service Portal Overview
Using the JustOn Self-Service Extension you set up a public web application based on Force.com Sites.
The JustOn Self-Service Extension includes a ready-to-use implementation that provides the complete functionality. You can modify the included implementation to suit your needs, or use the shipped components to build your self-service app from scratch.
The complete implementation includes the following components:
- Login page
- Product page
- Subscription page
- Account statement page
- Invoice page
- CSV upload page
- Profile page
- Payment page
- Direct debit mandate page
- Header, Footer, Logout
This article gives an overview of the provided components, explaining important concepts and outlining the components' functionality.
At first access, the login page shows a login button for each configured identity provider. A returning user only sees the button of the last used identity provider. This information is stored in a cookie.
Authenticated users are redirected to the page defined in the global setting
Redirect after login.
The products page is only visible for authenticated users. Otherwise it redirects to the login page.
The product page shows all master items and master products (see below) that are available for checkout. The items are retrieved using the MasterItemRetriever.
Typically, you choose to present either master items or master products for checkout, depending on your business requirements. You can, however, combine the two approaches.
If there is an image attachment found on the master item or master product, it is displayed as the product logo.
Users can add master items and master products to a cart. Once an item or product has been added to the cart, users can change its quantity. The page considers scaled prices and commissions defined for the master items.
When users click Checkout, the page calls the SubscriptionManager, which creates or updates a subscription. After the subscription has been created, the user is redirected to the subscriptions page, on which the new subscription is highlighted.
Master items are items that are not linked to a subscription. They are intended to be available on the Products page for checkout.
Master items must match the following criteria:
- they are not linked to a subscription
- they must be active
- they must match the criteria defined in the global setting
Master Item Criteria
Master items are sorted by their creation date or the criteria defined in the global setting
Master Item Sort Order.
Master products are products from specific price books that are to be available on the Products page for checkout.
The price book as the "source" for the master products is configured in the global setting
The price book can, however, be overwritten on the account. To this end, create a lookup field on the account for the price book with the name
ON_PriceBook__c. For help about creating fields, see Managing Object Fields.
Master products must match the following criteria:
- Price book is linked to the global settings or the account
- Price book is active
- Price book entry is active
Master products are sorted by their creation date or the criteria defined in the global setting
Pricebook Entry Sort Order.
Field mapping: Master product - Item
Master products are converted to items once they are retrieved from the database. The following field mapping is used:
|Price Book Entry/Product Field||Item Field||Description|
|Product2.ProductCode||Name||The order number of the item|
|PricebookEntry.CurrencyIsoCode||CurrencyIsoCode||Only in multi-currency orgs|
|Product2.Id||ON_Product (Lookup Product2)||Only if the field is available on the item|
|Product2.ON_ProductType__c||ON_ProductType__c||Both fields must be present in order to make the cart fields by type configuration work|
|Product2.ON_*||matching fields||ON fields are copied from the product to the item if they are available|
For details about setting up the product page, see Enabling Product Page and Shopping Cart.
The subscriptions page is only visible for authenticated users. Otherwise it redirects to the login page.
The subscription page shows all subscriptions for the authenticated user. It uses the SubscriptionRetriever in order to get the subscriptions of the current user.
The page shows the list of subscriptions in reverse chronological order. Each subscription shows the name, creation date and a list of items. Each item shows the title, unit price and quantity.
If the first subscription is highlighted (after checkout), the page shows the additional label
For details about setting up the subscription page, see Enabling Subscription Display.
Account Statement Page
The account statement page is only visible for authenticated users. Otherwise it redirects to the login page.
The account statement page shows all balances associated to the account of an authenticated user.
Users can limit the scope of the listed balances through setting a start date and an end date.
If a balance refers to an invoice, the table entry includes a link to the payment page for displaying the corresponding invoice overview. From there, users can view or download the invoice PDF, and, if there are configured payment providers, trigger the payment process for the current invoice.
In addition, the account statement page includes a Print button and provides a print style sheet.
For details about setting up the account statement page, see Enabling Account Statement Display.
The invoices page is only visible for authenticated users. Otherwise it redirects to the login page.
The invoice page shows all invoices for the authenticated user. The page uses the InvoiceRetriever in order to get the invoices of the current user.
The page shows the list of invoices in reverse chronological order. Each invoice shows the invoice number, date and payment amount, as well as a link to the invoice PDF file.
For details about setting up the invoice page, see Enabling Invoice Display.
CSV Upload Page
The CSV upload page is only visible for authenticated users. Otherwise it redirects to the login page.
The CSV upload page allows to upload data from CSV files to an arbitrary Salesforce object. See this, basically, as a way to "feed" usage data to be billed to JustOn. Think, for example, of scenarios like service staff who register their worked hours, or brokers who register deals - all as guest users via the JustOn Self-Service Extension.
If set up accordingly, JustOn creates an object record for each data row of the CSV file. The upload is configured by the custom metadata type CSV Upload Settings, which specifies the Salesforce target object and the data mapping.
For tracking and debugging purposes, the JustOn Self-Service Extension uploads the original CSV file (truncated at 2 MB) to Salesforce. Using the session information, the file is associated with the account of the user who has triggered the upload operation.
Make sure your users are made aware of the following specifics:
- Do not close the browser window nor reload the page while an upload is running. This would stop the upload progress at an indeterminate point.
- When specifying line numbers to skip, always include the header line. If, for example, you want to skip the first three data rows, you have to specify
4lines to skip.
- Upon upload, all CSV rows are processed and the corresponding records are created, irrespective of the original file size. However, Salesforce truncates the file attachment at 2 MB.
Implementation details: Large file processing
The upload allows to process large files. On the client side, the parser reads and parses data from the input file in chunks. If a certain number of CSV rows have been parsed, the data is uploaded to the Salesforce org, creating the corresponding object records. If required, both the chunk size of the file read and the size of the upload scope can be specified in the custom metadata type CSV Upload Settings. Parse errors are ignored as long as the CSV input row can successfully be converted to the Salesforce target object.
Implementation details: CSV requirements
The CSV file requires a header row that specifies the column names. The mapping of the CSV column names to the target object fields is configured in the custom metadata type CSV Upload Settings.
The values from the CSV file data rows are automatically converted to the data type of the target field of the target object. The following table shows the supported data types and source data formats:
|sObject Data Type||Supported CSV Column Format||Examples|
|Character String||This is a text.|
|Number with the point (
|Currency ISO Code||ISO 4217 three-letter currency ISO code||USD
|Date||ISO-8601 date format||
|Date/Time||ISO-8601 datetime format||
Implementation details: Data mapping specifics
The data mapping specifies which column of the CSV input file is written to which field of the Salesforce target object. If a CSV column name is not specified by the mapping, it is ignored. This allows to upload CSV files that contain more columns as required for the upload without having to edit the input file.
Implementation details: Error handling
In case of an error, the page shows the line number of the input file that could not be processed. All lines up to this line have been processed and uploaded to the Salesforce org. The
Skip lines field is automatically set to the number of successfully processed lines. This allows to continue the upload process starting with the failed line after you have corrected the error.
The error messages displayed on the page show the error type and a detailed error description.
|File Error||Error reading the input file.|
|Parse Error||Error message created by the client side parser. Parse errors are ignored if the data has been uploaded successfully.|
|Upload Error||Error message created by the server if the creation of the target object has failed.|
When specifying line numbers, the page always includes the header line. If, for example, an error is shown for line
10, all lines up to line
9 have been processed (one header row and eight data rows), which means that eight records of the target object have been created.
The upload tries to process as many input data as possible, ignoring parse errors as long as target objects can be created. In order to ensure that the created data records are correct, JustOn recommends to create validation rules for the target object that prevent invalid data to be written to the database.
For details about setting up the CSV upload, see Enabling CSV Upload.
The profile page is only visible for authenticated users. Otherwise it redirects to the login page.
The profile page enables users to modify their account and contact information, like name, email or billing address. The page uses the DefaultSessionHandler in order to retrieve the account and contact information.
The profile page shows all contact and account fields that are configured using the custom setting Profile. To overwrite the field labels of updatable fields, you use records of the custom setting Field Label .
For details about setting up the profile page, see Enabling Profile View.
The payment page is visible for unauthenticated users.
The payment page shows an overview of an invoice and allows users to view or download the invoice PDF. If there are configured payment providers, the page also displays buttons to trigger the payment process for the current invoice.
The payment process implementation is payment provider-specific.
Once the JustOn Self-Service Extension is properly set up to function with the payment page, JustOn creates a link to the payment page for a given invoice. You can add this link to your invoice email in order to redirect your users to the payment page. To this end, include the placeholder
[PaymentLink] to the email body of your invoice template. In addition, you can, optionally, enable the payment link display on the invoice record.
General payment workflow
(1) The user clicks Pay Now for one of the available payment providers.
(2) This displays an input form that allows to enter the banking details.
(3) The user clicks the pay button of the input form.
(4) If the input data is not valid, the input form displays an error message.
(5) If the input data is valid, the amount of the invoice is captured.
(6) If the capture is successful, JustOn creates a Balance record for the captured amount, and displays the success message. The balance field
TransactionNo is set to a provider-specific transaction number for this capture.
(7) If the capture is not successful, JustOn creates a Payment Entry record that holds the provider-specific information about the failed capture, and displays an error message.
For details about setting up the payment integration, see Payment-Specific Site Setup.
Direct Debit Mandate Page
The direct debit mandate page is visible for unauthenticated users.
The direct debit mandate page works independently from the payment page and does not require a payment provider integration.
Via the direct debit mandate page, users can provide their bank details, granting a SEPA direct debit mandate to your business. If they do, JustOn saves the mandate and the bank details with the user's account as well as the invoices. Consequently, this allows you to generate corresponding bank transfer orders to collect due payments.
If there already is a SEPA mandate and bank details saved with the user's account, the page displays the available information. Otherwise, the user is prompted to specify the corresponding details.
JustOn validates the format and structure (length, allowed characters, etc.) of the provided IBAN and BIC. This check does not necessarily prove, however, that the given bank account actually exists.
Once the JustOn Self-Service Extension is properly set up to function with the direct debit mandate page, JustOn creates a link to the direct debit mandate page for a given invoice. You can add this link to your invoice email in order to redirect your users to the direct debit mandate page. To this end, include the placeholder
[DirectDebitMandateLink] to the email body of your invoice template. In addition, you can, optionally, enable the direct debit mandate link display on the invoice record.
For details about setting up the direct debit mandate page, see Enabling Direct Debit Mandate Display.
Header, Footer, Logout
The header component is used on every self service-specific page. It displays a logo and the site name, as well as the site navigation.
The footer component is used on every self service-specific page. It displays the footer text as specified in custom labels.
The logout component is used on every self service-specific page. It displays the user name, the identity provider and a logout button.
For details about configuring the site logo, see Configuring Site Logo.
For details about adjusting header, footer and logout labels, see Configuring Header, Footer and Logout Labels.