Skip to content

Implementation Example

The JustOn Self-Service Extension includes an example implementation that demonstrates the provided functionality. You can use this demo site as a model when creating your own implementation, or just modify the example, adjusting it to your requirements.

The example implementation includes the following components:

sse_site
Implemented example site

Login Page

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 page uses the following custom labels, which are to be overwritten:

  • Login
  • LoginTeaser
  • LoginOAuth
  • LoginPassword
  • Username
  • Password
  • LoginFinePrint
  • LoginWithAmazon
  • SignInWithGoogle
  • LoginWithPaypal

Products Page

Info

The products page is only visible for authenticated users. Otherwise it redirects to the login page.

Features

The example products page shows all master items and master products, which are available for checkout. The items are retrieved using the MasterItemRetriever.

Info

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.

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.

Used Custom Labels

The page uses the following custom labels, which are to be overwritten:

  • Products
  • MasterItems
  • MasterItemTeaser
  • add
  • MasterItemFinePrint
  • Cart
  • CartTeaser
  • remove
  • checkout
  • CartFinePrint

Additional Configuration

Product Images

If there is an image attachment found on the master item or master product, it is displayed as the product logo.

Master Item Fields

You can define the fields of the master item that are to be displayed on the products page. To this end, use the global setting Master Item Fields:

  1. In Setup, open Custom Settings.

    In Salesforce Lightning, navigate to Custom Code > Custom Settings.

    In Salesforce Classic, navigate to Develop > Custom Settings. 2. Click Manage in the row of Global Settings. 3. Click Edit in the row of Default. 4. In Master Item Fields, specify the fields to be shown on the Products page. 5. Click Save.

Info

If there is no setting specified, it defaults to ONB2__Title__c,ONB2__Description__c.

Sort Order

You can define the display order of master items and master products. To do so, use the global settings Master Item Sort Order or Pricebook Entry Sort Order, respectively.

  1. In Setup, open Custom Settings.

    In Salesforce Lightning, navigate to Custom Code > Custom Settings.

    In Salesforce Classic, navigate to Develop > Custom Settings. 2. Click Manage in the row of Global Settings. 3. Click Edit in the row of Default. 4. In Master Item Sort Order or Pricebook Entry Sort Order, specify the SOQL order statement. 5. Click Save.

Info

If there is no sort order defined, it defaults to the creation date.

Shopping Cart Fields

You use the custom setting Cart to define which fields of an item are visible after the item has been added to the shopping cart.

Field Possible Values Description
Name string A unique name for the record.
Fieldname any item field The API name of the field of the ONB2__Item__c object to be displayed, like ONB2__Title__c.
Must be enabled in the Public Access Settings of the Force.com site.
Read Only (checkbox) true
false
Determines whether the field is editable or not.
Required (checkbox) true
false
If the field is set editable, this setting determines whether it is required or not.
Sequence positive integer A number that defines the display order of the cart fields.
Type any, including empty The field is only shown for items with that specific type.
You must add the field ON_ProductType__c to the Item object and the Product2 object if you use master products

Note

Create a Cart record for each field to be visible.

  1. In Setup, open Custom Settings.

    In Salesforce Lightning, navigate to Custom Code > Custom Settings.

    In Salesforce Classic, navigate to Develop > Custom Settings.

  2. Click Manage in the row of Cart.

  3. Click New.
  4. Specify the information as necessary.
  5. Click Save.

Info

If there are no cart fields defined, the system falls back to Title (read only) and Quantity (editable).

Subscriptions Page

Info

The subscriptions page is only visible for authenticated users. Otherwise it redirects to the login page.

Features

The example subscriptions page shows all subscriptions for the authenticated user. The page 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 FirstSubscriptionInfo.

Optionally, the page can display a welcome message. To do so, provide the parameter welcome=true.

Used Custom Labels

The page uses the following custom labels, which are to be overwritten:

  • Subscriptions
  • SubscriptionsWelcomeMessage
  • ActiveSubscriptions
  • SubscriptionsTeaser
  • FirstSubscriptionInfo
  • Position
  • Title
  • UnitPrice
  • Quantity
  • SubscriptionsFinePrint

Account Statement Page

Info

The account statement page is only visible for authenticated users. Otherwise it redirects to the login page.

Features

The example account statement page shows all balances associated to the account of an authenticated user.

The page shows the list of balances in chronological order. There is a field set that allows to configure which balance fields are displayed in the balance table (see Adjusting Balance Table).

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.

Used Custom Labels

The page uses the following custom labels, which are to be overwritten:

  • Balances
  • From
  • Print
  • StatementOfAccountTeaser
  • StatementsOfAccountEnd
  • StatementOfAccountFor
  • StatementOfAccountStart
  • StatementsOfAccountTotal
  • StatementOfAccountFineprint
  • Until
  • Update

Adjusting Balance Table

To configure which balance fields are displayed in the balance table:

  1. Navigate to the field sets definition of the Balance object.

    In Salesforce Lightning, navigate to Setup > Object Manager > Balance > Field Sets.

    In Salesforce Classic, navigate to Setup > Create > Objects > Balance > Field Sets.

  2. Click Edit in the Account Statement row.

  3. Move the fields to or from the In the Field Set container and reorder them as required.
  4. Click Save.

Invoices Page

Info

The invoices page is only visible for authenticated users. Otherwise it redirects to the login page.

Features

The example invoices 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.

Used Custom Labels

The page uses the following custom labels, which are to be overwritten:

  • Invoices
  • InvoicesTeaser
  • InvoiceNo
  • InvoiceDate
  • PaymentAmount
  • InvoiceStatus
  • PDFLink
  • ViewInvoice
  • InvoicesFinePrint

Payment Page

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.

Info

The payment process implementation is payment provider-specific.

Enabling Access to Payment Page

Once the JustOn Self-Service Extension is properly set up to function with the payment page, JustOn can create a link to the payment page for a given invoice. You can include this link to your invoice email in order to redirect your users to the payment page.

To configure and use the payment page link:

General Payment Process

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

Info

The payment page is also visible for unauthenticated users.

Used Custom Labels

The page uses the following custom labels, which are to be overwritten:

  • PayeezyWarnClose
  • PayeezyNoCvc
  • NoInvoiceAvailable
  • PaymentCancel
  • PaymentException
  • PaymentUseOtherPaypalPaymentOption
  • PaymentPaypalTokenTimedOut
  • PaymentSuccess
  • InvoiceSummary
  • DownloadPDF
  • InvoiceNo
  • InvoiceDate
  • InvoiceNet
  • InvoiceTax
  • InvoiceGrandTotal
  • InvoiceReceived
  • InvoicePaymentAmount
  • PayNow
  • Cancel
  • PaymentTeaser
  • PaymentFinePrint
  • PaymentOptions
  • PaymentAmount
  • CardNumber
  • CardIssuer
  • CvcHelp
  • Expires
  • CardHolder
  • PaymentFinePrintStripeCreditcard
  • PaymentFinePrintStripeSepa
  • PaymentFinePrintStripeAlipay

Info

The custom labels PaymentFinePrintStripeCreditcard, PaymentFinePrintStripeSepa and PaymentFinePrintStripeAlipay are displayed when using Stripe as the payment provider. Make sure to provide an appropriate text for these labels before going live with Stripe. For example, the label PaymentFinePrintStripeSepa should show the SEPA mandate acceptance notification.

To customize your payment page, you can add a logo image.

  1. Create a corresponding style record.
  2. Set the Payment Page as the target page.
  3. Provide the following content:

    .content::before {
        content: url(<image_path>);
        display: block;
        text-align: center;
    }
    

Profile Page

The example 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.

Info

The profile page is only visible for authenticated users. Otherwise it redirects to the login page.

Configuring Visible Fields

The page shows all contact and account fields that are configured using the custom setting Profile.

Note

Create a Profile record for each field to be visible on the profile page.

  1. In Setup, open Custom Settings.

    In Salesforce Lightning, navigate to Custom Code > Custom Settings.

    In Salesforce Classic, navigate to Develop > Custom Settings.

  2. Click Manage in the row of Profile.

  3. Click New.
  4. Specify the information as necessary.

    For details, see Profile.

  5. Click Save.

Info

Fields may require a value. If they are empty and the profile is therefore considered incomplete, the user is always redirected to the Profile Edit page until all required information is provided.

Once the profile is complete, the user is redirected to the page defined in the global setting Redirect after profile complete.

Overriding Field Labels

You use record of the custom setting Field Label to override the field labels of updatable fields. Labels that are not overwritten show the default label, which is also visible in Salesforce.

Field Description
Name A unique name for the record.
Object Name The name of the target object, like Account or Contact.
Field Name The API name of the target field, like BillingStreet or ONB2__TaxNumber__c.
Label The text to use to override the original label.

Note

Create a Field Label record for each field to be overridden.

  1. In Setup, open Custom Settings.

    In Salesforce Lightning, navigate to Custom Code > Custom Settings.

    In Salesforce Classic, navigate to Develop > Custom Settings.

  2. Click Manage in the row of Field Label.

  3. Click New.
  4. Specify the information as necessary.
  5. Click Save.
Multi-Language Configuration

If you use multiple languages, you can define additional fields using the Field Label custom setting that hold language-specific translations for labels:

Field Name Data Type Description
de Text (255) German translation
en Text (255) English translation
en_GB Text (255) British English translation
fr Text (255) French translation

Make sure to provide a field and translation for each activated language. If there is no language-specific field or content, the system uses the content of the Label field.

Used Custom Labels

The page uses the following custom labels, which are to be overwritten:

  • Profile
  • ProfileTeaser
  • Edit
  • Save
  • Cancel
  • ProfileFinePrint

CSV Upload Page

Info

The CSV upload page is only visible for authenticated users. Otherwise it redirects to the login page.

Features

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.

Note

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 4 lines to skip.

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.

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
Text
TextArea
Picklist
Character String This is a text.
Number
Percent
Currency
Number with the point (.) as the decimal separator and without digit group separators 12345.67
Currency ISO Code ISO 4217 three-letter currency ISO code USD
EUR
Date ISO-8601 date format 2019-03-05
Date/Time ISO-8601 datetime format 2019-02-26T16:02:39-02:00
Checkbox true|false
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.

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.

Error Type 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.

Setup

Upload Configuration

The upload is configured via the custom metadata type CSV Upload Settings.

The most relevant settings include the field Target, which specifies the sObject target object, and the the field Mapping, which specifies the mapping from the CSV columns to the target object fields.

In addition, you can write the account and contact data from the login session to the target object. To this end, set the values for Account Field and Contact Field to the field API name of the corresponding target object.

Field Required Possible Values Description
Active true|false Determines whether the configuration is available in the UI.
Target API name of an sObject Determines the target sObject for the upload.
Account Field API name of an sObject field Determines the target field for the login session account value.
Contact Field API name of an sObject field Determines the target field for the login session contact value.
Mapping map in JSON format Mapping from CSV row to sObject API field name.
Parse Chunk Size size in Bytes Determines the chunk size for reading from the input file on client side. Default is 10 MB.
Upload Scope number of records Determines the number of Salesforce records that are uploaded to the server in one step, defaults to 100.
Delimiter delimiter character Allows to overwrite the automatic delimiter detection of the parser.

Info

If Multi-Currency Support is enabled, use CurrencyISOCode as target field name for the currency ISO code.

Data mapping example
{
  "Total Amount" : "Amount__c",
  "Start Date" : "Date__c",
  "Currency" : "CurrencyISOCode",
  "Info" : "Text__c"
}

Note

You must create at least one CSV Upload Settings record. Otherwise, the CSV upload page is not displayed.

To edit the custom metadata type CSV Upload Settings:

  1. In Setup, open Custom Metadata Types.

    In Salesforce Lightning, navigate to Custom Code > Custom Metadata Types.

    In Salesforce Classic, navigate to Develop > Custom Metadata Types.

  2. Click Manage Records in the row of CSV Upload Settings.

  3. Click New, or click Edit to modify an existing custom metadata record.
  4. Specify the information as necessary.
  5. Click Save.

Info

You can create multiple CSV upload settings to support different data upload scenarios. Note that in this case, JustOn always uses the first active setting found, so make sure to activate/deactivate the settings as necessary.

Public Access Settings

The upload requires Read, Create, Edit and Delete permissions for the target object as well as Edit access for all fields that are specified by the CSV Upload Settings.

  1. Open the Site Details of your site.

    In the Sites list, click the label of the site to open its details.

  2. Click Public Access Settings to open the site profile.

  3. In the Original Profile User Interface, click Edit.

    If you use the Enhanced Profile User Interface, click Object Settings > Target Object > Edit.

  4. Enable the object permission settings Read, Create, Edit and Delete to the target object, and the enable the field permission Edit Access for all required fields.

  5. Click Save.

Used Custom Labels

The page uses the following custom labels, which are to be overwritten:

  • CSVUploadTeaser
  • CSVUploadNoSettings
  • CSVUploadInvalidTarget
  • CSVUploadInvalidData
  • CSVUploadNoMappedData
  • CSVUploadCheckDelimiter
  • CSVUploadSetValueError
  • CSVUpload
  • CSVUploadSelectFile
  • CSVUploadSkipFirstHelp
  • CSVUploadSkipFirst
  • CSVStartUpload
  • CSVUploadStarting
  • CSVUploadSuccessful
  • CSVUploadInProgress
  • CSVUploadError
  • CSVParseError
  • CSVFileError
  • CSVUploadFailedAtLine
  • CSVUploadWarnClose
  • CSVUploadFinePrint
  • PleaseSelectFile
  • PleaseSelectOnlyOneFile
  • NoValidNumber

The header component is used on every page. It displays a logo and the site name, as well as the site navigation.

Note

The image file that you intend to use as the site logo must be stored as a file in the Salesforce Documents tab and selected as Externally Available Image.

The logo file is enabled in the global setting Logo Name:

  1. In Setup, open Custom Settings.

    In Salesforce Lightning, navigate to Custom Code > Custom Settings.

    In Salesforce Classic, navigate to Develop > Custom Settings.

  2. Click Manage in the row of Global Settings.

  3. Click Edit in the row of Default.
  4. In Logo Name, specify the name of the logo image file.
  5. Click Save.

    This includes the specified file as the logo in the page header.

Defining Home URL

You can specify a URL that is to be opened when a user clicks the site logo or site name - usually, the site home page. The link target is defined in the global setting Home URL:

  1. In Setup, open Custom Settings.

    In Salesforce Lightning, navigate to Custom Code > Custom Settings.

    In Salesforce Classic, navigate to Develop > Custom Settings.

  2. Click Manage in the row of Global Settings.

  3. Click Edit in the row of Default.
  4. In Home URL, specify the intended URL.
  5. Click Save.

    The specified URL is now opened when a user clicks the site logo or site name.

Info

If there is no URL configured, clicking the site logo or site name has no effect.

Used Custom Labels

The component uses the following custom labels, which are to be overwritten:

  • SiteName
  • SiteDescription

The footer component is used on every page. It displays a footer text.

The component uses the following custom labels, which are to be overwritten:

  • Footer
  • Footer2
  • Footer3

Logout

The logout component is used on every page. It displays the user name, the identity provider and a logout button.

The component uses the following custom labels, which are to be overwritten:

  • Logout