Skip to main content

Collaborator Portal

The Collaborator Portal combines the back-end functionality of Salesforce with a user-friendly AWS front-end experience. This combination provides a streamlined user interface that enables authors to easily collaborate on documentation, including reviewing and completing assigned document-related tasks.

CollabPortalRebrandV121.png

Set up and update the Collaborator Portal

The Collaborator Portal is available in the mvn-publications-planning-identity package and requires that a Salesforce Digital Experience (formerly called Communities) is enabled for your organization.

Note

On your behalf, Komodo Health's delivery team will set up and update the Collaborator Portal for your Salesforce environment as appropriate. You do not need to complete the following steps.

To set up a new instance of the Collaborator Portal:

  1. Install the mvn-publications-planning-identity package.

  2. Enable the Salesforce Digital Experience. For more information, reference Salesforce's documentation on how to Enable the Experience Cloud Site in Your Org.

  3. (Optional) Configure a custom domain. For more information, reference Salesforce's documentation on how to Configure a Custom Domain for Your Experience Cloud Site.

  4. Provide the Komodo Publications Planning product team with the Collaborator Portal URL. This will enable the product team to generate a portal identity provider to be used in step 5b and a branch domain URL for a new Origin URL Pattern to be used in step 7.

    1. To find the Collaborator Portal URL:

      1. In Setup, search for and select All Sites.

      2. In the Collaborator Portal row, find the link under the URL column. This is the URL to provide to the Komodo Publications Planning product team.

    2. The Komodo Publications Planning product team will complete several setup steps on their end and provide both the portal identity provider and the branch domain URL in return.

  5. Enable Office 365™ in the Collaborator Portal. To do so, you must create a new custom attribute on the Office 365 Connected App and then add a Portal Identity Provider to the Default Office 365 Setting metadata record.

    1. To create a new custom attribute on the Office 365 Connected App:

      1. From Setup, navigate to Manage Connected Apps.

      2. Click the existing MCM Office 365 app if you're in a production environment and MCM Office 365 (Test) app if you're in a test environment.

      3. Scroll down to the Custom Attributes section, and click New.

      4. In the Attribute key field, enter mvn__CA_O365_ExperienceSite.

      5. In the Attribute value field, enter the following code and substitute <communityUrl> with the Collaborator Portal URL for your instance.

        If(ISPICKVAL($User.UserType,"PowerCustomerSuccess"),"<communityUrl>","")

      6. Click Save.

    2. To add the Portal Identity Provider to the Default Office 365 Setting metadata record:

      1. From Setup, navigate to the Office 365 Setting (mvn__CA_Office_365_Setting__mdt) custom metadata type.

      2. Click the Default metadata record.

      3. In the Portal Identity Provider field, enter the provider name that the Komodo Publications Planning product team provided in step 4b.

        Note

        If the Portal Identity Provider field is not readily available in the Office 365 Setting layout, edit the layout and add the field.

        KPP_EditO365SettingLayout.png

      4. Click Save.

  6. Enable Cross-Origin Resource Sharing (CORS). For more information, reference Salesforce's documentation on how to Enable CORS for OAuth Endpoints.

  7. Add the branch domain URL that the Komodo Publications Planning product team provided in step 4b as a new Origin URL Pattern to the CORS. This will allow the AWS instance to communicate with Salesforce. For more information, reference Salesforce's documentation on how to Configure Salesforce CORS Allowlist.

  8. Add the Collaborator Portal landing page URL to the default Collaborator Portal (mvn__PP_Collaborator_Portal__mdt) metadata record. This will ensure that users in the Collaborator Portal are directed to the corresponding Salesforce environment.

    • To configure the default Collaborator Portal metadata record:

      1. In Setup, navigate to the Collaborator Portal (mvn__PP_Collaborator_Portal__mdt) custom metadata type.

      2. Click Manage CollaboratorPortals.

      3. Edit the Default (PP_Default) metadata record.

      4. Set the Portal Landing URL field to equal the Collaborator Portal landing page URL, or the URL of the AWS instance.

      5. (Optional) Set the Static Resource Name field. For more information, reference the Static resources section below.

      6. Click Save.

The setup of a new instance of the Collaborator Portal is now complete. To update an existing instance of the Collaborator Portal, upgrade the mvn-publications-planning-identity package.

Static resources

A static resource is a file, such as an image, logo, or other file type, that can be changed as needed. Organizations can use static resources to configure their Collaborator Portal instance with help text, links, and logos. For example, you can include a line of text that appears on the bottom of the login page that will direct users to a custom link if they need help. For more information, visit Salesforce's documentation on Static Resources.

To create a new Static Resource:

  1. In Setup, search for Static Resources in the Quick Find search box.

  2. On the Static Resources page, click New.

  3. Enter details according to the table below:

    Table 82. Static Resource Fields

    Field

    Description

    Requirements

    Name

    Enter the name for the resource. This name will be used to identify the resource in Visualforce markup.

    Note

    If a Static Resource is referenced in a Visualforce markup, and the name is changed later, the Visualforce markup will update automatically to reflect that change.

    Required field.

    Names must:

    • Contain alphanumeric characters

    • Contain underscores (if used)

    • Be unique to your organization

    • Begin with a letter

    • Not include any spaces

    • Not end with an underscore

    • Not contain two consecutive underscores

    Description

    A description of the resource.

    Optional

    File

    The file containing the resource. A single Static Resource cannot exceed 5 MB in size. An organization's total static resources cannot exceed 250 MB in size.

    Required

    Cache Control

    Select Private or Public.

    Public: Can be shared with other users in your organization.

    Private: Stored in the Salesforce server cache only for the current user's session



  4. Click Save.

PubsIdentity Static Resource

By default, the Collaborator Portal (mvn__PP_Collaborator_Portal__mdt) custom metadata type uses the PubsIdentity (PP_Pubs_Identity_Resource__c) static resource. The html content for the Login page can be updated in the file attached to the static resource by using the following file path and editing the files:

  • html/en-US/login/htmlTop.html

  • html/en-US/login/htmlBottom.html

Note

If a static resource does not exist or the expected html is missing, a comment will appear in the html file directing you to the location of the static resource/html.

Production domains

A production domain must be created in order to host the Collaborator Portal community.

Collaborator Portal documents

To ensure a streamlined experience, only certain document types appear in the Collaborator Portal. Whether or not they appear in a user's portal instance relies on the user's assigned role and permissions. Additionally, configurations must be made to custom metadata types in your Salesforce instance that will drive how users interact with documents. As part of that process, you need to determine what types of documents will be supported, using the definitions below.

Publication documents

A publication document is any document type or subtype that has a related Document Collaborator. The Document Collaborator table must be on the high-level Publication Document layouts such as a manuscript or abstract. These types of documents appear in the Collaborator Portal under Active publications. You can configure the types of document statuses that should be considered "active" publication documents using the Pubs Global Setting (mvn__PP_Global_Setting_mdt) custom metadata type as well as whether checked out Office 365TM publication documents can be downloaded via the Collaborator Portal (mvn__PP_Collaborator_Portal__mdt) custom metadata type. Reference the Configuring the active publication criteria and Configuring the download capability of checked out Office 365TM documents sections below for more information.

Package files

Package files are a set of one or more files that relate to a single document version. For every publication document that appears in the Collaborator Portal, all of its package files will also appear in the Collaborator Portal as long as the PP_Pubs_API_Version_2 Pubs API Version (mvn__PP_Pubs_API_Version__mdt) metadata record is active. Reference the Package files page for more information.

Supporting documents

The types of documents that are considered supporting documents are determined by each client and are configured in the Supporting Document Type (mvn__PP_Support_Document_Type__mdt) custom metadata type. This allows you more flexibility and control over what you want to share with authors. Reference the Configuring the Supporting Document Type metadata type section below for more information.

Configuring the active publication criteria

Active publications will appear on the author's Collaborator Portal instance. You can define what is considered to be an "active" publication using the Pubs Global Setting (mvn__PP_Global_Setting__mdt) custom metadata type.

To configure:

  1. In Setup, navigate to the Pubs Global Setting custom metadata type.

  2. Click Manage Pubs Global Settings.

  3. Click Default.

  4. Click Edit.

  5. Adjust the criteria under the Active Publication Criteria section.

  6. Click Save.

Pubs Global Setting CMT Active Publication Criteria section

Configuring the download capability of checked out Office 365TM documents

Out of the box, publication documents that are checked out to Office 365TM cannot be downloaded in the Collaborator Portal. However, you can configure this setting via the Enable Checked Out Document Download (mvn__PP_Enable_Checked_Out_Document_Download__c) field on the Collaborator Portal (mvn__PP_Collaborator_Portal__mdt) custom metadata type to allow external document collaborators to review and edit documents offline and complete their assigned tasks while internal users review and edit documents in Office 365TM.

To enable documents that are checked out in Office 365TM to be downloaded in the Collaborator Portal:

  1. In Setup, navigate to the Collaborator Portal (mvn__PP_Collaborator_Portal__mdt) custom metadata type.

  2. Click Manage Collaborator Portals.

  3. Click and edit the Default (PP_Default) metadata record.

  4. Check the Enable Checked Out Document Download (mvn__PP_Enable_Checked_Out_Document_Download__c) checkbox.

  5. Click Save.

A download icon will appear on the publication document page in the Collaborator Portal, even if the document is checked out to Office 365TM in the Salesforce instance. When an external collaborator clicks the download icon, the file that is downloaded will be the original document version and will not contain any changes that may have been made in Office 365TM.

KPP_DownloadO365Document.png

Configuring the Supporting Document Type metadata type

You can configure which types of documents should be considered Supporting Document Types by adding new types to the Supporting Document Type (PP_Supporting_Document_Type__mdt) metadata object.

To configure:

  1. From Setup, navigate to the Supporting Document Type (PP_Supporting_Document_Type__mdt) metadata type.

  2. Click Manage Supporting Document Types.

  3. To edit an existing type, click the Edit link under the Action column. To add a new type, click New.

  4. Ensure all fields are completed, shown in the table below.

Field label

Description

Label

Label for the document type.

Supporting Document Type Name

Name for the supporting document type. This field automatically populates after you enter a value in the Label field and either press the Tab key or click outside of the field.

Role

Select a role from the options below. Users assigned with this role will be able to see this document type.

  • Approver

  • Owner

  • Reviewer

  • Viewer

  • Publication Specialist

  • Author

  • Statistician

Document Type

Select a document type from the following options:

  • Supporting Document

  • Summary Data

  • Other

Note

The Document Type you choose should be appropriate for the role you selected. For example, certain roles would not need to see "Other".

Collaborator Portal users

Collaborator Portal users are designated using the following taxonomies:

Table 83. Collaborator Portal user record types

Record Type

Definition

Contact

The Contact record contains initial metadata about the portal user. This information allows you to create authors, relate authors to documents, and perform background checks prior to provisioning portal user access.

The following are the minimum required fields:

  • Type of Contact

  • Account Name

  • First Name

  • Last Name

  • Email

Document Collaborator

A Contact can be related to a document via a Document Collaborator record. This relationship determines which document(s) the portal user has access to. The Role determines which permissions the author will have on the Document when a user is provisioned.

Required fields include:

  • Document

  • Contact

  • Role

  • Status

User Request

A User Request record is created when a user is provisioned from a Document Collaborator. A scheduled job processes "Pending" user request records and creates a user for each author. This triggers an automatic email that is sent to the user with a link to set their Portal password.

The scheduled job will also activate all related Document Collaborator records, thereby providing authors with access to the publication document based on the specific role on their corresponding Document Collaborator record.

User

A Document Collaborator record that has completed the provisioning process and is now a User record. Every document collaborator must have a User record to log into the Collaborator Portal.

Required fields include:

  • First Name (pre-populated from the contact)

  • Last Name (pre-populated from the contact)

  • Email Encoding

  • Language

  • Time Zone

  • Locale

Optional fields include:

  • Gender

  • ORCID ID

  • Pronoun

Note

Every document collaborator only needs to be provisioned once. Once a user is provisioned for a related contact, the document collaborator can be added to any other publication document.



Creating a new Document Collaborator user requires the completion of three primary steps:

  1. Create the contact.

  2. Create the Document Collaborator by relating the Contact to a document (as a Document Collaborator).

  3. Provision the user (which creates the User Request record).

The batch process then runs and creates a user from the User Request record, automatically activating the Document Collaborator.

Note

If the Contact already has a related User, disregard Step 3. The Document Collaborator record can be activated manually by the user.

Once provisioned, the user will gain access to the documents to which they are added as a collaborator. Visit Users for more information on creating users and adding permissions.

Provisioning a portal user

To provision a user:

  1. From the Document Record Page, click the Collaborators tab.

  2. Click the dropdown caret next to the contact/collaborator you want to provision.

  3. Select Provision User.

  4. On the Provision User modal, ensure all details are correct.

  5. Click Provision User.

After the user provisioning batch process is run, the document collaborator will be activated with a user record. They will receive an email to instruct them on how to setup their Collaborator Portal account. They can then be added as an active collaborator to any future documents.

Note

Salesforce automatically generates their username. The Collaborator Portal User only needs their email to login and reset their password.

Warning

If enhanced domains are enabled in your Salesforce environment and an external collaborator runs into an error when logging into the Collaborator Portal:

  1. In Setup, search for and select Network Access.

  2. Create the following Trusted IP Range records:

    Start IP Address

    End IP Address

    0.0.0.0

    1.255.255.255

    2.0.0.0

    3.255.255.255

  3. In Setup, search for and select Profiles.

  4. Click the external collaborator who is unable to log into the Collaborator Portal.

  5. Create the following Login IP Range record:

    IP Start Address

    IP End Address

    0.0.0.0

    255.255.255.255

The external collaborator will no longer run into an error when logging into the Collaborator Portal.

Just-in-time provisioning

The configuration of both Supporting Document Types and Roles also streamlines the Salesforce provisioning backend process. Users that are assigned to a publication document can also view certain supporting document types when they are related to (attached to) the main publication document.

This process is called "just-in-time provisioning." When a supporting document type is related to (attached) to a publication document, any users associated with the main publication document will be able to see and download that supporting document in the Collaborator Portal. After that user clicks Download in the Collaborator Portal, Salesforce processes the request as a "just-in-time provisioning" task. The user then appears in the Salesforce instance under the Document Roles section on the Collaborator tab.

Document role section on document record page

Permissions

User access to the Collaborator Portal is governed by the PP_Publication_Collaborator_Externals permission set group and PP_Content_Author_External permission set.

Permission sets

Permission sets bundle permissions and extend users' access to tools and functions. For a user to gain access to the Collaborator Portal to view documents and complete tasks, they must have the permission set shown below assigned to them. User notifications are also dependent upon their assigned permissions, as this set contains a custom permission for external notifications.

Table 84. Publication Collaborator External Permission Set Group

Permission set

Description

PP_Content_Author_External

Users with this permission set are considered external publication authors with access to all corresponding publication document objects. This permission set should be used in conjunction with CM_ContentAuthor.

The custom permission associated with this permission set determines which link (either an internal Salesforce link or external AWS link) the user will receive in their Collaborator Portal email notifications.

PP_ContentAuthor_External

Users with this permission set will be external authors with access to content management objects and fields. This is a clone of the CM_ContentAuthor permission set, with minor modifications to account for Customer Community user licenses.

PP_App_Permissions_External

Users with this permission set will be external authors, provisioned with access to Komodo Publications Planning application settings, custom metadata, Apex classes, etc.

CA_Office_365_Author

Users with this permission set can author Office 365™ content.



Schedulable jobs

Information about schedulable jobs can be found in Schedulable Jobs.

Flows

The Task: Make Tasks Visible for Community Users flow determines the visibility of tasks.

The logic can be changed as needed, using the following process:

  1. In Setup, search Flows in the Quick Find search box.

  2. Click Task: Make Tasks Visible for Community Users. The Flow Builder interface appears.

  3. Make edits as desired to the flow logic.

Warning

If the Task field Public (IsVisibleInSelfService) is not set to true, portal users will not see other users' review/approval tasks.

Office 365™ override labels

Customers utilizing the Office 365™ integration can configure the names and actions of the links that appear in a document's file path. For example, customers can configure their Office 365™ integration settings such that portal users (i.e., external users) will see a specific label name that when clicked, will redirect them back to the portal when working with a document in Office 365™. An example of a file path and its associated settings is shown below.

Collaborator portal settings

Note

The Close URL does not appear in the user interface but should contain the URL you want to direct users to when the document is closed.

Note

If a change is made to these configuration settings while a user(s) are working in a document, the changes will not appear until after the document is checked out again.

Configuring Office 365™

To configure Office 365™ for portal use:

  1. Install the Office 365™ app and configure your environment using the information in our Office 365 documentation.

  2. From Setup, in the Quick Find box, search for and select Manage Connected Apps.

  3. Click Edit next to the Office 365™ app.

  4. Add mvn.PP_Office365ConnectedAppPlugIn to the Apex Plugin Class field under the Custom Connected App Handler section.

  5. Click Save.

  6. In the Quick Find box, search for and select Custom Metadata Types.

  7. Click the Office 365 Setting (mvn__CA_Office_365_Setting__mdt) custom metadata type.

  8. Click Manage Office 365 Settings.

  9. Click Default.

  10. Verify that the User Overrides Apex Class Name field is populated with PP_Office365CheckoutUserOverrides.

  11. Navigate to the Office 365 Override (mvn__PP_Office365_Override__mdt) custom metadata type.

  12. Add your preferred URL Labels and Names.

    Note

    Checking Use Salesforce Domain for Action URLs will make the following URLs default to the URL of your Salesforce Instance:

    • Action Return URL

    • Action URL

    • Close URL

    Values in the above fields will not break anything but will not be used in runtime.