# parcelLab Customer Service for SFSC Integration Guide
## Overview
The parcelLab Customer Service Integration for Salesforce Service Cloud (SFSC) enables your customer service agents to answer delivery-related questions faster. The app enables viewing of all relevant tracking information in real time for orders and can be added to any object within your Service Console (for example: Account, Case, Order).
In this tutorial, you will learn:
* how to [generate a parcelLab API token with the required scope](#how-to-generate-a-parcellab-api-token)
* how to [configure the parcelLab SFSC integration](#configuring-the-parcellab-customer-service-integration-for-sfsc), including:
* [Defining credentials for displaying general app content](#defining-credentials-for-displaying-general-app-content)
* [Configuring the display of a link to the parcelLab App](#configuring-the-display-of-a-link-to-the-parcellab-app)
* [Configuring the necessary fields for displaying order data in the parcelLab app](#configuring-the-necessary-fields-for-displaying-order-data)
* [Adding the parcelLab app to a page layout](#adding-the-parcellab-app-to-a-page-layout)
## Requirements
Before you start, ensure the following prerequisites are met:
* SFSC
* Admin user access
* parcelLab
* Account with tracking data enabled
* One of the following:
* SSO for parcelLab App access
* One user’s login credentials for parcelLab App access
* Non-encoded API token with `Salesforce` scope
* Link to install the parcelLab app in Salesforce
How to generate a parcelLab API token
Before proceeding with setup in Salesforce, you will need an API token with the required scope from parcelLab. This API token can be generated in the parcelLab App by users with any of the following App permissions:
* Account Setup Admin (group)
* Manage API Tokens (role)
{% hint style="info" %}
For implementing the SFSC app, you will need the non-encoded API token.
{% endhint %}
To generate a new API token:
1. Click **Add API Token**.
The Add API Token page will display.
2. In the Scopes section, select the **Salesforce** checkbox.\
This ensures that your API token has the correct technical scope for use in the Salesforce Service Cloud integration.\
3. Add a description of what you will use the token for.
4. Enter your email address.\
The email address entered will be used for technical inquiries.
5. Click **Save**.\
Your API token is generated and a confirmation banner will display at the top of the list of your API tokens. A one-time notification banner will display the API token created, with an encoded token and non-encoded token (to be used with the `user_id`) shown.
6. To copy the newly created token, click the **Copy** button for the encoded or non-encoded token.
The API token is copied to your clipboard.
{% hint style="warning" %}
Save the copied tokens somewhere safe. This is important because you will not be able to view the tokens after navigating away from the page.
{% endhint %}
## Installing the parcelLab Customer Service Integration for SFSC
This section describes how you can install the parcelLab Customer Service Integration for SFSC.
To install the app:
1. Log in to your Salesforce account as an admin user.
2. Open the link you received from your parcelLab representative.
3. Select the level of access (for example: **Install for all users**).\
This permission provides access to the app page in Salesforce, which contains details about how to generate new API tokens. It does not control permissions for accessing and using the app after it has been added to an object.
4. Click **Install**.\
After the installation is complete, a success message will display.
You can find the installed parcelLab app in your Salesforce account under **Setup** > **Platform Tools** > **Apps** > **Packaging** > **Installed Packages**.
{% hint style="info" %}
Future app versions and updates will be pushed automatically to your environments.
{% endhint %}
## Configuring the parcelLab Customer Service Integration for SFSC
This section describes how you can configure the parcelLab Customer Service Integration for SFSC after it has been successfully installed.
{% stepper %}
{% step %}
### Defining Credentials for Displaying General App Content
To configure credentials that will enable the display of general app content, specify authentication settings in Salesforce as follows:
1. Click on the **Setup** icon on the top right of your Service Console.
The Setup Menu will display.
2. Click **Setup**.\
Setup Home opens in a new browser tab.
3. In the search field, enter “Named Credentials”.
4. In the dropdown menu, select the setup option **Named Credentials**.
The Named Credentials list page will display.
5. Click **New**.
The configuration page for app credentials will display.
6. In the **Label** field, enter a label that will be used to identify the API credentials (for example: Company\_UK).
If you have multiple parcelLab accounts, the label should be descriptive as you will need to reference it during additional configurations.
The **Name** field is automatically filled after a label has been entered in the Label field.
{% hint style="info" %}
When creating test credentials, do not use "ParcelLabTestCred" in the Label and Name fields. A set of credentials with this label come with the package for different purposes and should not be used for an actual setup.
{% endhint %}
7. In the **URL** field, enter .
8. For the **Identity Type**, select **Named Principal**.
9. For the **Authentication Protocol**, select **Password Authentication**.
Text fields for Username and Password will display.
10. In the **Username** field, enter your parcelLab user ID.
The parcelLab user ID can be requested from your parcelLab representative or retrieved from the [parcelLab App](https://app.parcellab.com/service/account/account/) under **Admin** > **Accounts**.
11. In the **Password** field, enter your non-encoded parcelLab token.
The token can be requested from your parcelLab representative or generated in the parcelLab App under **Admin** > **API Tokens**.
12. Click **Save**.
The New Named Credential is saved.
{% endstep %}
{% step %}
### Configuring the Display of a Link to the parcelLab App
To display a link to the parcelLab App:
1. In **Named Credentials**, click **New**.
The configuration page for app credentials will display.
2. In the **Label** field, enter the label that was used in the initial configuration (for example: Company\_UK) and add “\_Magic”.
This identifies that the app that is configured for the UK account should display a link to the space.vars.Product\_pLApp.
Following our example, the label entered in this step will be “Company\_UK\_Magic”.
3. In the **URL** field, enter .
4. For **Identity Type**, select **Named Principal**.
5. For **Authentication Protocol**, select **Password Authentication**.
Text fields for Username and Password will display.
{% hint style="info" %}
If you have implemented Single Sign-On (SSO) for your parcelLab App access, you do not need to enter any information into the Username and Password fields.
{% endhint %}
6. In the **Username** field, enter the email address of a parcelLab App user.
7. In the **Password** field, enter the user’s password.
8. Click **Save**.\
The New Named Credential is saved.
{% hint style="info" %}
For this configuration, please contact your parcelLab representative if you require a technical user account for App access. The login credentials of this technical user will be used for all service agents working with the parcelLab Customer Service Integration in Salesforce.
{% endhint %}
{% hint style="success" %}
After the app configuration is complete, you can add the lightning component to any object within a page layout, so your customer service agents can access it from your Service Console.
{% endhint %}
{% endstep %}
{% step %}
### Configuring the Necessary Fields for Displaying Order Data
Before adding the parcelLab App to the page layout where you intend to use it, you need to define the following fields in the object’s details:
* A field for the parcelLab credentials
* A field for the order ID
* A field for the user’s email address or any other alternative field you prefer to identify orders by
The credentials and alternative fields are mandatory to retrieve data in the parcelLab app directly. The order ID field is not mandatory, but it is the most common way to identify an order.
{% hint style="info" %}
The app will not work without the parcelLab credentials.
The app will work if the order ID and alternative field values are missing, but the field mappings need to be defined for the app configuration.
{% endhint %}
Create a custom field for parcelLab credentials
To create a field for your parcelLab credentials within the Salesforce object:
1. View a record detail page for the object you would like to add the lightning component to.
2. Click on the **Setup** icon on the top right of the record detail page.
The Setup Menu will display.
3. Click **Edit Object**.\
The Object Manager opens in a new browser tab.
4. In the Object Manager, click **Fields & Relationships**, then click **New**.\
The New Custom Field page will display.
5. Select **Formula** as the Data Type.
6. Click **Next**.
7. In the **Field Label** field, enter a label for the formula (for example: parcelLabNamedCredential).\
The field name populates based on field label.
8. Select **Text** as the Formula Return Type.
9. Click **Next**.
10. Insert the formula to define the parcelLab named credential to be returned. This formula should be the name of the named credential that was previously defined, wrapped in quotation marks.\
**Example formula:** `“Company_UK”`
11. Click **Next**.
12. Review that the field will be added to the correct page layout.
13. Click **Save**.\
The field for your parcelLab credentials is saved.
#### Required User Permissions
{% hint style="success" %}
Users who need to use the parcelLab app in Salesforce (for example: your customer service agents) must have field-level access to all three fields in the object. Object-level access is not sufficient for accessing and using the parcelLab app.
It is recommended to also assign the permission set included in the app (that is: ParcelLab\_User) to all users who need to use the parcelLab app in Salesforce.
{% endhint %}
{% endstep %}
{% step %}
### Adding the parcelLab App to a Page Layout
To add the parcelLab App to a page layout:
1. View a record detail page for the object you would like to add the lightning component to.
2. Click on the **Setup** icon on the top right of the record detail page to open the page layout editor.
The Setup Menu will display.
3. Click **Edit Page**.
The page layout editor opens with a list of components displayed on the left-hand side of the page.
4. In the components list, enter “parcelLab” into the search field or scroll through the components list until you see the parcelLab component under **Custom - Managed**.
5. Drag the component to where you want to place it on the page.
When the component is added to the page, the component configuration will display on the right-hand side of the page layout editor.
{% hint style="info" %}
Initially the component will return an invalid warning.
{% endhint %}
6. Configure the component by setting the following fields:
* For **Named Credentials field name**, enter the API field name of the field used to identify your parcelLab API credentials.
* For **Order field name**, enter the API field name of the field that contains the order ID used in parcelLab.
* For **Alternative search field name**, enter the API field name of the field you are using in your pages to capture the user’s email address, or any other order attribute by which you can identify an order. \
This must be an attribute that is associated with the order ID in the parcelLab system within a limited set of fields. For more information please refer to the section on [using the search function](https://docs.parcellab.com/docs/platform/app-store/parcellab-customer-service-integration-for-sfsc/..#using-the-search-function).
{% hint style="info" %}
These fields must be part of the object’s details for the app to work. For more information, refer to the section on [configuring the necessary fields for displaying order data in the parcelLab app](#configuring-the-necessary-fields-for-displaying-order-data-in-the-parcellab-app).
{% endhint %}
7. Click **Save**. \
The component is added to the page layout.
When the app has been successfully added to the page layout, the component will automatically load the order information when a record detail page is viewed.
If you are unable to locate the order ID field, or experience issues when configuring the lightning component, please contact your parcelLab representative.
{% endstep %}
{% step %}
### Additional Configurations
{% hint style="info" %}
If you have multiple parcelLab accounts for different countries and/or brands, please follow these configuration instructions.
{% endhint %}
1. Set all different accounts as separate Named Credentials.\
The correct parcelLab account credentials are retrieved using a formula you need to define.
2. Create a formula by navigating to **Setup** > **Object Manager** > **Order** (or any other object you want to place the app) > **Fields & Relationships**.
3. Click **New** to create a new custom field.
4. Select **Formula** as the Data Type.
5. Click **Next**.
6. In the **Field Label** field, enter a label for the formula.
7. Select **Text** as the Formula Return Type.
8. Click **Next**.
9. Insert the formula to define the parcelLab account name to be returned.
**Example formula:** `CASE(Country__c,"DE", "parcellab DE", "AT", "parcellab AT", "No parcellab Account")`
In this example formula, all German orders (where the value of the field Country is DE) use the parcelLab DE account (set as the label within the credentials) and all Austrian orders use the parcelLab AT account.
10. Click **Save**.
Your formula is saved.
11. In the second column of **Fields & Relationships**, find the formula’s **Field Name** and copy it.
12. In the page layout editor, open the page that contains the parcelLab component.
13. Click on the parcelLab component.
The component configuration opens on the right-hand side of the page.
14. Under **Named Credentials field name**, enter the formula’s field name.
{% hint style="info" %}
The formula field must be present in the object's details for this configuration to work.
{% endhint %}
15. Click **Save**.\
The app is configured for multiple parcelLab accounts.
{% endstep %}
{% endstepper %}
