Prepare to Deploy OmniOut Projects

Learning Objectives

After completing this unit, you’ll be able to:

• Set up project prerequisites to deploy with OmniOut.
• Prepare your Salesforce org and tools to deploy with OmniOut.
• Create a connected app to enable your external connection to interact with Salesforce.

Project Prerequisites

Robert has worked with his clients to confirm the details of each OmniOut project. He’s now on the case to prepare the deployment environments.

Before Robert can begin, for any project, he needs to ensure the following prerequisites are in place.

• The customer CMS is set up and the apps created.
• He’s running the current version of Node.js on his development platform.
• He’s obtained an npm key for each OmniOut project.
• His source-code editor is current.
• All FlexCards and OmniScripts that he wants to use are active.

Ensure the CMS and App Are Ready

Before you prepare FlexCards or OmniScripts to deploy with OmniOut, make sure the CMS is in place. As you prepare your org to deploy an app with OmniOut, knowing in advance which CMS to connect to helps you take all the necessary steps. In addition, it’s best if the app is built and ready for OmniOut deployment. Robert's lucky because all his projects have a CMS and app ready to go. 

Check Node.js Is Installed and npm Keys Available

If you don’t already have LTS Node.js, you need to download and install it. In addition, you must contact your Salesforce customer service rep to get your company’s npm key. The npm key allows your app to access the base components in the OmniStudio npm repository. 

Robert confirms that he has the current version of Node.js installed. As he’s working on four simultaneous projects, with four different clients, he obtains four different npm keys.

Ensure Your Source-Code Editor Is Current

To deploy FlexCards and OmniScripts in an OmniOut app, you need a source-code editor. If you don’t have one already, consider using Visual Studio Code, which is free and available for Windows, macOS, and Linux. Check the documentation and videos to help you get up and running. 

Robert has been working with Visual Studio Code for some time now, and he’s ready to roll. For each project, he can now focus on configuring the orgs. 

Prepare to Deploy with OmniOut

With all the prerequisites in place, Robert prepares to deploy with OmniOut. The good news is the steps are the same in any org, no matter which type of connection or CMS. 

Robert needs to complete the following tasks in each org.

• Download static resources.
• Install dependencies in the app.
• Add any nested LWCs to the OmniScripts.

Download Static Resources

OmniOut projects use two types of static resource:

• OmniOut: All OmniOut projects use the OmniOut static resource, which includes JS, HTML, CSS, and other files required for OmniStudio to run outside Salesforce.
• CSS: Some OmniOut projects use custom style sheets. The downloaded metadata of a FlexCard or OmniScript doesn't include any custom styling. So you need to download the CSS files and add any custom styling to your application later on.

Custom styling done with OmniScript Designer or FlexCard Designer is included in the downloaded off-platform LWC.

Download a static resource.

1. Click , and select Setup.
2. In the Quick Find box, enter static, and select Static Resources.
3. On the Static Resources page, locate and select the vlocityomnioutlwc resource.
4. Click View File to download the static resource.
5. If the project includes custom styles, return to the Static Resources page to locate and download CSS resources.
6. Decompress any downloaded files, and add the required folders to your app.
7. If using CSS, open the app’s index.html file, and add a reference to load the CSS. For example:

<link rel="stylesheet" type="text/css" href=".../styles/my-custom-styles.css">

The Bull Market Investments project uses custom style sheets, so Robert downloads both the OmniOut and CSS static resources from the Bull Market Investments org. 

He’s now ready to install any dependencies for the projects. 

Install Dependencies

The downloaded static resource excludes OmniOut dependencies, so you need to install them using a command-line tool. Robert uses his computer’s terminal application.

Install dependencies.

1. Open your terminal application.
2. In the decompressed folder, locate and open the .npmrc file, and set _auth equal to the npm repository access key: _auth=Authentication_Key.
3. In a new terminal shell, install the npm packages by running the command npm install.
4. Run the command npm run watch to run the development server.
5. Access the local development server at localhost:4002, and view the demo application.

Now that Robert has taken care of the static resources and dependencies, he turns his focus to adding nested LWCs to OmniScripts.

Add Nested Custom LWCs to OmniScripts

Any LWCs that override or map to an OmniScript automatically download with the off-platform OmniScript LWC. Nested custom LWCs referenced by a custom LWC in the OmniScript do not download automatically. A nested LWC is one that is a child of a parent LWC. Being nested also makes it a custom LWC.

Custom LWCs from a managed package, which are those developed outside of OmniStudio or Salesforce but used in OmniStudio, need to be off-platform compatible to work with OmniOut. For this to happen, ensure the component does not use @salesforce imports and referenced LWC components are in the open source list.

For the nested custom LWC to compile properly, you need to map it to a dummy element in the Element Type To LWC Component Mapping section. If it is mapped to an actual element it will not compile correctly.

Map nested custom LWCs.

1. Open the OmniScript.
2. In the OmniScript Setup panel, find the Element Type To LWC Component Mapping section.
3. In the Element Type field, enter a fictitious element type, for example, nestedElement.
4. In the Lightning Web Component field, enter the name of your nested custom LWC, for example, nestedLWC.

Create a Salesforce Connected App

The last step Robert needs to take before downloading the FlexCards and OmniScripts is to build a Salesforce-connected app for each org. A connected app enables the external connection to interact with Salesforce by giving OmniOut an access token that enables proxies and login authentication to work. 

Robert creates a connected app in each org and then makes sure it’s ready to support OmniOut in three phases.

• He creates the app in Salesforce.
• He generates an access token from the app.
• He links credentials using a source-code editor.

Create the App in Salesforce

Robert creates the connected apps in each org.

1. Click , and select Setup.
2. In the Quick Find box, enter app, and select App Manager.
3. Click New Connected App.
4. In the Connected App Name field, enter a name for the connected app, for example, OmniOutConnectionApp. The API Name automatically populates after you click in the next open field.
5. Enter a contact email for the app.
6. Select Enable OAuth Settings.
7. Enter a callback URL. This is the URL for the OmniOut app's public site, so it varies from project to project.
8. Move the Fullaccess (full) and Access and manage your data (api) from AvailableOAuth Scopes to Selected OAuth Scopes as needed.
9. Click Save to create your Connected App.
10. If prompted, click Continue.

Generate an Access Token

Once the Salesforce connected app is created, Robert needs to confirm settings and generate an access token.

1. From the connected app detail page, click Manage.
2. Click Edit Policies.
3. In the Permitted Users field, confirm All users may self-authorize displays. If you change this setting, click Save.
4. From the Sidebar, click App Manager.
5. On the right side of the row, click the dropdown menu and select View.
   
6. From the connected app detail page, copy the Consumer Key and Consumer Secret, and save them to use in the final steps and later during deployment.
7. From the Initial Access Token for Dynamic Client Registration section, click Generate next to Initial Access Token.
8. When the screen refreshes, click Reveal next to the Initial Access Token Value. Save this value to use when running the project in development mode.

The final steps are to link a Salesforce username and password and the Consumer Key and Consumer Secret to the app that uses OmniOut. 

Link Credentials

Robert uses his source-code editor to link credentials.

1. In the source-code editor, enter the following command without running it: curl -d "username=USERNAME" -d "password=PASSWORD" -d "client_id=CLIENTID" -d "client_secret=CLIENTSECRET" -v -d "grant_type=password".
2. Replace USERNAME with a Salesforce username.
3. Replace PASSWORD with a Salesforce password.
4. Replace CLIENTID with the Consumer Key you saved earlier.
5. Replace CLIENTSECRET with the Consumer Secret you saved earlier.
6. Optionally, add the URL for the Salesforce environment to the end of the command. By default, the URL is configured for a Sandbox org.
7. Run the command.
8. Copy the Access Token and Instance URL, and save them to use later in development mode.

Robert has ensured each org is prepared and that all FlexCards and OmniScripts are activated. He’s ready to take the next steps to create the OmniOut project. You can see how he does this in the next unit.

Resources

• Node.js: Download Node.js LTS
• Visual Studio Code: Download Visual Studio Code
• Salesforce Help: Connected Apps