Integrating and Extending Oracle Content and Experience...REST API for Sites Management 4-41 REST...

Oracle® CloudIntegrating and Extending Oracle Content andExperience

F24100-08April 2020

Oracle Cloud Integrating and Extending Oracle Content and Experience,

F24100-08

Copyright © 2017, 2020, Oracle and/or its affiliates.

Primary Author: Bonnie Vaughan

Contributors: Kannan Appachi, Sarah Bernau, Robert Briggs, David Jones, Bob Lies, Keith MacDonald, MarkPaterson, Angelo Santagata, Ankur Saxena, Keith Sholes, Ron van de Crommert, Archana Vishnu

This software and related documentation are provided under a license agreement containing restrictions onuse and disclosure and are protected by intellectual property laws. Except as expressly permitted in yourlicense agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify,license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means.Reverse engineering, disassembly, or decompilation of this software, unless required by law forinteroperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. Ifyou find any errors, please report them to us in writing.

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it onbehalf of the U.S. Government, then the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs (including any operating system, integrated software,any programs embedded, installed or activated on delivered hardware, and modifications of such programs)and Oracle computer documentation or other Oracle data delivered to or accessed by U.S. Government endusers are "commercial computer software" or “commercial computer software documentation” pursuant to theapplicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use,reproduction, duplication, release, display, disclosure, modification, preparation of derivative works, and/oradaptation of i) Oracle programs (including any operating system, integrated software, any programsembedded, installed or activated on delivered hardware, and modifications of such programs), ii) Oraclecomputer documentation and/or iii) other Oracle data, is subject to the rights and limitations specified in thelicense contained in the applicable contract. The terms governing the U.S. Government’s use of Oracle cloudservices are defined by the applicable contract for such services. No other rights are granted to the U.S.Government.

This software or hardware is developed for general use in a variety of information management applications.It is not developed or intended for use in any inherently dangerous applications, including applications thatmay create a risk of personal injury. If you use this software or hardware in dangerous applications, then youshall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure itssafe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of thissoftware or hardware in dangerous applications.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks oftheir respective owners.

Intel and Intel Inside are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks areused under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Epyc,and the AMD logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registeredtrademark of The Open Group.

This software or hardware and documentation may provide access to or information about content, products,and services from third parties. Oracle Corporation and its affiliates are not responsible for and expresslydisclaim all warranties of any kind with respect to third-party content, products, and services unless otherwiseset forth in an applicable agreement between you and Oracle. Oracle Corporation and its affiliates will not beresponsible for any loss, costs, or damages incurred due to your access to or use of third-party content,products, or services, except as set forth in an applicable agreement between you and Oracle.

Contents

Preface

Audience xii

Documentation Accessibility xii

Related Resources xii

Conventions xii

1 Get Started

Understand Integrations 1-1

Integration Interfaces 1-3

Enable Single Sign-On (SSO) 1-4

2 Integrate with Other Applications and Services

Integrate with Oracle WebCenter Content 2-1

Integrate with JD Edwards 2-2

Integrate with Oracle Logistics Cloud 2-3

Integrate with Eloqua 2-4

Choose an Asset Repository and Create a Publishing Channel 2-4

Provide Oracle Content and Experience Information for the Eloqua Integration 2-5

Enable Oracle Content and Experience Embedded Content 2-6

Use an Asset in an Eloqua Landing Page 2-6

Integrate with Responsys 2-8

Choose an Asset Repository and Create Two Publishing Channels 2-8

Enable the Integration 2-9

Create and Publish Assets in Oracle Content and Experience 2-9

View Images in Responsys Message Preview 2-11

Integrate with Oracle Business Intelligence Publisher 2-13

Integrate with Oracle Process Cloud Service 2-14

Configure Oracle Integration Settings in Oracle Content and Experience 2-16

Process Cloud Service Integration with Documents 2-17

Process Cloud Service Integration with Sites 2-18

Pass a CSS Style Sheet to Process Cloud Service 2-19

iii

Start the Default Version of a PCS Process 2-19

Integrate with Oracle Developer Cloud Service 2-19

Integrate with Oracle Visual Builder 2-20

Embed a VBCS Visual App in an Oracle Content and Experience Page 2-21

Embed a VBCS Page in a Site Page 2-26

Build an Oracle Content and Experience VBCS Public Form Component 2-30

Build an Oracle Content and Experience VBCS Secure Form Component 2-38

Build an Oracle Content and Experience VBCS Public Gated Form Component 2-47

Build an Oracle Content and Experience VBCS Data Report Component 2-57

Build an Oracle Content and Experience VBCS Multipage Form As a Web AppComponent 2-61

Provide a VBCS Endpoint As a URL for Select Menus 2-68

Integrate with Intelligent Advisor 2-70

Integrate with Oracle Cobrowse Cloud Service 2-71

3 Use Apps and Services in Oracle Content and Experience

Understand Cross-Origin Resource Sharing (CORS) 3-1

Understand the Application Integration Framework (AIF) 3-2

Manage Custom Applications 3-5

4 Oracle Content and Experience REST APIs

Integrate with Oracle Content and Experience Using OAuth 4-3

Access Using 2-Legged OAuth 4-3

Create an OAuth Client and Acquire a Client ID and Secret 4-4

Grant the Required Oracle Content and Experience Roles to the Client 4-4

Acquire an Access Token from Oracle Identity Cloud Service (IDCS) for theRequired Resource 4-5

Use the Access Token to Access the Oracle Content and ExperienceResource 4-5

Access Using 3-Legged OAuth Flow 4-6

Create an OAuth Client and Acquire a Client ID and Secret 4-6

Grant the Required Oracle Content and Experience Roles to the Client 4-7

Acquire an Access Token from Oracle Identity Cloud Service (IDCS) for theRequired Resource 4-8

Use the Access Token to Access the Oracle Content and ExperienceResource 4-8

Integrate Using OAuth As a Resource Owner 4-9

REST API for Activity Log 4-10

REST API for Content Delivery 4-11

REST API for Content Management 4-12

REST API for Conversations 4-13

iv

REST API Features for Conversations 4-14

API Security 4-15

API Versioning 4-15

Case Sensitivity 4-16

HTTP Methods 4-16

Optional Fields and Default Values for JSON Data Representations 4-17

Return Values 4-17

Name Patterns 4-17

URL Encoding 4-18

Pagination 4-18

Filters 4-19

Sort Order 4-19

Localization 4-19

Name Field Length Limit 4-20

HTTP Status Codes and Error Handling 4-21

Collaboration Resource 4-21

Configuration Resource for Conversations 4-22

Security Resource 4-22

Social Resource 4-22

REST API for Documents 4-22

Version History 4-23

REST API Features for Documents 4-25

REST Overview 4-25

Service Call URI and Version 4-26

Service Request 4-26

Service Response 4-27

Security 4-27

Sort Order 4-31

Pagination 4-32

Links Identification 4-32

HTTP Methods 4-33

HTTP Status Codes 4-33

Error Codes 4-34

Applinks Resource 4-34

Catalog Resource 4-37

Collections Resource 4-37

Configuration Resource for Documents 4-37

Files Resource 4-38

Folders Resource 4-38

Metadata Collection Resource 4-38

Publiclinks Resource 4-39

v

Shares Resource 4-39

Sites Resource 4-40

Templates Resource 4-40

Users Resource 4-40

REST API for Sites Management 4-41

REST API for Users and Groups 4-41

REST API for Webhooks Management 4-42

Download the Swagger File for a REST API 4-43

Upload a REST API Swagger File into Mobile Cloud Service 4-44

Search with the Querytext Parameter 4-45

Set Up Searches on Metadata Fields 4-46

Create and Use Applinks for File and Folder Access 4-47

Provide Access to Files and Folders with Public Links 4-48

5 Oracle Content and Experience SDKs

Content SDK 5-1

Mobile SDKs 5-1

6 Embed the Web User Interface in Other Applications

Embed the Web User Interface for Assets 6-1

Embed the Web User Interface for Documents 6-4

Authentication and SSO Environments 6-4

Real-Time Updates for Embedded Conversations 6-5

Embed Documents Manager on a Site -6

Security for Content in Other Domains 6-6

Embed Content in Other Domains 6-6

Browser Configuration Parameters 6-7

Embed Search Results 6-10

Embed Sites Content in Another Domain 6-11

Integrate Folder and File Selection 6-11

Configure the File Picker with the SitesSDK.filePicker Method 6-12

7 Set Proxies

Configure Proxy Service Settings 7-1

Debug Proxy Service Endpoints 7-3

vi

8 Develop Custom Actions with Application Integration Framework(AIF)

Application Integration Framework Overview 8-1

Configuration File Format 8-4

Application Properties 8-7

Action Command 8-7

Invoke Command 8-8

Presentation Command 8-9

Expressions 8-10

Variables 8-11

Localization 8-14

9 Use Content Connectors

Enable a Content Connector 9-1

Disable a Content Connector 9-2

Configure a Google Drive Content Connector 9-3

Configure a Microsoft OneDrive Content Connector 9-5

Configure a Dropbox Content Connector 9-7

Configure a YouTube Content Connector 9-9

Configure WebCenter Content and Oracle Content and Experience for the WCCConnector 9-11

Map Source Metadata to Content Types for a WCC Connector 9-11

Create and Configure a Custom Content Connector 9-12

Create Content Types for a Connector 9-13

Map Source Metadata to Fields in a Content Type 9-13

Provide Configuration Parameter Values for a Content Connector 9-14

Delete a Content Connector 9-15

10

Develop Content Connectors

Connector REST API Interface 10-1

Connector SDK 10-1

Build a New Content Connector 10-2

REST Interfaces for Configuration, Authorization, and Fetching Content 10-4

REST Interfaces for File System Browsing and Searching 10-9

Content Picker 10-11

Authorization 10-17

Content Connector Configuration and Registration 10-21

Content Connector Execution Flow 10-21

Pexels Content Connector Sample Implementation 10-22

vii

Install the Content Connector 10-22

Check Prerequisites for Installation 10-22

Build the Content Connector WAR File 10-23

Register the Content Connector 10-23

Test the Content Connector 10-25

Understand the Content Connector Source Code 10-25

Custom Picker UI 10-26

Pexels REST APIs 10-26

Change and Test the Content Connector Code 10-26

Download the CEC Content Connector Sample and SDK 10-26

11

Use Webhooks

Configure Webhooks 11-1

Receive Push Notifications from a Content Lifecycle Webhook 11-2

Receive Push Notifications from a Content Publishing Webhook 11-3

Receive Push Notifications from a Site Publishing Webhook 11-4

Use Endpoints for Push Notifications of Content Lifecycle, Content Publishing, andSite Publishing Events 11-4

12

Develop with OCE Toolkit

Set Up OCE Toolkit on Your Local Machine 12-2

Install Dependencies Through npm 12-2

Create Source in Your Local File System 12-3

Use the cec Command-Line Utility 12-4

Test with a Local Test Harness 12-52

Develop for Oracle Content and Experience with Developer Cloud Service 12-53

About Using Developer Cloud Service 12-54

Sign in to the Developer Cloud Service Console for Oracle Content andExperience 12-54

Create a Project in Developer Cloud Service 12-55

Create a Developer Cloud Service Project with an Oracle Content andExperience Template 12-55

Create a Project in Developer Cloud Service with an OCE Toolkit Downloadfrom Oracle Content and Experience 12-56

Add OCE Toolkit to the Project Code in the New Git Repository 12-58

Test Custom Components, Templates, and Content Layouts in a Local TestHarness 12-59

Merge Changes 12-59

Propagate Changes from Test to Production with OCE Toolkit 12-59

Encrypt a Password 12-66

Register a Server 12-66

viii

Create a Usage and Permission Report for a Site 12-66

Download and Upload Documents and Folders 12-67

Create a Site from a Template and Keep the Same GUIDs for Content 12-68

Import and Export Taxonomies 12-68

Develop Custom Field Editors 12-69

Transfer or Update a Site from One Server to Another 12-74

Index Site Pages with OCE Toolkit 12-74

Create the Content Type for Site Page Text 12-74

Create Page Index Content Items with OCE Toolkit 12-75

Add Content Search to a Site in Oracle Content and Experience 12-76

Add a Search Page to the Site 12-76

Add a Search Field to the Theme 12-77

Index a Multilingual Site with OCE Toolkit 12-77

Create a Simplified Component for Easy Component Development 12-80

Compile a Site to Improve Runtime Performance for Site Pages 12-80

Overview of Site Compilation 12-81

Interaction with Prerender 12-81

Controller Site Page Rendering 12-81

Compiled Site Page Rendering 12-82

Template Compilation 12-82

Setup 12-82

Compile Your Template 12-83

Site Compilation 12-89

Prerequisites for Site Compilation 12-89

Compile a Site 12-89

Custom Compilers 12-90

Constraints 12-91

Debug Custom Compilers 12-91

Page Layout Compilers 12-92

Component Compilers 12-93

SCSCompileAPI 12-94

Component Hydration 12-95

Publishing 12-98

Static Site Delivery Precedence 12-98

Caching Headers 12-99

Detail Pages 12-99

Add Content Items to a Channel 12-99

Compile a Site for Mobile Devices 12-101

Site Lifecycle and Compiled Pages 12-103

Create a New Site or Asset Translation Job in the Oracle Content and ExperienceServer 12-103

ix

Translate a Site with a Language Service Provider 12-107

Create a Translation Job with OCE Toolkit 12-108

List Translation Jobs 12-108

Create a Translation Connector 12-109

Generate a Site Map for a Multilingual Site 12-110

Submit a Translation Job to a Language Service Provider 12-111

Upload a Translation Job to the Server 12-112

13

Develop Translation Connectors for Language Service Providers

Overview of the Translation Connector Framework 13-2

Translation Connector SDK 13-2

Translation Connector REST APIs 13-3

Request a Lingotek Trial Connector for Content Translation 13-4

Enable a Lingotek LSP Translation Connector 13-6

Register Multiple Lingotek Connectors 13-7

Build a New Translation Connector 13-9

REST Interfaces for Configuration and Authorization 13-11

REST Interfaces for Creating Translation Jobs and Returning TranslatedContent 13-15

Authorization for Translation Connectors 13-16

No Auth 13-16

OAuth 13-17

Basic 13-19

Configure and Register a Translation Connector 13-20

Translation Connector Execution Flow 13-20

Sample Translation Connector Implementation 13-21

Create the Sample Translation Connector with OCE Toolkit 13-21

Register the Sample Translation Connector 13-21

Test the Sample Translation Connector 13-22

Understand the Sample Translation Connector Source Code 13-23

Translation Job Original Zip File Format 13-25

Translation Job Translated Zip File Format 13-26

14

Use Site Redirects or URL Mapping

Plan for Redirects 14-1

Add Site Redirects 14-1

Specify Redirect Rules in a JSON File 14-2

Upload a Redirect Rules File to a Site 14-5

Map a Site URL 14-5

x

15

Improve Site Performance

Leverage Caching to Improve Performance 15-1

Runtime Caching 15-2

Site Builder Caching 15-3

Above the Fold (ATF) Rendering 15-3

16

Tutorial: Develop Components with Knockout

Introduction and Prerequisites for Component Development with Knockout 16-1

Step 1: Create a Component 16-2

Step 2: Review the Structure of Your Local Component Rendering 16-4

Step 3: Review the Structure of Local Component Settings 16-7

Step 4: Display the New Property in the Component 16-11

Step 5: Register Triggers 16-12

Step 6: Raise Triggers 16-13

Step 7: Register Actions 16-16

Step 8: Execute Actions 16-17

Step 9: Create a Distinct Title for Each Instance of the Component 16-18

Step 10: Use Nested Components with In-Line Editing 16-19

Step 11: Support Different Layouts 16-21

Step 12: Define Custom Styles 16-23

Step 13: Render a Component in an Inline Frame 16-24

Step 14: Use Custom Styles When the Component Is Rendered in an Inline Frame 16-28

Step 15: Integration with the Page Undo and Redo Behavior 16-31

Step 16: Asset Management 16-32

Tutorial Review 16-37

xi

Preface

Integrating and Extending Oracle Content and Experience describes how to configureOracle Content and Experience and combine it with other services to create customintegrations and to extend the capabilities of Oracle Content and Experience.

AudienceThis publication is intended for Oracle Content and Experience administrators anddevelopers who want information about integrating Oracle Content and Experiencewith other services to provide custom applications.

Documentation AccessibilityFor information about Oracle's commitment to accessibility, visit the OracleAccessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.

Access to Oracle Support

Oracle customers that have purchased support have access to electronic supportthrough My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trsif you are hearing impaired.

Related ResourcesFor more information, see these Oracle resources:

• Getting Started with Oracle Cloud

• Administering Oracle Content and Experience

• Building Sites with Oracle Content and Experience

• Collaborating on Documents with Oracle Content and Experience

• Developing with Oracle Content and Experience As a Headless CMS

ConventionsThe following text conventions are used in this document.

Convention Meaning

boldface Boldface type indicates graphical user interface elements associatedwith an action, or terms defined in text or the glossary.

Preface

xii

http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc

http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc

http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info

http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info

http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs

Convention Meaning

italic Italic type indicates book titles, emphasis, or placeholder variables forwhich you supply particular values.

monospace Monospace type indicates commands within a paragraph, URLs, codein examples, text that appears on the screen, or text that you enter.

Preface

xiii

1Get Started

The Oracle Content and Experience integration features make it a key component in anumber of Oracle offerings and also make it easy for you to leverage the service inyour own applications.

There are different types of roles in Oracle Content and Experience. Understandinghow they work together is essential to giving users the access they need to performtheir duties and access appropriate content. See Roles.

The following topics can help you get started with Oracle Content and Experienceintegrations with other applications and services:

• Understand Integrations

• Integration Interfaces

• Enable Single Sign-On (SSO)

Understand IntegrationsOracle Content and Experience provides multiple ways to leverage its functionality,whether you want to incorporate your processes or apps into Oracle Content andExperience, or whether you want to use Oracle Content and Experience in yourenterprise application.

Oracle Content and Experience

Oracle Content and Experience provides rich content and experience managementfeatures, from folder and file viewing and sharing, to conversations, to websites thatdeliver your message and content securely.

• Integrations with JD Edwards, Oracle Business Intelligence, and other servicesshow that Oracle Content and Experience is a key component in a number ofOracle integrations described in the following text.

• An embeddable version of the web user interface and website components forinteracting with folders, files, conversations, and processes provide ready-to-useintegrations.

• Application Programming Interfaces (APIs) and the Software Development Kit(SDK) let you access Oracle Content and Experience functionality to create yourown integrations within the service or across services. See Oracle Content andExperience REST APIs and Oracle Content and Experience SDKs.

• Single sign-on (SSO) authentication provides a seamless user experience acrossservices. See Enable Single Sign-On (SSO).

What Integrations Are There?

Oracle Content and Experience is a key component in a number of Oracleintegrations. With some integrations, Oracle Content and Experience is provided “out

1-1

of the box” as part of the service. For others, you must enable or configure theintegration.

Note:

A number of the integrations described in this guide require that integratedservices be in the same identity domain. For that reason, those integrationswork only on traditional cloud accounts.

Category Integration

Middleware Oracle WebCenter Content: Uses Oracle Content and Experienceto provide a truly comprehensive hybrid enterprise contentmanagement (ECM) integration, with a unified ECM infrastructureand security from a single vendor. It combines anywhere accessfrom the cloud with content retention and archiving from on-premiseinstallations. See Integrate with Oracle WebCenter Content.

Applications JD Edwards: Integrates with Oracle Content and Experienceallowing you to attach managed documents to transactions andcollaborate through conversations.

Software as a Service(SaaS)

Oracle Logistics Cloud: Use Oracle Content and Experience tostore and manage documents. See Integrate with Oracle LogisticsCloud.

Platform as a Service(PaaS)

• Business Intelligence Publisher: Integrates with OracleContent and Experience and offers managed folders as adestination for generated reports. See Integrate with OracleBusiness Intelligence Publisher.

• Oracle Process Cloud Service: Automate business-driven,company-specific processes, such as employee on-boarding orIT service requests, and incorporate those processes intoOracle Content and Experience. See Integrate with OracleProcess Cloud Service.

• Oracle Visual Builder: Rapidly create web and mobileapplications with minimal to no coding using an open-source,standards-based integration to develop, collaborate on, anddeploy applications within Oracle Content and Experience. See Integrate with Oracle Visual Builder.

• Oracle Developer Cloud Service: Use project templates andtools to create, test, and package your own site templates,themes, and components for use in Oracle Content andExperience. See Integrate with Oracle Developer Cloud Service.

Note:

This integration is available with traditional cloudaccounts.

Third-party Applications Oracle Cloud Marketplace lists applications created by partnersusing the integration features provided with Oracle Content andExperience.

Custom Applications Use options such as REST APIs, Java services, and the ApplicationIntegration Framework (AIF), to create any number of applications.

Chapter 1Understand Integrations

1-2

Use Apps and Services in Oracle Content and Experience

If you want to expand the service to include your own apps or to communicate withother services:

• The open architecture for site components means you can register and deliverhosted apps and create your own components using your preferred platform. Fordetails about how to create your own components, see Develop Components.

• Cross-Origin Resource Sharing (CORS) allows a web page to make requests suchas XMLLHttpRequest to another domain. If you have a browser application thatintegrates with Oracle Content and Experience but is hosted in a different domain,add the browser application domain to Oracle Content and Experience’s CORSorigins list. See Understand Cross-Origin Resource Sharing (CORS).

• If you use REST services that do not support Cross-Origin Resource Sharing(CORS) or that require service account credentials, you can use the OracleContent and Experience proxy service. See Configure Proxy Service Settings.

• You can use Application Integration Framework (AIF) to create your own customapplications that define the actions that are exposed in the web interface, respondto user selections, call third-party services, and specify how the results arepresented to the user. The framework supports variables and expressions andprovides multiple language support. See Understand the Application IntegrationFramework (AIF).

• You can modify the web interface and menus to provide access to yourapplications and features. See Manage Custom Applications.

Use Oracle Content and Experience with Other Services

The Oracle Platform as a Service (PaaS) architecture means you can leverage theOracle Content and Experience functionality where you need it:

• Provide direct interaction with Oracle Content and Experience in another webapplication with the embedded version of the web user interface.

• Specify a list of domains where you allow content from Oracle Content andExperience to be displayed using either the embedded web user interface orREST calls. See Embed Content in Other Domains.

Integration InterfacesFrom the Integrations page in the Oracle Content and Experience Administrationweb user interface, you can select an application for integration, configure contentconnectors to third-party content repositories, and configure proxy service settings.

Chapter 1Integration Interfaces

1-3

You can also add custom actions created with the Application Integration Framework(AIF) to change the menu options for your users, add pop-up dialogs, and evaluatedata entered into forms.

Enable Single Sign-On (SSO)If you use Federated Single Sign-On (SSO) for your Oracle Content and Experienceenvironment, you can enable it to customize sign-in procedures. When Single Sign-On(SSO) is enabled, users can sign in to one instance using corporate securitycredentials and access another instance in the same domain without signing in again.For example, perhaps you are an administrator for your company which has twoOracle Cloud services and you must provision these services to your company’sorganization, roles, and users. Your company may also have on-premise applicationsand cloud services from other vendors. It’s important that communication betweenthese services and applications is done in a secure fashion. With SSO, users can signin to all of them using the same set of credentials that are managed by using youridentity domain system.

OAuth provides secure access to all services in Oracle Cloud. It provides an accesstoken for communication between services. The token is valid for a limited time andcontains the security credentials for a sign-in session. It identifies the user and theuser's groups.

See Role of the Identity Domain in Understanding Identity Concepts to learn abouthow the identity domain is used to manage many features of Oracle Cloud.

Overview of SSO Configuration

Oracle Cloud uses the SAML 2.0 standard to enable secure cross-domaincommunication between Oracle Cloud and other SAML-enabled sites located on-premise or in a different cloud. The administrator must configure SAML 2.0 SSObetween Oracle Cloud and the identity provider. When SSO is enabled, the identityprovider performs authentication for Oracle Cloud.

Perform the following steps to configure SSO:

Chapter 1Enable Single Sign-On (SSO)

1-4

1. Sign in to Oracle Cloud as the cloud account administrator. You can find youraccount name and login information in your welcome email.

2. In the Infrastructure Console, click on the top left to open the navigation menu,click Identity, then click Federation. You might need to use the scroll bar on theleft to scroll down to see the menu option.

3. On the Federation page, click the link to the Oracle Identity Cloud ServiceConsole. This opens the IDCS Console in a new window.

4. In the IDCS Console, add a SAML application, and configure SSO details. See Add a SAML Application in Administering Oracle Identity Cloud Service.

Chapter 1Enable Single Sign-On (SSO)

1-5

https://cloud.oracle.com

2Integrate with Other Applications andServices

You can integrate Oracle Content and Experience with many other applications andservices.

• Integrate with Oracle WebCenter Content

• Integrate with JD Edwards

• Integrate with Oracle Logistics Cloud

• Integrate with Eloqua

• Integrate with Responsys

• Integrate with Oracle Business Intelligence Publisher

• Integrate with Oracle Process Cloud Service

• Integrate with Oracle Developer Cloud Service

• Integrate with Oracle Visual Builder

• Integrate with Intelligent Advisor

• Integrate with Oracle Cobrowse Cloud Service

Integrate with Oracle WebCenter ContentIntegration Oracle Content and Experience with Oracle WebCenter Content makes iteasy to manage content in either environment and to share content between the two.

Need to collaborate with team members in the cloud? Users can collaborate on cloudcontent whether they are in the cloud, on their phone, or on-premise. This makes itpossible for enterprises with investment in on-premise applications to leverage theirinvestment while taking advantage of the rapidly expanding set of cloud offerings.Users can manage cloud content and move content between the cloud and on-premise installations. See Work with Oracle Documents Cloud Service in OracleFusion Middleware Using Oracle WebCenter Content, 12c (12.2.1.2.0)

2-1

When Oracle Content and Experience is enabled with Oracle WebCenter Content, youhave a truly comprehensive hybrid enterprise content management (ECM) integration,with a unified ECM infrastructure and security from a single vendor. It combinesanywhere access from the cloud with content retention and archiving from on-premiseinstallations.

Setting up the integration in Oracle WebCenter Content is as easy as 1–2–3:

• Enable the component

• Configure the server connection

• Configure the host name verifier

See Configure Document Cloud Service Integration Settings in Oracle FusionMiddleware Administering Oracle WebCenter Content, 12c (12.2.1.2.0)

Integrate with JD EdwardsJD Edwards EnterpriseOne integrates with Oracle Content and Experience, letting youattach managed documents to transactions and collaborate through conversations.

With content stored in Oracle Content and Experience, you can:

• Access documents using web, desktop devices, and mobile devices

• View, search, and manage documents directly in the web interface

• Collaborate through conversations, and conversations about specific transactionsor documents

• Review document usage data

When you enable the integration, you can use the following from within JD EdwardsEnterpriseOne:

• User Conversations: Start or participate in social conversations about a topic ofinterest within EnterpriseOne using the Conversation icon in the menu bar.

Chapter 2Integrate with JD Edwards

2-2

• Contextual Conversations: Start or participate in conversations about specificbusiness records within EnterpriseOne. Create conversations within the context ofa transaction using the Conversation icon in the header bar of the AttachmentManager.

• Contextual Documents: Add documents to the cloud and organize documentswhile still keeping them in the context of your business record by using theDocument icon in the header bar of the Attachment Manager.

Integrate with Oracle Logistics CloudYou can use Oracle Content and Experience to store and manage documents fromwithin Oracle Logistics Cloud.

You simply configure the integration with URL, user name, and password to connect tothe Oracle Content and Experience server. After authentication credentials areverified, you can upload, edit, and delete documents directly from Oracle LogisticsCloud. See Content Management System Integration Guide.

Chapter 2Integrate with Oracle Logistics Cloud

2-3

https://docs.oracle.com/cloud/latest/otmcs_gs/OTMCI/OTMCI.pdf

Integrate with EloquaIntegration with Eloqua lets you insert published assets from an Oracle Content andExperience asset repository into Eloqua responsive emails, forms, and landing pages.Using Oracle Content and Experience as a single source for all images saves reworkbecause you can find your images easily.

Eloqua users can leverage the extensive asset repository capabilities in OracleContent and Experience to store content for use in Eloqua marketing assets. Whenyou design emails, forms, or landing pages, this integration gives you the option toinsert published image assets from Oracle Content and Experience into your Eloquaassets.

This is an overview of the Eloqua integration with Oracle Content and Experience:

• Choose an Asset Repository and Create a Publishing Channel

• Provide Oracle Content and Experience Information for the Eloqua Integration

• Enable Oracle Content and Experience Embedded Content

• Use an Asset in an Eloqua Landing Page

For more detailed information, see the Oracle Eloqua Help Center.

Choose an Asset Repository and Create a Publishing ChannelFor integration with Eloqua, you need to choose an asset repository and create apublishing channel in Oracle Content and Experience. Then Eloqua can provideaccess to assets in the repository.

After you choose an asset repository Oracle Content and Experience, create andshare a publishing channel. Oracle suggests creating a channel that is specifically forEloqua. See Create and Share Publishing Channels.

Chapter 2Integrate with Eloqua

2-4

https://docs.oracle.com/cloud/latest/marketingcs_gs/OMCAA/Help/Integrations/ContentExperience/ContentExperienceIntegration.htm

The assets published to the Eloqua channel will be displayed in a tab on the EloquaImage Chooser page, where you can choose an Oracle Content and Experienceasset.

To refresh an image in all channels, email campaigns, and landing pages in which theimage is used, you can change and republish the image in Oracle Content andExperience.

If the image you want to use is not available in the Eloqua Image Chooser, you can goto Oracle Content and Experience and upload or publish the image.

Provide Oracle Content and Experience Information for the EloquaIntegration

To enable Oracle Content and Experience integration with Eloqua, submit a servicerequest to My Oracle Support (MOS).

Include the following details for your Oracle Content and Experience instance:

1. Domain nameFor example, if you sign in to Oracle Content and Experience at the URLhttps://eloquaoce.oraclecloud.com/documents/assets, the domainname is eloquaoce.oraclecloud.com.

2. Repository IDTo retrieve your repository ID:

a. In Oracle Content and Experience, navigate to Administration > Assets.

b. Select the repository you want to use for storing your Eloqua images.

c. The repository ID is appended to the URL. For example, if the full URL ishttps://eloquaoce.oraclecloud.com/documents/repository/ABC6F858251160CC3000A497C0C07C96651BA6F0BE73, the repository IDis ABC6F858251160CC3000A497C0C07C96651BA6F0BE73.

3. Channel ID and channel tokenTo retrieve your channel ID and channel token:

a. In Oracle Content and Experience, navigate to Administration > Assets.

b. From the Repositories drop-down menu, choose Publishing Channels.


2-5

c. Select the publishing channel you intend to use for Eloqua images.

d. The channel ID and channel Token are listed under API Information.

e. Ensure that Access is set to Public.

Enable Oracle Content and Experience Embedded ContentIn Oracle Content and Experience administration security settings, enable embeddedcontent and add the Eloqua URL.

Then you can embed the Oracle Content and Experience web UI in Eloqua. See Embed Content in Other Domains.

Use an Asset in an Eloqua Landing PageAfter the Oracle Content and Experience Cloud integration with Eloqua is enabled, youcan choose a digital asset from Oracle Content and experience to use it in Eloquaresponsive landing page.

1. On the Oracle Eloqua home page, choose Landing Pages from a drop-downmenu on the right.

2. On the Landing Pages page, click Create a Landing Page.Eloqua displays the Template Chooser for a landing pages.


2-6

3. Click Blank Responsive Landing Page. This opens the editor page with theempty canvas.

4. Drag and drop the image symbol from under Content on the left onto the blankcanvas.You can upload the image or browse for it. If the integration with Oracle Contentand Experience has been enabled, the Content & Experience option is displayedin the left navigation menu.

5. In the Image Chooser, click Content & Experience to browse for an image in theOracle Content and Experience repository that was created to use with Eloqua.You can select any image in the repository.

6. After you choose an image from the Oracle Content and Experience landing page,you can set properties for and size the image on your Eloqua landing page.


2-7

Note:

Using Internet Explorer to insert assets from Oracle Content and Experiencemight cause an error. Oracle recommends that you use Google Chrome orMozilla Firefox to insert assets from Oracle Content and Experience until thisissue is resolved in a future release.

Integrate with ResponsysIntegration with Responsys lets you insert published assets from an Oracle Contentand Experience asset repository into Responsys Email and Mobile campaigns. UsingOracle Content and Experience as a single source for all images saves reworkbecause you can find your images easily.

Responsys users can leverage the extensive asset repositories in Oracle Content andExperience to store content while using Responsys to design campaigns. When youdesign Email and Mobile campaigns, this integration gives you the option to insertpublished image assets from Oracle Content and Experience into your campaigns.You can choose digital assets from an Oracle Content and Experience publishingchannel through the Responsys application.

This is an overview of the Responsys integration with Oracle Content and Experience:

• Choose an Asset Repository and Create Two Publishing Channels

• Enable the Integration

• Create and Publish Assets in Oracle Content and Experience

• View Images in Responsys Message Preview

For more detailed information, see the Oracle Responsys Help Center.

Choose an Asset Repository and Create Two Publishing ChannelsWhen you design an Email or Mobile campaign, you will choose assets from thepublishing channel for the appropriate campaign type. Responsys will automatically

Chapter 2Integrate with Responsys

2-8

https://docs.oracle.com/cloud/latest/marketingcs_gs/OMCEZ/en/ContentExperienceCloud_Overview.htm

filter content assets in Oracle Content and Experience according to the campaign youare designing.

After you choose an asset repository in Oracle Content and Experience, create andshare two publishing channels: a mobile channel and an email channel. Oraclesuggests creating channels that are specifically for Responsys. See Create and SharePublishing Channels.

In Responsys, you can choose Oracle Content and Experience assets from thesechannels.

Enable the IntegrationYou can enable the integration between Oracle Responsys and Oracle Content andExperience account from Responsys.

In Oracle Responsys, choose Oracle Content and Experience Cloud Integrationfrom the Integrate menu.

This feature is available only if it is enabled for your account.

Configure an Oracle Content and Experience Cloud account

1. From the side navigation bar in Responsys, select Account.

2. Select Integration settings, and then choose Content and Experience Cloudsettings.

3. Provide the following details about your Oracle Content and Experience instanceto configure your publishing channels:

• CEC API Version: Your Oracle Content and Experience version.

• CEC Publish Server URL Prefix: The URL of your Oracle Content andExperience instance.

• Email Channel ID: The ID of the Email channel, which is automaticallygenerated when you create the channel.

• Email Channel Token: The Email channel token, which is automaticallygenerated when you create the channel.

• Mobile Channel ID: The Mobile channel ID, which is automatically generatedwhen you create the channel.

• Mobile Channel Token: The Mobile channel token,which is automaticallygenerated when you create the channel.

4. Click Save.

Enable Oracle Content and Experience Embedded Content

In Oracle Content and Experience administration security settings, enable embeddedcontent and add the Responsys URL. Then you can embed the Oracle Content andExperience web UI in Responsys.

See Embed Content in Other Domains.

Create and Publish Assets in Oracle Content and ExperienceYou can create and publish assets in Oracle Content and Experience to use inResponsys.


2-9

1. Create an HTML file.

2. Edit the HTML file in your ResponSys rich text editor.

a. Open the image browser.The browser displays the available image libraries:

b. Click Oracle Content and Experience Cloud to display the Oracle Contentand Experience asset picker.The Oracle Content and Experience asset picker opens on the Digital Assetspage, which displays published assets in the Oracle Content and Experienceaccount. If you don't see an asset you want, you can use the drop-down menuon the left to navigate different asset collections. Or you can upload andpublish an image in Oracle Content and Experience.

c. Pick one of the assets, and click OK.The Image dialog opens and displays a thumbnail of the image and propertiesthat you can set for it:


2-10

• Title text

• Alternative text

• Height

• Width

• Link URL, which makes the image clickable.

d. Set the properties you want.

e. Click Apply to insert the image into your content.To view the URL to the image in Content and Experience, you can clickSource. In a live production environment, this would be an asset pointingdirectly to the content delivery network, so that the asset is accessible.

View Images in Responsys Message PreviewTo preview Oracle Content and Experience images in Responsys, you can use theResponsys Message Preview.

1. On the Oracle Responsys Manage campaigns page, choose Create campaignfrom the drop-down menu on the right, and create an Email or Mobile campaign.


2-11

2. Create a new HTML document.

3. Add a block in the HTML file for an image.


2-12

4. After the image is visible, you can click Preview to preview it in an email message.

Integrate with Oracle Business Intelligence PublisherWhen integrated with Oracle Content and Experience, Business Intelligence Publisheroffers managed folders as a destination for generated reports.

For example, payroll reports can be sent to individual employee folders. Manage thefolders and folder contents with the easy-to-use interface from mobile, web, or desktopdevices. All of the familiar security, sharing, viewing, and collaboration features ofOracle Content and Experience are available to view and manage your reports.

See Setting Output Options in Fusion Middleware User's Guide for Oracle BusinessIntelligence Publisher.

Chapter 2Integrate with Oracle Business Intelligence Publisher

2-13

Integrate with Oracle Process Cloud ServiceYou can allow your users to access Oracle Process Cloud Service functionality, whichlets users manage business processes in the cloud, such as document routing forapproval or review.

Note:

Integration between these services requires SSO sign-ons, so both servicesmust be in the same identity domain.

Integrating Oracle Content and Experience with Oracle Process Cloud Servicebenefits document-intensive processes by organizing, managing, and restrictingaccess to documents that must be submitted, reviewed, and approved or rejected bydifferent roles and organizations during the business process. Conversations enableusers to easily discuss things that come up during the process.

Oracle Content and Experience integrates documents and conversations with yourprocess applications.

• Documents: Oracle Process Cloud Service provides simple file attachmentfunctionality, but if you need something more robust to handle document-intensiveprocesses, you can integrate Oracle Content and Experience. This serviceenables you to organize files into folders, manage access to each folder, and evenstart a process when you upload a document. For example, if you’re processing ahome loan, you need to manage documents such as loan applications,employment histories, and house appraisals, making sure that the right users seethe documents they need to submit, review, or approve, but they don’t get accessto restricted information.

• Conversations: When you integrate conversations, users can easily discuss thingsthat come up during the process. This provides a record of what happened,enabling you to quickly bring new stakeholders up to speed or refer back to thingsas necessary. Plus, the conversation tools work like the social media tools usersregularly use, but with enterprise-wide security and controls. For example, if you’reworking on a contract you might need to discuss some of the terms, while stillmaking sure your discussion is confidential.

• Document- and Folder-Initiated Processes: You can automatically start a processwhen someone uploads a document (or folder of documents) to a chosendocument folder.

You must configure settings in both Oracle Process Cloud Service and Oracle Contentand Experience before users can take advantage of the integrated functionality. For anoverview, see the video Integrate Oracle Documents with Oracle Process CloudService. For information about configuring Oracle Process Cloud Service, see Integrating Documents and Conversations in Using Processes in Oracle Integration.

To configure Oracle Content and Experience to integrate with Oracle Process CloudService:

1. Enable the integration and enter connection information.

a. Sign in to the Oracle Content and Experience web interface as anadministrator.

Chapter 2Integrate with Oracle Process Cloud Service

2-14

https://apexapps.oracle.com/pls/apex/f?p=44785:265:0::::P265_CONTENT_ID:12579

https://apexapps.oracle.com/pls/apex/f?p=44785:265:0::::P265_CONTENT_ID:12579

b. Click System in the Administration area of the navigation menu.

c. In the Settings menu, click Integrations.

d. Under Oracle Integrations, select Process Cloud Service Integration toenable the service, and then set these values:

• Service URL: The URL of the service that users can access for theirapplications:

– If you have Universal Credits subscription, your Service URL shouldlook something like this: https://servicename/ic/api/process/v1/processes.

– If you have a non-metered subscription, your Service URL should looksomething like this: https://servicename/bpm/api/3.0/processes.

• Service User: Enter the email address of the user who owns the processto be used in Oracle Content and Experience. This must be the same useryou entered in Oracle Process Cloud Service.

• Service Password: Enter the user password. This must be the samepassword you entered in Oracle Process Cloud Service.

2. In Oracle Content and Experience, enable Oracle Process Cloud Service use forthe desired folders.

a. In Oracle Content and Experience, open the properties for the folder.

b. Enable Oracle Process Cloud Service use.

c. Select a process from the list.

If the process list is blank, it’s caused by one of the following issues:

• The Oracle Process Cloud Service user you specified in step 2 doesn’t haverights to see the processes.

• The Oracle Process Cloud Service URL you specified in step 2 isn’t correct.

• The Oracle Process Cloud Service user/password combination you specifiedin step 2 isn’t correct.

• The Oracle Process Cloud Service doesn’t have a process that uses aDocuments Start Event. To create a process with a Document Start Event, see Creating a Document- or Folder-Initiated Process in Using Processes inOracle Integration.

After both services have been configured for integration, Oracle Process CloudService users can take actions (such as approvals) on the files directly in OracleProcess Cloud Service. Oracle Content and Experience users can upload files intofolders to initiate a workflow associated with the folder. Oracle Content and Experiencesite designers can create web pages with ready-to-use components that provide folderand file access, process selection and initiation, associated conversation display andinteraction and much more. See Using Built-In Components in Building Sites withOracle Content and Experience.

The following sections provide more details about Oracle Process Cloud Serviceintegration:

• Configure Oracle Integration Settings in Oracle Content and Experience

• Process Cloud Service Integration with Documents


2-15

• Process Cloud Service Integration with Sites

• Pass a CSS Style Sheet to Process Cloud Service

• Start the Default Version of a PCS Process

Configure Oracle Integration Settings in Oracle Content andExperience

Manage workflow for business applications, such as document routing for review orapproval, with Oracle Integration integration enabled for documents in Oracle Contentand Experience.

You can allow your users to access Oracle Integration functionality, which lets usersmanage business processes in the cloud, such as document routing for approval orreview. (This feature may not be available depending on the Oracle Content andExperience subscription type and start date of your service.)

You can allow your users to access Oracle Integration functionality, which lets usersmanage business processes in the cloud, such as document routing for approval orreview. (This feature may not be available depending on the Oracle Content andExperience subscription type and start date of your service.)

Before users can take advantage of the integrated functionality, you must configuresettings in both Oracle Integration and Oracle Content and Experience.

When a task step is complete, a user can manage the file according to the definedprocess. For an incoming document, a user can perform actions based on theassigned role for the document: Contributor, Downloader, or Viewer.

When Oracle Content and Experience starts a process, the following payload is sent tolaunch the process:

{

"operation":"startEvent",

"processDefId":"testing~LoanApplicationProcessing!1.0~LoanApplicationProcessing"

"params": {

"id": "abc123",

"name": "document name",

"startedBy": "user id",

"type": "d",

"role": "role that should be used to generate subsequentapplinks",

"version": "version" }


2-16

}

As a developer, you need be aware of the following requirements for the process youdevelop.

• It needs to be a process that uses an Oracle Content and Experience DocumentStart event.

• When you deploy the process, you need to share it with the user specified forenabling the integration so that user has the rights to trigger the process.

• For the user who uploaded the file to appear as the user who started the task, theprocess must use the value passed in the startedby field as the display name forthe initiator.

Process Cloud Service Integration with DocumentsManage workflow for business applications, such as document routing for review orapproval, with Oracle Process Cloud Service integration enabled for documents inOracle Content and Experience Cloud.

You can allow your users to access Oracle Process Cloud Service functionality, whichlets users manage business processes in the cloud, such as document routing forapproval or review.

This feature may not be available depending on the Content and Experience Cloudsubscription type and start date of your service.

You must configure settings in both Oracle Process Cloud Service and Oracle Contentand Experience Cloud before users can take advantage of the integrated functionality.

1. In Oracle Process Cloud Service, sign in as an administrator and enter connectioninformation for Oracle Content and Experience Cloud. See Integrating Documentsand Conversations in Using Oracle Process Cloud Service.

2. In Oracle Content and Experience Cloud, enable Oracle Process Cloud Serviceintegration and enter connection information:

a. Sign in to Oracle Content and Experience Cloud as an administrator.

b. From the Administration menu, choose Integrations.

c. Under Oracle Applications, select Process Cloud Service Integration toenable the service, and then set these values:

• Service URL: The URL of the REST service that users can access fortheir applications, ending with bpm/api/4.0/processes (for example,https://servicename/bpm/api/4.0/processes).

• Service User: Enter the email address of the user who owns the processto be used in Oracle Content and Experience Cloud.

• Service Password: Enter the user password.

3. To create a process with a Document Start event, see Creating a Document- orFolder-Initiated Process in Using Oracle Process Cloud Service.

When a task step is complete, the file can be managed according to the definedprocess. For an incoming document, a user can perform actions based on theassigned role for that document: Contributor, Downloader, or Viewer.


2-17

When Oracle Content and Experience Cloud starts a process, the following payload issent to launch the process:

{

"operation":"startEvent",

"processDefId":"testing~LoanApplicationProcessing!1.0~LoanApplicationProcessing"

"params": {

"id": "abc123",

"name": "document name",

"startedBy": "user id",

"type": "d",

"role": "role that should be used to generate subsequent applinks",

"version": "version"

}

}

As a developer, you need be aware of the following requirements for the process youdevelop:

• It needs to be a process that uses an Oracle Content and Experience CloudDocument Start event.

• When deploying the process, you need to share it with the user specified forenabling the integration so that user has the rights to trigger the process,

• For the user who uploaded the file to show up as the user who started the task,the process must use the value passed in the startedby field as the display namefor the initiator.

Process Cloud Service Integration with SitesYou can integrate tasks on your sites with Process Cloud Service.

Developers need to be aware of the following requirements for Process Cloud ServiceProcess Cloud Service Integration with Sites:

• The process author needs to ensure that the sites author is added as an initiator ofthe process, or the site author will not be able to see the process in the list ofprocesses available when configuring the start form component.

• The process author also needs to ensure that any site visitor is added as aninitiator of the process, or the visitor, upon filling in the start form, will not actuallybe able to initiate the process.


2-18

Pass a CSS Style Sheet to Process Cloud ServiceAs a developer, you can control the look of a PCS process start form in a site bypassing CSS information through the design.css file in a theme.

To do this, you need to place the CSS style inside of the design.css file that is withinthe theme of the site. The style sheet would be most likely be related to the theme.

On a site page, you can drop a PCS form with Name and Address fields. There is nostyling for the fields.

1. Click Edit in the top right menu to go into edit mode.

2. On the Process Start Form menu, choose Settings.

3. In the Process Start Form Settings dialog, click Custom Settings.

4. In the Properties panel, you can choose a control class under Control ClassName for each field in the PCS form. Each control class specifies a CSS style.

5. In the design.css file for the theme of a site, you can specify properties for eachcontrol class, such as a bold label.

When developing a form, you can specify the control class name on a field-by-fieldbasis.

On the Style tab in the Button Settings panel, contributers can choose styles thatcome with a theme. You can set options for a custom style in Site Builder for editing asite.

In the CKEditor toolbar for both paragraphs and titles, you can choose styles fortoolbar groups. The specifications for these style options go in the components.jsonfile for the theme.

Start the Default Version of a PCS ProcessYou can start the default version of a PCS process and view a sorted list of PCS startforms to choose from.

The PCS start form is part of a process, and the process is an application. When youactivate the application package, it has an associated version number.

1. Each time you change and publish a PCS process, click Activate in the top menuto activate the latest version of the process, which becomes the default version.

2. Under Select a Process in the Custom Settings panel, check Use default processversion.

3. Select a process, and choose a start form from the list.

Integrate with Oracle Developer Cloud ServiceOracle Developer Cloud Service is a cloud-based software development platform thatprovides an open source, standards-based integration to develop, test, and deployapplications into other cloud services such as Oracle Content and Experience.

Develop with OCE Toolkit and Develop for Oracle Content and Experience withDeveloper Cloud Service decscribe the integration.

Chapter 2Integrate with Oracle Developer Cloud Service

2-19

Note:

This integration works only on traditional cloud accounts because it requiresthat the service be in the same identity domain as Oracle Content andExperience.

Integrate with Oracle Visual BuilderYou can allow your users to access Oracle Visual Builder Cloud Service functionality.Oracle Visual Builder Cloud Service (VBCS) is a hosted environment for yourapplication development infrastructure. It provides an open-source standards-basedintegration to develop, collaborate on, and deploy applications within Oracle Cloud.This enables users to rapidly create web and mobile applications with minimal to nocoding.

Note:

• Integration between these services requires SSO, so both services mustbe in the same identity domain.

• Only administrators with the enterprise user role can enable integrationwith VBCS. If you aren’t an enterprise user, the Visual Builder CloudService Integration option is grayed out.

On the VBCS side, the following must be done before this feature can be used withOracle Content and Experience:

• Cross-Origin Resource Sharing (CORS) must be enabled on the VBCS site. See Allow Other Domains Access to Services in Administering Visual Builder in OracleIntegration Cloud.

• Apps must be created and made available for embedding. See Creating a NewWeb Application in Using Visual Builder in Oracle Integration Cloud.

• The apps must be configured for use with Oracle Content and Experience. See Embedding the Application in Using Visual Builder in Oracle Integration Cloud.

• Web applications must be created and made available for embedding in an iframe.

• The Sites SDK must be imported.

• The Sites SDK must be referenced in the web applications.

• A page URL parameter called “id” must be added to the web applications.

On the Oracle Content and Experience side, you need to configure integration withVBCS:

1. After you sign in to the Oracle Content and Experience web application as anadministrator, click System in the Administration area of the navigation menu.

2. In the Settings menu, click Integrations.

3. Under Oracle Integrations, select Visual Builder Cloud Service Integration toenable the service.

Chapter 2Integrate with Oracle Visual Builder

2-20

4. Enter the Service URL of the Oracle Visual Builder Cloud Service.

Note:

If you have Universal Credits subscription, you must include ic/builder in your Service URL. For example, https://vbcsserver.example.com/ic/builder.

After both services have been configured for integration, Oracle Content andExperience users can create components for your VBCS apps and add them to sitepages. See Oracle Visual Builder Cloud Service in Building Sites with Oracle Contentand Experience.

• Embed a VBCS Visual App in an Oracle Content and Experience Page

• Embed a VBCS Page in a Site Page

• Build an Oracle Content and Experience VBCS Public Form Component

• Build an Oracle Content and Experience VBCS Secure Form Component

• Build an Oracle Content and Experience VBCS Public Gated Form Component

• Build an Oracle Content and Experience VBCS Data Report Component

• Build an Oracle Content and Experience VBCS Multipage Form As a Web AppComponent

• Provide a VBCS Endpoint As a URL for Select Menus

Embed a VBCS Visual App in an Oracle Content and ExperiencePage

You can embed a Visual Builder Cloud Service (VBCS) visual app in an OracleContent and Experience site page.

To embed a visual app in a site page, you need to create the app in VBCS and thenadd the app to the page.

Create a Visual App in VBCS

1. Connect to a VBCS Server.

For example: https://vbcs-server/ic/builder (for a Universal Creditssubscription with Oracle Content and Experience) or https://vbcs-server (for anon-metered subscription) .

If you have a Universal Credits subscription, you must include ic/builder in yourService URL.

2. Allow Cross-Origin Resource Sharing (CORS):

a. From the VBCS menu, choose Settings and then Allowed Origins.

b. Click New Origin and enter the URL of your Oracle Content and Experienceserver for Origin Address.

3. Create a new Visual App in VBCS.

4. Create a web application.


2-21

a. Click Web Applications in the navigation menu on the left.

b. Enter a name for the web app, and then click Create.

5. Allow the web app to be embedded in an iframe:

a. Select the web app in the navigator.

b. Choose Settings (the cog icon), and then click the Security tab. ChooseAllow embedding in any application domain.

6. a. Right-click the Resources node in the navigator.

b. Locate the Sites SDK (import the sites.js or sites.min.js file).

The Sites SDK is also available for download from the Oracle Content andExperience server:

http://{server}/_sitesclouddelivery/renderer/app/sdk/js/sites.min.js

c. Click Import. This imports the JS file into the resources directory.

7. Reference the Sites SDK in the page:

a. With the web app selected, choose the HTML tab in Site Builder.

b. Add the following line below the <link> tag:

<script type="text/javascript" src="resources/sites.min.js"></script>

8. Add a page URL parameter called id. Oracle Content and Experience will use thisparameter to pass the ID of the component.

a. Select the page in the web app.


2-22

b. Click the Variables tab.

c. Add a variable called id, and click Create.

d. In the panel on the right, mark the new variable as a URL input parameter.

9. Add code to automatically set the iframe height when the web app renders:

a. Click the JS tab on the on the left of the page.


2-23

b. Add the following code above the return statement. This will resize the heightof the Oracle Content and Experience component when the app renders.

setTimeout(function() { SitesSDK.setProperty("height", null);}, 500);

10. Stage and Publish the VBCS app. The app must be live for the Oracle Contentand Experience site to use it.

Add the VBCS Visual App to an Oracle Content and Experience Site Page

1. In Oracle Content and Experience, configure a VBCS connection:

a. On the Administration menu, choose Integrations and then Applications.

b. Select the Visual Builder Cloud Service Integration check box.

c. Enter the URL of your Oracle Content and Experience instance, and then clickSave.


2-24

2. Create a new VBCS component:

a. Choose Developer and then Components.

b. Choose Create and then Create Visual Builder Component.

c. Publish the VBCS app you created, copy the URL of the app, and then paste itinto the form. Do the same for the web application you created.

3. Add the VBCS component to a site page:

a. Edit a new or existing site.

b. In Site Builder, choose Components and then Custom.


2-25

c. Drag the VBCS component onto the site page.

Embed a VBCS Page in a Site PageYou can embed a Visual Builder Cloud Service (VBCS) page in an Oracle Content andExperience site page.

To embed a VBCS page in a site page, you need to create an app in VBCS and thenadd the app to the site page.

Create an App in VBCS

1. Connect to a VBCS Server.

For example: https://vbcs-server/ic/builder (for a Universal Creditssubscription with Oracle Content and Experience) or https://vbcs-server (for anon-metered subscription) .

Note:

If you have a Universal Credits subscription, you must include ic/builder in your Service URL.


a. Choose Administer Visual Builder, then Global Settings, and then AllowedOrigins.

b. Click New Origin, and enter the URL of your Oracle Content and Experienceserver for Origin Address.


2-26

3. Create a new app in VBCS.

4. Allow the new app to be embedded.

a. Choose Application Settings, then Security, and then Embedding.

b. Select Allow embedding in any domain.

5. Use Data Designer and Page Designer to build your app.

6. Add a custom component to the bottom of your page.

7. Select the Custom Component. Enter the following in the Template section:

<div data-bind="html: script"></div>

8. Enter the following code in the Model section, substituting your own OracleContent and Experience server.

define([], function () {

'use strict';

/** * Inject the SitesSDK and set the Component Height. */ var CustomComponentViewModel = function (params, componentInfo) { this.script = ko.observable( '<script type="text/javascript">\n' + '(function(d, s, id) {\n' + ' var js, fjs = d.getElementsByTagName(s)[0];\n' + ' if (d.getElementById(id))\n' + ' return;\n' + ' js = d.createElement(s);\n' + ' js.id = id;\n' + ' js.src = "https://oracle-content-and-experience-server + ' fjs.parentNode.insertBefore(js, fjs);\n' + ' }(document, "script", "sites-sdk"));\n' + ' setTimeout(function() {\n' + ' SitesSDK.setProperty("height", null);\n' + ' }, 500);\n' + '</script>'); };

return CustomComponentViewModel;});


2-27

9. Enter the following for Application Style. This will hide some of the unwanted"chrome" around the component when embedded in an SCS page.

/* remove some side padding */div#abcs-app-content > div { max-width: none;}

/* allow SitesSDK.setProperty("height") to work */html, body, body.abcs-layout-nonav { height: auto;}

10. Stage and publish the VBCS app. The app must be live for Oracle Content andExperience sites to use it.

Add the VBCS App to a CECS Site Page

1. In Oracle Content and Experience, configure a VBCS Connection:

a. Choose Administration, Integrations, and then Oracle Integrations.

b. Select the Visual Builder Cloud Service Integration check box.

c. Enter the Oracle Content and Experience URL (from Step 1 under Create anApp in VBCS), and then click Save.

2. Create a new VBCS Component:

a. Choose Experience and then Components,

b. Choose Create and then Create VBCS Components.

c. In the drop-down list, choose the VBCS App (created earlier in step 3 underCreate an App in VBCS).


2-28

3. Add the VBCS component to a site page.

a. Edit a new or existing site .

b. In Site Builder, choose Add and then Custom.

c. Drag the VBCS component onto the page.


2-29

Build an Oracle Content and Experience VBCS Public FormComponent

You can build a local Oracle Content and Experience component that uses REST APIsexposed by business objects in VBCS to deliver a simple, anonymous web form, apublic form.

VBCS Configuration


a. Choose Visual Builder , then Settings, and then Allowed Origins.


c. Click the check mark to save.

2. Create a new Application:

3. Configure the app to allow anonymous access.

a. Open Application Settings.

.

b. On the Settings page, choose User Roles.


2-30

c. Select Allow anonymous access.

4. Create a business object:

• Add fields.

• Enable role-based security.

• Grant Anonymous User the Create permission.


2-31

Build an Oracle Content and Experience Local Component

Assumptions:

• The VBCS app name is "RequestForm".

• The business object name is "requestform" and it contains the following customfields:

– name (required)

– email (required)

– phone

– subject

– message

Modify assets/render.js

1. Define the component template as follows.

<div class="form">

 <div class="request-msg green" data-bind="text: requestSuccessMsg"></div>   <div class="request-msg red" data-bind="text: requestFailMsg"></div> 

<label class="required-field" for="name">Name</label> <input type="text" id="name" name="name" required placeholder="Your name. . ." data-bind="value: name"/>

<label class="required-field" for="email">Email</label> <input type="text" id="email" name="email" required placeholder="Your email. . ." data-bind="value: email"/>

<label for="phone"></label>Phone</label> <input type="text" id="phone" name="phone" data-bind="value:


2-32

phone"/> <label for="subject">Subject</label> <input type="text" id="subject" name="subject" data-bind="value: subject"/>

<label for="message"></label>Message</label> <textarea id="message" name="message" rows="6" data-bind="value: message"/>

<button data-bind="click: sendRequest, , enable: canSubmit">Send Request</button></div>

<div class="scs-hidden" data-bind="scsRenderStatus: {'id': id, 'status': 'complete'}"></div>

2. Create the observables for the fields in the Knockout ViewModel.

self.initialized = ko.observable(false);self.requestSuccessMsg = ko.observable();self.requestFailMsg = ko.observable();self.VBCSServerUrl = ko.observable();self.name = ko.observable();self.email = ko.observable();self.phone = ko.observable();self.subject = ko.observable();self.message = ko.observable();

// Get VBCS servervar serverPromise = getVBCSServerURL(); serverPromise.then(function (result) { self.VBCSServerUrl(result.url); self.initialized(true);});

self.canSubmit = ko.computed(function () { return self.name() && self.email();}, self);

3. Handle required fields.

Enable the Submit button only after all required fields have values.

4. Obtain the VBCS connection.

After you configure VBCS connection, there are two ways to get the connection:

• From siteinfo at site runtime

• From Integrations in Site Builder

var getVBCSServerURL = function () { var serverPromise = new Promise(function (resolve, reject) {


2-33

// First try to get from siteinfo var siteConnections = SCSRenderAPI.getSiteProperty('siteConnections'); var serverUrl = siteConnections && siteConnections.VBCSConnection; if (serverUrl) { console.log('Get VBCS server from siteinfo: ' + serverUrl); resolve({'url': serverUrl}); } else { // Get from integrations var configUrl = '/documents/web?IdcService=AF_GET_APP_INFO_SIMPLE&dAppName=VBCS'; $.ajax({ type: 'GET', dataType: 'json', url: configUrl, success: function (data) { var appInfo = data.ResultSets.AFApplicationInfo; var enabled; if (appInfo) { for (var i = 0; i < appInfo.fields.length; i += 1) { if (appInfo.fields[i].name === 'dAppEndPoint') { serverUrl = appInfo.rows[appInfo.currentRow][i]; } else if (appInfo.fields[i].name === 'dIsAppEnabled') { enabled = appInfo.rows[appInfo.currentRow][i]; } if (serverUrl && enabled) { break; } } if (enabled !== '1') { serverUrl = ''; } } console.log('Get VBCS server from Idc Service: ' + serverUrl); resolve({'url': serverUrl}); }, error: function (xhr, status, err) { console.log('Request failed: url:' + configUrl + ' status: ' + status + ' error: ' + err); resolve({'url': serverUrl}); } }); } }); return serverPromise;};


2-34

5. Submit the request

self.sendRequest = function (data, event) { var vbcsServer = self.VBCSServerUrl(); var appName = 'requestform', appVersion = 'live', businessObject = ‘Requestform' var url = vbcsServer + '/rt/' + appName + '/' + appVersion + '/resources/data/' + businessObject; var payload = { "name": self.name(), "email": self.email(), "phone": self.phone(), "subject": self.subject(), "message": self.message() }; $.ajax({ type: 'POST', url: url, beforeSend: function(xhr) { xhr.setRequestHeader( "Content-type", "application/vnd.oracle.adf.resourceitem+json" ); }, data: JSON.stringify(payload), dataType: 'json', success: function (data) { self.requestFailMsg(''); self.requestSuccessMsg('Request has been submitted successfully'); self.name(''); self.email(''); self.phone(''); self.subject(''); self.message(''); }, error: function(jqXhr, textStatus, errorThrown) { console.log('Error:'); console.log(jqXhr); self.requestSuccessMsg(''); self.requestFailMsg('Failed to submit the request'); } });};

Modify styles/design.css

Add the following css to design.css.

.form { font-family: "Helvetica Neue", "Segoe UI", sans-serif-regular, Helvetica, Arial, sans-serif; font-size: 14px;}.form input[type=text] {


2-35

width: 100%; padding: 12px 20px; margin: 8px 0; display: inline-block; border: 1px solid #ccc; border-radius: 4px; box-sizing: border-box;}.form textarea { width: 100%; padding: 12px 20px; margin: 8px 0; display: inline-block; border: 1px solid #ccc; border-radius: 4px; box-sizing: border-box;}.form button { width: 100%; background-color: #4CAF50; color: white; padding: 14px 20px; margin: 8px 0; border: none; border-radius: 4px; cursor: pointer;}.form button:hover { background-color: #45a049;}.form button:disabled { background-color: #dddddd;}.required-field::after { content: "*"; color: red; margin-left:2px}.request-msg { padding: 5px; font-size: 18px; font-weight: bold; text-align: center; margin-bottom: 20px;}.green { background-color: #81BA5E;}.red { background-color: red;}


2-36

Use the Form Component on Oracle Content and Experience

1. Configure the VBCS connection:

• Choose Administration, then Integrations, and then Applications.

• Click the Visual Builder Cloud Service Integration check box.

• Enter the URL, and click Save.

2. Import the component:

• Choose Developer and then Components.

• Choose Create and then Import Component.

3. Add the component to a page:



c. Drag the component onto the page.


2-37

Build an Oracle Content and Experience VBCS Secure FormComponent

You can build a local Oracle Content and Experience component that uses REST APIsexposed by business objects in VBCS to deliver a simple web form that requires userauthentication.

VBCS Configuration





2. Create a new Application

.

3. Configure the app to allow access for authenticated users.

a. Open Application Settings.

.


c. Add roles to control access to the business object.

The values for Mapping are groups from Oracle Identity Cloud Service. Toadd groups, see Create Groups for Your Organization.


2-38

4. Create a business object.

• Add fields.

• Enable role-based security

• Grant roles to Create permission.


Assumptions:


2-39

• The business object name is "requestform" and it contains the following customfields:

– name (required)


– phone

– subject

– message



<div class="form">

 <div class="request-msg green" data-bind="text: requestSuccessMsg"></div>   <div class="request-msg red" data-bind="text: requestFailMsg"></div> 

<label class="required-field" for="name">Name</label> <input type="text" id="name" name="name" required placeholder="Your name. . ." data-bind="value: name"/>

<label class="required-field" for="email">Email</label> <input type="text" id="email" name="email" required placeholder="Your email. . ." data-bind="value: email"/>

<label for="phone"></label>Phone</label> <input type="text" id="phone" name="phone" data-bind="value: phone"/>

<label for="subject">Subject</label> <input type="text" id="subject" name="subject" data-bind="value: subject"/>

<label for="message"></label>Message</label> <textarea id="message" name="message" rows="6" data-bind="value: message"/>

<button data-bind="click: sendRequest, , enable: canSubmit">Send Request</button></div>

<div class="scs-hidden" data-bind="scsRenderStatus: {'id': id,


2-40

'status': 'complete'}"></div>


self.initialized = ko.observable(false);self.requestSuccessMsg = ko.observable();self.requestFailMsg = ko.observable();self.VBCSServerUrl = ko.observable();self.name = ko.observable();self.email = ko.observable();self.phone = ko.observable();self.subject = ko.observable();self.message = ko.observable();

// Get VBCS servervar serverPromise = getVBCSServerURL(); serverPromise.then(function (result) { self.VBCSServerUrl(result.url); self.initialized(true);});

self.canSubmit = ko.computed(function () { return self.name() && self.email();}, self);



4. Obtain the VBCS connection

After configure VBCS connection, there are two ways to get the connection:



var getVBCSServerURL = function () { var serverPromise = new Promise(function (resolve, reject) { // First try to get from siteinfo var siteConnections = SCSRenderAPI.getSiteProperty('siteConnections' var serverUrl = siteConnections && siteConnections.VBCSConnection; if (serverUrl) { console.log('Get VBCS server from siteinfo: ' + serverUrl); resolve({'url': serverUrl}); } else { // Get from integrations var configUrl = '/documents/web?IdcService=AF_GET_APP_INFO_SIMPLE&dAppName=VBCS'; $.ajax({ type: 'GET', dataType: 'json',


2-41

url: configUrl success: function (data) { var appInfo = data.ResultSets.AFApplicationInfo; var enabled; if (appInfo) { for (var i = 0; i < appInfo.fields.length; i += 1) { if (appInfo.fields[i].name === 'dAppEndPoint') { serverUrl = appInfo.rows[appInfo.currentRow][i]; } else if (appInfo.fields[i].name === 'dIsAppEnabled') { enabled = appInfo.rows[appInfo.currentRow][i]; } if (serverUrl && enabled) { break; } } console.log('Get VBCS server from Idc Service: ' + serverUrl); resolve({'url': serverUrl}); }, error: function (xhr, status, err) { console.log('Request failed: url:' + configUrl + ' status: ' + status + ' error: ' + err); resolve({'url': serverUrl}); } }); } }); return serverPromise;};

5. Get an authorization token.

Requirement: Oracle Content and Experience and VBCS are deployed in thesame identity domain.

var getAuthToken = function (args) { // dummy function if callbacks not supplied var dummyCallback = function () {};

// extract the args and create the server URL var serverURL = (args.serverURL || '/').split('/ic/')[0], successCallback = args.successCallback || dummyCallback, errorCallback = args.errorCallback || dummyCallback, tokenURL = serverURL + ‘/ic/builder/resources/security/token’;

// For VBCS to get the authtoken: // - make a POST call to /ic/builder/resources/security/token // - include scope=run-time form parameter var getToken = function (tokenURL, successCallback, errorCallback) { $.ajax({


2-42

'type': 'POST', 'url': tokenURL, data: { scope: 'run-time' }, 'xhrFields': { withCredentials: true }, 'success': successCallback }).fail(errorCallback); };

// try to get the token normally getToken(tokenURL, function (resp, status, xhr) { var ct = xhr.getResponseHeader("content-type") || "";

// if the response was an HTML Form. . . if (ct.indexOf('html') > -1) { // parse the form and submit it var parser = new DOMParser(), htmlDoc = parser.parseFromString(resp, "text/html"), forms = htmlDoc.getElementsByTagName("form"); if (forms.length === 1) { var f = forms[0]; $.ajax({ 'type': 'POST', 'url': f.action, 'data': $(f).serialize(), 'xhrFields': { 'withCredentials': true 'success': function () { // retry getting the token now the form was auto-submitted getToken(tokenURL, successCallback, errorCallback); } }).fail(function () { // even if the form submit failed, retry getting the token getToken(tokenURL, successCallback, errorCallback); }); } } else { // already logged in return the token successCallback(resp); } }, errorCallback);};


2-43

6. Submit the request.

self.sendRequest = function (data, event) { var vbcsServer = self.VBCSServerUrl(); var authorization, token; var appName = 'securerequestform', mode = 'rt', appVersion = 'live', businessObject = 'Requestform'; var url = vbcsServer + '/' + mode + '/' + appName + '/' + appVersion + '/resources/data/' + businessObject; var payload = { "name": self.name(), "email": self.email(), "phone": self.phone(), "subject": self.subject(), "message": self.message() }; // get token first getAuthToken({ 'serverURL': self.VBCSServerUrl(), 'successCallback': function (data) { token = data; authorization = (token.token_type ? token.token_type : 'Bearer') + ' ' + token.access_token; $.ajax({ type: 'POST', url: url, beforeSend: function (xhr) { xhr.setRequestHeader('Content-type', 'application/vnd.oracle.adf.resourceitem+json'); xhr.setRequestHeader('Authorization', authorization); }, data: JSON.stringify(payload), dataType: 'json', success: function (data) { self.requestFailMsg(''); self.requestSuccessMsg('Request has been submitted successfully’); self.name(''); self.email(''); self.phone(''); self.subject(''); self.message(''); }, error: function (jqXhr, textStatus, errorThrown) { console.log('Error:'); console.log(jqXhr); self.requestSuccessMsg(''); self.requestFailMsg('Failed to submit the request'); } }); }, 'errorCallback': function (xhr, status, err) {


2-44

if (xhr && xhr.status === 200) { token = xhr.responseText; console.log('Got token'); } else { console.error('getToken: xhr: ' + JSON.stringify(xhr) + ' status: ' + status + ' error: ' + err); self.requestSuccessMsg(''); self.requestFailMsg('Failed to get authorization token'); } } });};



.form { font-family: "Helvetica Neue", "Segoe UI", sans-serif-regular, Helvetica, Arial, sans-serif; font-size: 14px;}.form input[type=text] { width: 100%; padding: 12px 20px; margin: 8px 0; display: inline-block; border: 1px solid #ccc; border-radius: 4px; box-sizing: border-box;}.form textarea { width: 100%; padding: 12px 20px; margin: 8px 0; display: inline-block; border: 1px solid #ccc; border-radius: 4px; box-sizing: border-box;}.form button { width: 100%; background-color: #4CAF50; color: white; padding: 14px 20px; margin: 8px 0; border: none; border-radius: 4px; cursor: pointer;}.form button:hover { background-color: #45a049;}


2-45

.form button:disabled { background-color: #dddddd;}.required-field::after { content: "*"; color: red; margin-left:2px}.request-msg { padding: 5px; font-size: 18px; font-weight: bold; text-align: center; margin-bottom: 20px;}.green { background-color: #81BA5E;}.red { background-color: red;}









3. Add the component to a page




2-46


Note:

This VBCS secure form component works only on secure sites.

Build an Oracle Content and Experience VBCS Public Gated FormComponent

You can build a local Oracle Content and Experience component that uses REST APIsexposed by business objects in VBCS to deliver a simple, anonymous web form thatcaptures visitor details to allow the visitor to download a document.

VBCS Configuration





2. Create a new Application.

3. Configure the app to allow anonymous access.

a. Open Application Settings .

.


2-47


c. Select Allow anonymous access.

4. Create a business object:

• Add fields.


2-48

• Enable role-based security.

• Grant Anonymous User the Create permission.


Assumptions:


• The business object name is "registration" and it contains the custom fields.


2-49

– firstName (required)

– lastName (required)


– phone

– company

– jobTitle





div class="form">  <h1 style="text-align: center;">Fill out the form to access the document</h1>

 <div class="request-msg green" data-bind="text: requestSuccessMsg"></div>  <div class="request-msg red" data-bind="text: requestFailMsg"></div>

<label class="required-field" for="firstname">First Name</label> <input type="text" id="firstname" name="firstname" required placeholder="Your first name. . ." data-bind="value: firstName"/> <label class="required-field" for="lastname">Last Name</label> <input type="text" id="lastname" name="lastname" required placeholder="Your last name. . ." data-bind="value: lastName"/> <label class="required-field" for="email">Business E-mail</label> <input type="text" id="email" name="email" required placeholder="Your email. . ." data-bind="value: email"/> <label for="phone"></label>Phone</label> <input type="text" id="phone" name="phone" data-bind="value: phone"/> <label for="company">Company</label> <input type="text" id="company" name="company" data-bind="value: company"/> <label for="jobtitle"></label>Job Title</label> <input type="text" id="jobtitle" name="jobtitle" data-bind="value: jobTitle"/>

<button data-bind="click: sendRequest, enable: canSubmit">Accept the document</button> 

 <div class="download"> <h2>Thanks for your registration. Please click the button to download. </h2>


2-50

<button data-bind="click: startDownload">Download</button> <button data-bind="click: closeDownload">Close</button> </div> </div>

<div class="scs-hidden" data-bind="scsRenderStatus: {'id': id, 'status': 'complete'}"></div>


self.initialized = ko.observable(false);self.requestSuccessMsg = ko.observable();self.requestFailMsg = ko.observable();self.VBCSServerUrl = ko.observable();self.showDownload = ko.observable(false);

self.firstName = ko.observable();self.lastName = ko.observable();self.email = ko.observable();self.phone = ko.observable();self.company = ko.observable();self.jobTitle = ko.observable();

self.canSubmit = ko.computed(function () { return self.firstName() && self.lastName() && self.email();}, self);




After you configure a VBCS connection, there are two ways to get the connection:



var getVBCSServerURL = function () { var serverPromise = new Promise(function (resolve, reject) { // First try to get from siteinfo var siteConnections = SCSRenderAPI.getSiteProperty('siteConnections'); var serverUrl = siteConnections && siteConnections.VBCSConnection; if (serverUrl) { console.log('Get VBCS server from siteinfo: ' + serverUrl); resolve({'url': serverUrl}); } else { // Get from integrations var configUrl = '/documents/web?


2-51

IdcService=AF_GET_APP_INFO_SIMPLE&dAppName=VBCS'; $.ajax({ type: 'GET', dataType: 'json', url: configUrl, success: function (data) { var appInfo = data.ResultSets.AFApplicationInfo; var enabled; if (appInfo) { for (var i = 0; i < appInfo.fields.length; i += 1) { if (appInfo.fields[i].name === 'dAppEndPoint') { serverUrl = appInfo.rows[appInfo.currentRow][i]; } else if (appInfo.fields[i].name === 'dIsAppEnabled') { enabled = appInfo.rows[appInfo.currentRow][i]; } if (serverUrl && enabled) { break; } } if (enabled !== '1') { serverUrl = ''; } } console.log('Get VBCS server from Idc Service: ' + serverUrl); resolve({'url': serverUrl}); }, error: function (xhr, status, err) { console.log('Request failed: url:' + configUrl + ' status: ' + status + ' error: ' + err); resolve({'url': serverUrl}); } }); } }); return serverPromise;};

5. Submit the request.

self.sendRequest = function (data, event) { var vbcsServer = self.VBCSServerUrl(); var appName = 'requestform', appVersion = 'live', businessObject = 'Registration'; var url = vbcsServer + '/rt/' + appName + '/' + appVersion + '/resources/data/' + businessObject; var payload = { 'firstName': self.firstName(),


2-52

'lastName': self.lastName(), 'email': self.email(), 'phone': self.phone(), 'company': self.company(), 'jobTitle': self.jobTitle() };

$.ajax({ type: 'POST', url: url, beforeSend: function (xhr) { xhr.setRequestHeader('Content-type', 'application/vnd.oracle.adf.resourceitem+json'); }, data: JSON.stringify(payload), dataType: 'json', success: function (data) { self.requestFailMsg(''); self.requestSuccessMsg('Request has been submitted successfully'); self.firstName(''); self.lastName(''); self.email(''); self.phone(''); self.company(''); self.jobTitle(''); self.showDownload(true); }, error: function (jqXhr, textStatus, errorThrown) { console.log('Error:'); console.log(jqXhr); self.requestSuccessMsg(''); self.requestFailMsg('Failed to submit the request'); } });};

6. Create a trigger to download a document.

{ "id": "ECVBCS-Gated-Form", "settingsData": { "settingsHeight": 90, "settingsWidth": 300, "settingsRenderOption": "dialog", "componentLayouts": [], "triggers": [{ "triggerName": "VBCSGatedFormSubmitted", "triggerDescription": "VBCS gated form submitted", "triggerPayload": [{ "name": "payloadData", "displayName": "Document URL" }] }],


2-53

"actions": [] },}

Register the trigger in appinfo.json.

self.raiseTrigger = function (triggerName) { SitesSDK.publish(SitesSDK.MESSAGE_TYPES.TRIGGER_ACTIONS, { 'triggerName': triggerName, 'triggerPayload': { 'payloadData': 'https://docs.oracle.com/en/cloud/paas/content-cloud/developer/developing-oracle-content-and-experience-cloud.pdf' } });};

self.startDownload = function (data, event) { console.log('Raise trigger: VBCSGatedFormSubmitted'); self.raiseTrigger("VBCSGatedFormSubmitted"); // matches appinfo.json};

• Raise the trigger in render.js.

\



.form { font-family: "Helvetica Neue", "Segoe UI", sans-serif-regular, Helvetica, Arial, sans-serif; font-size: 14px;}.form input[type=text] { width: 100%; padding: 12px 20px; margin: 8px 0; display: inline-block; border: 1px solid #ccc; border-radius: 4px; box-sizing: border-box;}.form textarea { width: 100%; padding: 12px 20px; margin: 8px 0; display: inline-block; border: 1px solid #ccc; border-radius: 4px; box-sizing: border-box;}.form button { width: 100%;


2-54

background-color: #4CAF50; color: white; padding: 14px 20px; margin: 8px 0; border: none; border-radius: 4px; cursor: pointer;}.form button:hover { background-color: #45a049;}.form button:disabled { background-color: #dddddd;}.required-field::after { content: "*"; color: red; margin-left:2px}.request-msg { padding: 5px; font-size: 18px; font-weight: bold; text-align: center; margin-bottom: 20px;}.green { background-color: #81BA5E;}.red { background-color: red;}










2-55

3. Add the component to a page:





2-56

Note:

This VBCS public form component can be used on public or secure sites.

Build an Oracle Content and Experience VBCS Data ReportComponent

You can build a local Oracle Content and Experience component that uses REST APIsexposed by business objects in VBCS to deliver reports on data collected throughforms.

Use data from a public form component to show the number of requests per day in aCSS bar chart. See Build an Oracle Content and Experience VBCS Public FormComponent.


Assumptions:

• The VBCS app name is “RequestForm”.

• The business object name is “requestform”.



<h1 style="text-align: center;">Number of requests per day</h1>


2-57

<div class="chartrow"><div class="chartbody"> <div class="chartbody"> <table id="q-graph"> <tbody data-bind="foreach: requests"> <tr class="qtr" data-bind="css: barcss"> <td class="day bar" data-bind="style: {height: height}"> <p><span data-bind="text: value"></span></p> </td> </tr> </tbody> </table>

<div id="ticks" data-bind="foreach: ticks"> <div class="tick" style="height: 59px;"> <p><span data-bind="text: value"></span></p> </div> </div> </div> <div class="chartlabel"> <div class="labelrow"> <div class="colorindex sunday"></div> <span>Sunday</span> </div> <div class="labelrow"> <div class="colorindex monday"></div> <span>Monday</span> </div> <div class="labelrow"> <div class="colorindex tuesday"></div> <span>Tuesday</span> </div> <div class="labelrow"> <div class="colorindex wednesday"></div> <span>Wednesday</span> </div> <div class="labelrow"> <div class="colorindex thursday"></div> <span>Thursday</span> </div> <div class="labelrow"> <div class="colorindex friday"></div> <span>Friday</span> </div> <div class="labelrow"> <div class="colorindex saturday"></div> <span>Saturday</span> </div> </div></div><div class="scs-hidden" data-bind="scsRenderStatus: {'id': id, 'status': 'complete'}"></div>


2-58


self.initialized = ko.observable(false);self.VBCSServerUrl = ko.observable();

self.requests = ko.observableArray();self.ticks = ko.observableArray(); // Get VBCS servervar serverPromise = getVBCSServerURL();serverPromise.then(function (result) { self.VBCSServerUrl(result.url); self.initialized(true); self.getRequests();});


See Build an Oracle Content and Experience VBCS Public Form Component.

4. Get an Authorization Token.

Requirement: Oracle Content and Experience and VBCS are deployed in thesame identity domain. See Build an Oracle Content and Experience VBCS SecureForm Component.

5. Get requests.

Use a business object endpoint:

/Requestform

self.getRequests = function () { var vbcsServer = self.VBCSServerUrl(); var authorization, token; var appName = 'requestform', mode = 'rt', appVersion = 'live' businessObject = 'Requestform'; var url = vbcsServer + '/' + mode + '/' + appName + '/' + appVersion + '/resources/data/' + businessObject;

// get token first getAuthToken({ 'serverURL': self.VBCSServerUrl(), successCallback': function (data) { token = data; authorization = (token.token_type ? token.token_type : 'Bearer') + ' ' + token.access_token; url = url + '?limit=999&orderBy=creationDate:desc'; $.ajax({ type: 'GET', url: url, beforeSend: function (xhr) { xhr.setRequestHeader('Authorization', authorization);


2-59

}, success: function (data) { if (data && data.count > 0) { self.showChart(data.items); } }, error: function (jqXhr, textStatus, errorThrown) { console.log('Error:'); console.log(jqXhr); } }); }, 'errorCallback': function (xhr, status, err) { if (xhr && xhr.status === 200) { token = xhr.responseText; console.log('Got token'); } else { console.error('getToken: xhr: ' + JSON.stringify(xhr) + ' status: ' + status + ' error: ' + err); } } });};

6. Set up chart data.

self.showChart = function (items) { var weekDayCounts = [0, 0, 0, 0, 0, 0, 0]; var weekDayNames = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday']; for(var i = 0; i < items.length; i++) { var d = new Date(items[i].creationDate); var day = d.getDay(); if (day >= 0 && day < 7) { weekDayCounts[day] = weekDayCounts[day] + 1; } } var max = 0; var results = []; for(var i = 0; i < weekDayCounts.length; i++) { if (max < weekDayCounts[i]) { max = weekDayCounts[i]; } } var lines = 7, buckets = 5; var gap = Math.round(max / buckets); var top = gap * (lines - 1); if (max > top) { gap += 1; } var ticks = []; for(var i = 0; i < lines; i++) { ticks[i] = { value: i * gap


2-60

}; } self.ticks(ticks.reverse()); for(var i = 0; i < weekDayCounts.length; i++) { var height = (weekDayCounts[i] / gap) * 60; results.push({ height: height.toString() + 'px', value: weekDayCounts[i], barcss: weekDayNames[i].toLowerCase() }); } self.requests(results);};

Use the Component on Oracle Content and Experience

For information about how to add the component on a page, see Build an OracleContent and Experience VBCS Public Form Component.

The component renders as follows.

This VBCS component works only on secure sites.

Build an Oracle Content and Experience VBCS Multipage Form As aWeb App Component

You can build a complex, multipage form for Oracle Content and Experience as acomponent of a VBCS web application.


2-61

To build a VBCS multipage form as a web application component for Oracle Contentand Experience, you can remove the header and footer, set the IFrame height, addvalidation for required form fields, .Call a REST endpoint to save form data, and, for apublic web application, set security to allow anonymous access.

Remove the VBCS Web Application Header and Footer

If you don’t want the default VBCS web application’s header and footer, you canremove them from the page.

Set the VBCS Component Iframe Height

You need to set the VBCS component iframe height for each page in the flow of theweb app. Include a validation group in the page model,

Required Form Fields Validation

When you try to navigate to another page, some of form fields on the current page aremarked as "required" and don’t have values yet. By default, there is no validation. Youcan use oj-validation-group to add the validation:

1. Wrap all your form fields inside the component <oj-validation-group>.


2-62

2. Include oj-validation-group in the page model.


2-63

3. Create a Flow module function .


2-64

4. Create an action chain for the "Go to the Next Step" button.


2-65

The "If" condition checks the values for the required fields; for example:

{{ $flow.variables.enroll_values.field && $flow.variables.enroll_values.zip }}

If the condition evaluates to true, navigation goes to the second step. Otherwise, itstays on the current page, and the error message is shown.

Call REST Endpoint to Save Form Data

At the last step, after the form fields validation, you can use the "Call REST Endpoint"action to persist form data in the business object.


2-66

Public Web Application

If the web application is intended for public, you can set security to allow anonymousaccess.

Also allow anonymous access for the business object.


2-67

Provide a VBCS Endpoint As a URL for Select MenusA content administrator can provide a Visual Builder Cloud Service (VBCS) endpointas a URL to get values for select menus.

Instead of typing values for a select menu, users can enter a VBCS URL to get thevalues for the select menu in the Site Builder dialog. The content administrator canconfigure what attributes to use for option text and values in a REST response, using apublic or secure VBCS URL.

Users can populate VBCS select menus in content item forms based on the URLconfiguration. When defining a content type and fields for the content type, the contentadministrator has the option to select a single-value menu that uses a Visual Builderendpoint.

The data for a content item is pooled by the Visual Builder URL. A business object,such as Company, can be defined by many fields in VBCS.

To create a content type with a VBCS endpoint as a URL for select menus:

1. Sign in as a content administrator in your browser and click Assets underAdministration in the left navigation menu.

2. Choose Content Types from the drop-down menu and click Create.

3. Enter VBCS as the name of your content type.

4. Under Content Type Definition for the VBCS content type, click Edit to edit thesettings.

5. In the Text Settings dialog, click Appearance.

6. Under Appearance of data field, choose Single-select menu (Visual Builderendpoint).


2-68

7. In the Visual Builder endpoint URL field, enter a valid endpoint that is defined inVBCS.

8. For Endpoint security, select the check box if the Visual Builder endpoint requiresan authenticated user. If the check box is not selected, anonymous users can usethe VBCS endpoint.

9. Enter values for the REST field to use as label and REST Field to use as valuefields, such as companyName and email.

10. Click Test Configuration to test the settings. If the configuration is correct, a"Test successful" message appears.

11. Save your changes and click OK.


2-69

In the Create Content Item dialog, the UI for a VBCS content type looks identical to asingle-select box for static data, except the data for the content item is dynamicallypooled from the VBCS side with a run search. The value of REST field to use as avalue, such as email, gets stored in the Oracle Content and Experience database.

Integrate with Intelligent AdvisorYou can give users access to Intelligent Advisor functionality, which implements online"interview" scenarios, such as feedback for troubleshooting or eligibility assessmentsfor services. Intelligent Advisor delivers advice across channels by capturing rules inMicrosoft Word and Excel documents, then building interactive customer serviceexperiences called interviews around those rules.

Note:

Only administrators with the enterprise user role can enable integration withIntelligent Advisor. If you aren't an enterprise user, the Intelligent AdvisorCloud Service Integration option is grayed out.

On the Intelligent Advisor side, interviews must be created and stored on the host site.In addition, the Intelligent Advisor administrator must add the Oracle Content and

Chapter 2Integrate with Intelligent Advisor

2-70

Experience domains (*.documents.* and *.sites.*) to the list of hosts authorized toembed interviews. See the Intelligent Advisor Automation documentation.

On the Oracle Content and Experience side, you need to configure integration withIntelligent Advisor:

1. After you sign in to the Oracle Content and Experience web application as anadministrator, open your user menu and click Administration.

2. In the Administration menu, click Integrations.

3. Under Oracle Integrations, select Intelligent Advisor Cloud ServiceIntegration to enable the service, and then set these values:

• Service URL: Enter the URL of the Intelligent Advisor Cloud Service.

• Service User: Enter the name of the Intelligent Advisor user. This user mustbe an Integration user and must have the Deploy Admin role for the IntelligentAdvisor collections.

• Service Password: Enter the user password.

After both services have been configured for integration, Oracle Content andExperience users can add an Intelligent Advisor component to site pages. See Intelligent Advisor.

Integrate with Oracle Cobrowse Cloud ServiceYou can allow your users to access Oracle Cobrowse Cloud Service functionality,which lets users share screens or initiate a cobrowsing session with another person.For example, you might want to use cobrowse on a sales site so that a salesrepresentative can help a customer select appropriate products or services on the site.

Note:

Only administrators with the enterprise user role can enable integration withOracle Cobrowse Cloud Service. If you aren't an enterprise user, the OracleCobrowse Cloud Service Integration option is grayed out.

To integrate with Oracle Cobrowse Cloud Service:

1. After you sign in to the Oracle Content and Experience web application as anadministrator, open your user menu and click Administration.

2. In the Administration menu, click Integrations.

3. Under Oracle Integrations, select Oracle Cobrowse Cloud Service Integrationto enable the service, and then set these values:

• Service URL: Enter the URL for the Cobrowse service. See Log in to theAgent Console in the Standalone Cobrowse User Guide for the link (forexample, https://www.livelook.com).

• Service User: Enter the Oracle Cobrowse Cloud Service administrator username.

• Service Password: Enter the user’s password.

Chapter 2Integrate with Oracle Cobrowse Cloud Service

2-71

http://documentation.custhelp.com/euf/assets/devdocs/unversioned/PolicyAutomation/en/Default.htm#Guides/Welcome/Welcome.htm

https://docs.oracle.com/cloud/latest/servicecs_gs/FASGU/cobrowse_user_guide-2.htm

https://docs.oracle.com/cloud/latest/servicecs_gs/FASGU/cobrowse_user_guide-2.htm

After you've configured the integration, Oracle Content and Experience users canenable cobrowse to work with a site and add the Cobrowse Launcher component to asite page. See Enable Cobrowse Integration and Use Cobrowse on a Page in BuildingSites with Oracle Content and Experience.

Note:

If you later decide to disable cobrowse, you must disable the option on theIntegrations page and in the site settings for any sites that use cobrowse. Ifyou disable only the option on the Integrations page, any sites that usecobrowse will continue to do so, but users won't be able to add newcobrowse functionality.

Chapter 2Integrate with Oracle Cobrowse Cloud Service

2-72

3Use Apps and Services in Oracle Contentand Experience

Oracle Content and Experience helps you expand the service to include your ownapps or to communicate with other services.

• Understand Cross-Origin Resource Sharing (CORS)

• Understand the Application Integration Framework (AIF)

• Manage Custom Applications

Understand Cross-Origin Resource Sharing (CORS)Cross-Origin Resource Sharing (CORS) allows a web page to make requests such asXMLLHttpRequest to another domain. If you have a browser application that integrateswith Oracle Content and Experience Cloud but is hosted in a different domain, add thebrowser application domain to Oracle Content and Experience Cloud’s CORS originslist.

The REST APIs use CORS because they're called from JavaScript code that runs in abrowser and the REST APIs and Oracle Content and Experience are hosted indifferent domains.

If your browser application needs to use a REST endpoint that doesn't support CORSor that needs service account credentials, you can instead register and use theendpoint via Oracle Content and Experience’s integrated proxy service. See ConfigureProxy Service Settings.

In general, inline frames can host content if the protocol, domain, and port of the inlineframe are identical to those for the content it displays. For example, by default, aninline frame on the page http://www.example.com:12345/home.html can host contentonly if the content's protocol is also http, the domain is www.example.com and the portis 12345.

However, if the application is in a different domain than Oracle Content andExperience, you need to need to add the application’s host machine information to thelist of front channel CORS origins, back channel CORS origins, or both.

• If the request is a cross-domain request (not originating from Oracle Content andExperience's domain) that will be served by Oracle Content and Experience, youneed to add a front channel CORS origin. Front channel CORS is typically usefulfor custom application integration. For example, the REST APIs interact with thefront channel.

• If the request is directly from Oracle Content and Experience to a connected clientin another domain, you need to add a back channel CORS origin. For example,Oracle Content and Experience can send back-channel messages (real-timeupdates) to an application.

3-1

• If an application gets both front-channel and back-channel communication fromOracle Content and Experience, you need to add the domain to both the front andback channel CORS origins lists.

The CORS settings apply to all Oracle Content and Experience calls (documents,social, and content as a service).

See Enable Cross-Origin Resource Sharing (CORS) in Administering Oracle Contentand Experience.

Understand the Application Integration Framework (AIF)Application Integration Framework (AIF) provides a simple and effective way tointegrate third-party services and applications into the Oracle Content and Experienceweb interface.

Using AIF, you can quickly define the actions that are exposed in the web interface,respond to user selections, call third-party services, and specify how the results arepresented to the user. The framework supports variables and expressions andprovides multiple language support.

Custom AIF applications are not applied when you access them through an applink orpublic link.

The definition for one or more integrations is stored in a single file in JSON format. Asa developer, you can upload the configuration file and add it to a list of availableapplications. You can also edit and validate the configuration file directly in the webinterface, enable or disable the app for general use, set preferences, or delete the app.

The definition for one or more integrations is stored in a single configuration file inJSON format. The configuration file defines and manages the interactions between theapp, native objects and web interface elements. The configuration file includes:

• App properties including tenant and user preferences

• Actions that are exposed in the web interface and the service calls they make

• How the results are presented to the user

• Interface strings with support for multiple languages

Chapter 3Understand the Application Integration Framework (AIF)

3-2

As a developer, you can add the configuration file, enable the integration, and providetenant and account information to get started. You can also edit and validate theconfiguration file directly in the web interface, download the configuration file, or deletethe app.

To manage apps created with Application Integration Framework, sign in as adeveloper, open your user menu, choose Administration, and then chooseIntegrations. Under Custom Actions, click Add.


3-3

From the Applications page, you can use the following options.

Setting Description

Enable or disable the application for users. When you enable theapplication, you can specify preferences for the application from theuser menu, by choosing Preferences and then ApplicationsSettings. You specify the user preferences resource in theuserPrefs element in the configuration file.

Browse local folders and files to locate and upload an applicationconfiguration file.

Display the information defined for the application and specified in theinfo element of the configuration file.

Display the preferences resource defined in the tenantPrefs elementof the configuration file.


3-4

Setting Description

Open the configuration file in the integrated JSON editor. The editorvalidates the syntax of the file to ensure that the file contains validJSON code. Changes you make to the configuration file areimmediately available in the enabled application.

Changes you make to the configuration file are stored only in theserver copy of the file. To back up your changes, use the Downloadicon to save the file locally.

Download the file from the server to a local destination.

Delete the configuration permanently.

When you delete a configuration file, the deletion is permanent. Thefile can’t be restored from the trash.

Manage Custom ApplicationsYou can create custom applications using the Application Integration Framework (AIF).

With custom applications, you can change the menu options your users will see, addpop-up dialogs as needed, call third-party services, and specify how the results arepresented to the user.

For details about creating applications using AIF, see Application IntegrationFramework Overview .

After creating an application, you can add it to Oracle Content and Experience andmanage it from the Administration web interface.


2. In the Settings menu, click Integrations.

3. To add an application, under Custom Actions, click Add and navigate to thelocation where the configuration file that contains the application information isstored and select it.

4. After adding the application, you can enable or disable it by selecting or clearingthe check box.

After you add your application and enable it, you can manage it by clicking theappropriate icon for any of the following actions:

• View information about the application. What is shown is set by the application’sinfo application property (for example, a popup window).

• Set the preferences for the application. What is shown is set by the application’stenantPrefs property.

• Edit the application. You can alter the application’s code and click Load to test theapplication, save the application, or cancel your edit. If an action isn’t allowed inthe code, an error message is displayed, describing the error.

• Download the application. You can save the application or open it using an editorof your choice.

Chapter 3Manage Custom Applications

3-5

• Remove the application. When you delete an application, it is not moved to yourtrash. You will need to add the application file again if you want to use it.

When an application is disabled, you can only edit the application, download it, ordelete it.

To view all enabled applications, open your user menu, click Preferences, and then,in the Preferences menu, select Applications. You can view the information for theapplication and the preferences. The Applications option is not shown in thePreferences menu unless at least one application is enabled.

Chapter 3Manage Custom Applications

3-6

4Oracle Content and Experience RESTAPIs

REST APIs are available in Oracle Content and Experience for content delivery andfor management of content, conversations, documents, and users and groups.

Oracle Content and Experience has several REST APIs, listed in the following table.

API Name Description

REST API for Activity Log Provides the ability to search activities inOracle Content and Experience.

REST API for Content Delivery Provides access to published assets in OracleContent and Experience. Published assetsinclude content items and digital assets, aswell as their renditions.

REST API for Content Management Provides access to manage assets in OracleContent and Experience. Assets includecontent items and digital assets and theirrenditions.

REST API for Conversations Enables interaction with your cloud resourcesfor real-time collaboration between individualsand teams to connect your businessprocesses, enterprise applications, andcontent.

REST API for Documents Enables you to interact with folders and filesstored in Oracle Content and Experience andto create sites from templates and other sites.

4-1

API Name Description

REST API for Sites Management Provides the ability to create sites fromtemplates and then manage the life cycle ofthose sites in Oracle Content and Experience.This REST API has several categories ofendpoints:

• ComponentsImport, export, list, read, copy, update,publish, share and delete components.

• ThemesImport, list, read, copy, publish, update,share and delete themes.

• TemplatesCreate policies and associate them with atemplate to be used when creating a site.Policies can be used to enforce sitecreation approval, who can use atemplate, and what security the site willhave.

• PoliciesManage policies and manage themembership of policies with access lists.

• RequestsRequests are made when creating a site.A site request is rejected or approvedthrough a review.

• SitesCreate, copy, delete, publish and activatesites. Get site information and associatedresources. List sites and managemembership.

REST API for Users and Groups Enables you to manage users and groups ofusers.

REST API for Webhooks Management Provides the ability to manage webhooks inOracle Content and Experience.

The following topics provide descriptions of how to perform some tasks with RESTAPIs:

• Integrate with Oracle Content and Experience Using OAuth

• Integrate Using OAuth As a Resource Owner

• Download the Swagger File for a REST API

• Upload a REST API Swagger File into Mobile Cloud Service

• Search with the Querytext Parameter

• Set Up Searches on Metadata Fields

• Create and Use Applinks for File and Folder Access

• Provide Access to Files and Folders with Public Links

Chapter 4

4-2

Integrate with Oracle Content and Experience Using OAuthDeveloper access to Oracle Content and Experience REST APIs is protected by CG/WTSS using OAuth clients.

For content management and sites management REST APIs, you acquire the client IDand secret required to get the access token from Oracle Identity Cloud Service (IDCS).For 2-legged OAuth you use client credentials to acquire the client ID and secret. For3-legged OAuth, you use an Authorization code to acquire the client ID and secret.

The information in this section applies only to the following Oracle Content andExperience REST APIs:

• REST API for Content Delivery

• REST API for Content Management

• REST API for Sites Management

In this release, the information in this section does not apply to the following RESTAPIs:

• REST API for Activity Log

• REST API for Conversations

• REST API for Documents

• REST API for Users and Groups

• REST API for Webhooks Management

The OAuth Client approach will be supported for other Oracle Content and ExperienceREST APIs in coming releases.

The following sections describe how to use OAuth clients to access Oracle Contentand Experience REST APIs:

• Access Using 2-Legged OAuth

• Access Using 3-Legged OAuth Flow

Access Using 2-Legged OAuthFor access using 2-legged OAuth, you can use client credentials to acquire the clientID and secret required to get an access token from Oracle Identity Cloud Service(IDCS).

The Identity Domain Administrator or Application Administrator of the tenantcreates an OAuth client for the developer with the required privileges.

The Identity Domain Administrator performs the following steps to get an accesstoken:

1. Create an OAuth Client and Acquire a Client ID and Secret

2. Grant the Required Oracle Content and Experience Roles to the Client

3. Acquire an Access Token from Oracle Identity Cloud Service (IDCS) for theRequired Resource

4. Use the Access Token to Access the Oracle Content and Experience Resource

Chapter 4Integrate with Oracle Content and Experience Using OAuth

4-3

Create an OAuth Client and Acquire a Client ID and SecretDeveloper access to Oracle Content and Experience REST APIs is protected by CG/WTSS using OAuth clients. You can acquire the client ID and secret required to getthe access token from Oracle Identity Clout Service (IDCS).

The Identity Domain Administrator or an Application Administrator of the tenantcreates an OAuth client for the developer with the required privileges. To do this,perform the following steps:

1. Go to the IDCS administration console:

https://<IDCS BaseURL>/ui/v1/adminconsole

2. Click to add a new application in the Applications section.

3. Select Confidential Application.

4. Give the application a name and, optionally, a description, and press Enter.

5. Choose to configure this application as a client.

6. Select the client credentials grant type on the Authorization screen.

7. Scroll down to the Token Issuance Policy section and, under Resources, clickadd scope to give the application access to the required Oracle Content andExperience instance.

8. Click the right arrow to select the scope.The only scope required is the one ending in

urn:opc:cec:all

9. Click Next until the end of the train.The Resources, Web Tier Policy, and Authorization stops are related toapplications that have some resource authenticated or authorized by IDCS; forexample, a web application. This isn’t relevant in the case of a simple server-server client, which is discussed here.

10. Click Finish.

11. Note the Client ID and Client Secret values because you’ll need those to get atoken later.

12. Check Activate and then click Save to enable the application.

You can decide how to handle the client ID and secret.

Grant the Required Oracle Content and Experience Roles to the ClientYou can grant the required roles through the Oracle Identity Cloud Service (IDCS)administration console in the Pool environment or through the CloudPortal endpoint ina production environment.

1. Log in to the IDCS administration console.

2. Click Applications.


4-4

3. Select the Oracle Content and Experience service instance for which you needprivileges. This instance name would have been provided by your accountadministrator.

4. Right-click the burger menu on the right.

5. Choose Assign Applications.

6. Click Application Roles.

7. Click CECRepositoryAdministrator.

8. Repeat the steps 4 through 7 for the roles CECEnterpriseUser andCECContentAdministrator.

9. Save the changes.

Acquire an Access Token from Oracle Identity Cloud Service (IDCS) for theRequired Resource

Use the client ID and secret obtained earlier from the OAuth client to get anAccessToken for the resource.

A sample curl command to acquire an access token follows:

AccessToken Request

curl -X POST \https://<idcs tenantname that is protecting this service>/oauth2/v1/token\-H 'Authorization: Basic <Base64 encoded clientID:clientSecret>'\-H 'Host: <IDCS BaseURL>'\-d 'grant_type=client_credentials&scope=https%3A%2F%<ServiceInstanceBaseURL>%3A443%2Furn%3Aopc%3Acec%3Aall'

IDCS returns the key and value for an access token:

{"access_token":"<access-token-value}"

Copy the access token value.

Use the Access Token to Access the Oracle Content and Experience ResourceOnce the access token is acquired, call the Oracle Content and Experience endpointto access the resource.


4-5

A sample curl command follows.

curl -X GET https://Oracle-Content-and-Experience-URL/sites/management/api/v1/sites \-H 'Authorization: Bearer <Access Token acquired from previous step>'\-H 'Content-Type: application/json'

Access Using 3-Legged OAuth FlowFor access using 3-legged OAuth, you acquire the client ID and secret required to getthe access token from Oracle Identity Cloud Service (IDCS).

This requires that the Identity Domain Administrator or Application Administratorof the tenant creates an OAuth client for the developer with the required privileges.The Identity Domain Administrator performs the following steps to create an OAuthclient.

For 3-legged OAuth, you use an Authorization code grant type.

The Identity Domain Administrator performs the following steps to get an accesstoken:

1. Create an OAuth Client and Acquire a Client ID and Secret

2. Grant the Required Oracle Content and Experience Roles to the Client

3. Acquire an Access Token from Oracle Identity Cloud Service (IDCS) for theRequired Resource

4. Use the Access Token to Access the Oracle Content and Experience Resource

Create an OAuth Client and Acquire a Client ID and SecretDeveloper access to Oracle Content and Experience REST APIs is protected by CG/WTSS using OAuth clients. You can acquire acquire the client ID and secret requiredto get the access token from Oracle Identity Cloud Service (IDCS).

The Identity Domain Administrator or an Application Administrator of the tenantcreates an OAuth client for the developer with the required privileges. To do this,perform the following steps:

1. Go to the IDCS administration console:

https://<IDCS BaseURL>/ui/v1/adminconsole





6. Select the Authorization code grant type on the Authorization screen.

7. Enter a redirect URL value to point to the URL where the user needs to beredirected after authorization.

8. Enter a Post logout URL value to point to the Oracle Content and Experienceservice administration console.


4-6

https://Oracle-Content-and-Experience-URL/sites/management/api/v1/sites

9. Scroll down to the Token Issuance Policy section and, under Resources, clickadd scope to give the application access to the required Oracle Content andExperience instance.

10. Click the right arrow to select the scope.The only scope required is the one ending in

urn:opc:cec:all

11. Click Next until the end of the train.The Resources, Web Tier Policy, and Authorization stops are related toapplications that have some resource authenticated or authorized by IDCS; forexample, a web application. This isn’t relevant in the case of a simple server-server client, which is discussed here.

12. Click Finish.



The client can store the Client ID and Client Secret values securely in a credentialstore.

Grant the Required Oracle Content and Experience Roles to the ClientYou can grant the required roles through the Oracle Identity Cloud Service (IDCS)administration console in the Pool environment or through the CloudPortal endpoint ina production environment.

1. Log in to the IDCS administration console.

2. Click Applications.

3. Select the Oracle Content and Experience service instance for which you needprivileges. This instance name would have been provided by your accountadministrator.

4. Right-click the burger menu on the right.

5. Choose Assign Applications.

6. Click Application Roles.

7. Click CECRepositoryAdministrator.

8. Repeat the steps 5 through 7 for the roles CECEnterpriseUser andCECContentAdministrator.

9. Save the changes.


4-7

Acquire an Access Token from Oracle Identity Cloud Service (IDCS) for theRequired Resource

You can get an access token from IDCS for a resource.

Acquisition of the access token consists of multiple steps:

1. Request the authorization code.Authorization code request:

curl -X GET <IDCS BaseURL>

Note: A nonce value is a cryptographically strong random string that you use to prevent intercepted responses from being reused.

2. Provide log-in credentials to IDCS. If you are not already logged in, IDCS willchallenge you to authenticate. IDCS checks your credentials.

3. Acquire an authorization code.If the login is successful, IDCS redirects the browser to the client application withan authorization code.

If you do not authenticate, an error is returned rather than the authorization code.

4. Use the authorization code to acquire an access token.Access token request:

curl -i-H 'Authorization: Basic <base64-clientid-secret'-H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8'--request POST https://<IDCS-service-instance>/oauth2/v1/token\-d 'grant_type=authorization_code&code=<authz-code>&redirect_uri=<client-redirect-uri as specified in the configuration at the client creation time>

IDCS returns the key and value for an access token:

{"access_token":"<access-token-value"}

Copy the access token value.

Use the Access Token to Access the Oracle Content and Experience ResourceOnce the access token is acquired, call the Oracle Content and Experience endpointto access the resource.

A sample curl command follows.

curl -X GET https://Oracle-Content-and-Experience-URL/sites/management/api/v1/sites \-H 'Authorization: Bearer <Access Token acquired from previous step>'\-H 'Content-Type: application/json'


4-8


Integrate Using OAuth As a Resource OwnerA Resource Owner can generate OAuth tokens for other users. You can use IdentityCloud Service (IDCS) to configure a confidential application to authorize a ResourceOwner grant for requesting tokens.

To configure a confidential application to authorize a Resource Owner grant:

1. Go to the IDCS admin console: https://<IDCS BaseURL>/ui/v1/adminconsole





6. Select the Resource Owner grant type on the Authorization screen.

7. Scroll down to the Token Issuance Policy section and, under Resources, clickAdd Scope to give the application access to the Oracle Content and Experienceinstance required.

8. Select the correct instance.

9. Click the right arrow to select the scope. The one ending in urn:opc:cec:all isthe only scope required.

10. Click Next until the end of the train. The Resources, Web Tier Policy, andAuthorization stops are related to applications that have some resourceauthenticated or authorized by IDCS; for example, a web application. In the caseof a simple server-server client, which is discussed here, this isn’t relevant.

11. Click Finish.



To request a token:

1. Make a form post to <IDCS BaseURL>/oauth2/v1/token.

2. Authentication is HTTP basic, where the user name is the client ID and thepassword is the client secret. The HTTP authorization header must specify Basicauthentication.

3. The following table describes the fields.

Field Value

grant_type password

scope A scope you added previously, in step 9; forexample: https://1DF8AB52D0FF48F6992EEA3A5715B66F.cec.dev.ocp.octest. com:443/urn:opc:cec:all

username The user name to generate the token for.

Chapter 4Integrate Using OAuth As a Resource Owner

4-9

Field Value

password The password for the user name in thepreceding field.

POST /oauth2/v1/token HTTP/1.1Host: <idcs-host>Authorization: BasicNTZkZWJjY2EzYjc0NDRlMWFhNjg4OGQ0ZTYzY2Y1M2Y6NDYxYzM5YjctMzJiZC00NGE0LTk4NTctNWM1NzAyMWMzNDg4Accept: */*Content-Type: application/x-www-form-urlencodedContent-Length: 162grant_type=password&scope=https%3A%2F%2F1DF8AB52D0FF48F6992EEA3A5715B66F.cec.dev.ocp.octest.com%3A443%2Furn%3Aopc%3Acec%3Aall&username=<user-name>&password=<password>

This results in JSON text where the token is the value of the access_token field:

{"access_token":"eyJ4NXQjUzI1NiI6IkhoRktIMFFGeHR1UDkxLWg3QlJKSUFDMU50V2R...HUQmto_oELyjRaBpqhI75hQJYLWRKm6ozPS57tR1EYHmWABgYw_XALMT1kMuIuRxpGB2ozngpajzNNBBu2qtKg10-RzBTulKaxD25vKK1rznQ3p_XAOLK4CUUM-uG_PUOk49-JDgJjuSI74hLC1kagIlM93A2jUG3g3gdUpUCZPg","token_type": "Bearer","expires_in": 604800}

The token expiration time is given in seconds, and is typically 7 days.

4. To use the token and access REST API endpoints, use the Bearer Authorizationheader; for example:

curl -i -H 'Authorization: Bearer token' --request GET


Authorization header format is Basic [Base64[client_id:client_secret]]. Theaccess token value needs to be a base64 UTF-8 encoded value of the client IDand client secret concatenated using a colon as a separator; for example,clientID:clientSecret.

REST API for Activity LogThe Oracle Cloud REST API for Activity Log provides the ability to search activities inOracle Content and Experience.

Chapter 4REST API for Activity Log

4-10

https://docs.oracle.com/en/cloud/paas/content-cloud/rest-api-activity-log/index.html

The REST API for Activity Log has the categories of endpoints listed in the followingtable.

Category Description

Audit Log Provides the details of activities and its related data.

Events Provides the details of types and categories.

Oracle Content and Experience also provides the following REST APIs:








REST API for Content DeliveryYou can use the Oracle Cloud REST API for Content Delivery to fetch things fromchannels in an asset repository.

The REST API for Content Delivery has several categories of endpoints, which thefollowing table describes.


Item Use the Item resource to get published items, previews of items, oritem metadata.

Item Variations Use the Item Variations resource to get item variations, a content itemfor an item variations, and item variations by variation type.

Items Use the Items resource to search published items or get the metadatacatalog of published items.

Items by Slug Use the Items by Slug resource to manage items by slug and providedetails about the metadata catalog, preview, taxonomies, publishinformation, and variations of an item.

Recommendations Use the Recommendations resource to access publishedrecommendation results.

Renditions Use the Renditions resource to get digital assets, published renditionsof digital assets, metadata for digital assets or renditions, orinformation about published assets or renditions.

Taxonomies Use the Taxonomies Resource to list all taxonomies, read a categoryor a taxonomy, or search published categories.

Version Catalog Use the Version Catalog resource to get information about APIs, APIversions, or API metadata.




Chapter 4REST API for Content Delivery

4-11

https://docs.oracle.com/en/cloud/paas/content-cloud/rest-api-content-delivery/index.html

https://docs.oracle.com/en/cloud/paas/content-cloud/rest-api-manage-content/index.html

http://www.oracle.com/pls/topic/lookup?ctx=cloud&id=cec-rest-api-conversations

https://docs.oracle.com/en/cloud/paas/content-cloud/rest-api-documents/index.html

https://docs.oracle.com/en/cloud/paas/content-cloud/rest-api-sites-management/index.html

http://www.oracle.com/pls/topic/lookup?ctx=cloud&id=cec-rest-api-users-groups

https://docs.oracle.com/en/cloud/paas/content-cloud/rest-api-webhooks-management/index.html









REST API for Content ManagementYou can use the Oracle Cloud REST API for Content Management to manage assetsin Oracle Content and Experience. Assets include content items as well as digitalassets and their renditions.

The REST API for Content Management has several categories of endpoints, whichthe following table describes.


Channel Secret Use the Channel Secret resource to generate, refresh, or delete achannel secret.

Channels Use the Channels resource to create, delete, read, or update achannel, to list all channels, or to list all permissions on a channel.

Collections Use the Collections resource to create, delete, read, or update acollection, to list all collections in a repository, or to list all permissionon a collection.

Connectors Use the Channel Secret resource to generate, refresh, or delete achannel secret.

Digital ItemRenditions

Use the Digital Item Renditions resource to get a digital item native filewith or without a file name or a rendition of a digital item with or withouta file name.

Item Variations Use the Item Variations resource to list all item variations of a variationtype, read an item variation of a variation type value, read itemvariations by variation type, or update the master item of an itemvariations set.

Items Use the Items resource to create, delete, read, or update an item; toread publish information for an item; to list all time zones; or to listchannels, collections, published channels, relationships, tags,variations, or all taxonomies and categories of an item.

Items BulkOperations

Use the Items Bulk Operations resource to perform bulk itemsoperations, \read items bulk operations status, or read items bulkoperations publish item IDs.

Items by Slug Use the Items by Slug resource to manage items by slug. Providedetails of item variations of a variation type, collections of a given item,publish information for a given item, relationships, tags, taxonomies,variations, and version information for a given item.

Items Search Use the Items Search resource to manage items search queries.

Languages Use the Languages resource to list the names of all known languagecodes.

Localization Policies Use the Localization Policies resource to create, delete, read, orupdate a localization policy or to list all localization policies.

Chapter 4REST API for Content Management

4-12








ManagementTaxonomies

With the Management Taxonomies resource, you can take thefollowing actions to manage your content:

• Create, update, or delete a taxonomy• Get, create, update, copy, or delete a category in a taxonomy• Create, copy, update, promote, read, publish, unpublish, or delete

a taxonomy• List all taxonomies or list all categories in a taxonomy• Read copy category, draft creation, promote, publish, or unpublish

job status• Update a category's properties, including moving it in the treeAfter taxonomies are promoted, they can be assigned to repositories.After taxonomies are assigned to repositories, users can applycategories to assets.

OAuth Tokens Use the OAuth Tokens resource to generate an OAuth token.

PermissionOperations

Use the Permission Operations resource to perform permissionoperations on a resource or to read permission operations status.

Recommendations Use the Recommendations resource to manage recommendations:• Create, delete, list, update, read, and publish recommendations• Read a recommendation's published and unpublished item IDs• Approve or reject a Recommendation• Create, delete, list, read, and update audience attributes

Repositories Use the Repositories resource to create, delete, read, or update arepository, to list all permissions on a repository, or to list allrepositories.

Tokens Use the Tokens resource to read a a Cross-Site Request Forgery(CSRF) valid token.

Types Use the Types resource to create, delete, read, or update a type or tolist all types, all data types, or all permissions on a type.









REST API for ConversationsYou can use the Oracle Cloud REST API for Conversations to create and manageconversations in your cloud resources that enable real-time collaboration betweenindividuals and teams and connect your business processes, enterprise applications,and content.

The REST API for Conversations uses the JSON data format and relies on a REST-based architectural style that provides a convenient and consistent approach to

Chapter 4REST API for Conversations

4-13









requesting and modifying data. The client specifies an action using an HTTP verb suchas POST, GET, PUT, or DELETE. It specifies a resource using a unique URL in thisformat:

https://oracleContentInstance-identityName.network.dataCenter.oraclecloud.com/osn/social/api/v1/resource-path

In the URL:

• oracleContentInstance is the name you chose for your Oracle Content andExperience Cloud instance when it was provisioned.

• identityName is the identity name you chose when you signed up with OraclePublic Cloud.

• network is the name of your network.

• dataCenter is the data center that Oracle Content and Experience Cloud is set upto use.

• resource-path is the relative path that defines the resource.

The following topics provide overview information about developing with the REST APIfor Conversations:

• REST API Features for Conversations

• Collaboration Resource

• Configuration Resource for Conversations

• Security Resource

• Social Resource









REST API Features for ConversationsFeatures of the REST API for Conversations help you develop custom integrationswith conversation objects in Oracle Content and Experience.

• API Security

• API Versioning

• Case Sensitivity

• HTTP Methods


4-14








• Optional Fields and Default Values for JSON Data Representations

• Return Values

• Name Patterns

• URL Encoding

• Pagination

• Filters

• Sort Order

• Localization

• Name Field Length Limit

• HTTP Status Codes and Error Handling

API SecurityAll API invocations happen in the security context of the signed-in user.

Agent users can do actions on the system, either independently or on behalf of aparticular user. In specific situations you might need to use one of the followingproperties. Among agent user techniques, as a best practice you should useImpersonate. Use On Behalf Of or Bypass only on the advice of Oracle support or theOracle integration team.

• Impersonate (in XV1ConnectionUpdateInfo)

During the connection to the server, the impersonation sign in is recorded. Theserver also tracks when the impersonation ends. The audit log tracks the actionsas being done by the user being impersonated; it does not track the impersonatingagent for each action.

The permissions for actions are based on the permission level of the user beingimpersonated.Impersonate is intended for use only in automated processes, suchas for conversation object updates where you want to show that the update wasmade by a particular user. Keep in mind that using Impersonate can degradeanalytics accuracy because it associates actions with the impersonated user.

• On Behalf Of (in XV1ConnectionUpdateInfo) - Allows a user to do a limitednumber of end-user functions on behalf of another user, such as posting amessage to a Conversation or uploading a document. When this privilege is used,the audit log indicates both the user who performed the action and the user onwhose behalf it was performed; in clients, the action is labeled as having beenperformed by the user the action was performed for.

• Bypass (in XV1SocialObjectRole, XV1ConversationRole, andXV1SocialObjectRole) - Allows the user to do any action without failing due toinadequate permissions (although a request might fail for another reason, such asnot being a member of the Conversation being acted on). The Bypass privilege isintended for use only in certain automated processes in a highly secureenvironment.

API VersioningThe current version of the REST API for Conversations is v1. API versions are not tiedto releases of Oracle Content and Experience.


4-15

The version number is placed in the URL directly following /social/api. For example:

https://<host>[:<port>]/osn/social/api/v1

A GET request to the API endpoint returns a list of the top-level URIs that the serversupports. For example, this request:

https://<host>[:<port>]/osn/social/api/

Returns a list of supported versions, including the

VCurrent

identifier, which identifies the most recent release of the server API. The currentrelease is "V1". The result follows:

{"V1" : "https://osn/api/v1",}

Case SensitivityCase is important throughout the REST API because URLs, methods, names, andobject IDs are all case sensitive.

Case is significant in the REST API URLs.

HTTP MethodsThe REST API for Conversations supports standard HTTP methods (verbs).

Method Description

GET Retrieve or query resources.

If you send a GET request for a specific field's value but that field doesnot exist, the API returns the field that you passed, with a null valueand a status of 200.

POST Create a new instance of a resource, such as a conversation.

In addition, you can use POST to create a relationship between twoobjects. For example, you can use POST to create a Like (Starred)relationship between a user and a conversation.

PUT Update the state of an existing instance of a resource.

For example, you can use PUT to change the state of a conversationfrom Open to Closed. PUT requests use the XUpdater class.

DELETE Delete an existing instance of a resource or delete a relationshipbetween two objects.

Subset of HTTP Methods Supported by Client

If the client supports only a subset of these HTTP methods, you can tunnel the othermethods using the POST method by specifying the desired method in the method


4-16

query parameter. For example, the DELETE operation can be achieved by doing aPOST on a resource with "method=delete" in the query string portion of the URL.

PUT Requests with XUpdater

When updating an object using a PUT request, such as with XConversationUpdater,you can use XUpdater to specify the value that you want to change. XUpdater is aclass that represents the DTO for updating objects; the updater field actuallyrepresents a map of field values. For example, XUpdater can be reresented as follows:

{"updater": "XUpdater"}

For example, you can use a PUT request to . . ./social/api/v1/conversations/ObjectID with the request payload {"updater":{"SHORT_NAME":"String for shortname"}} to change the short name.

XUpdater is used with Collections, Conversations, Groups, People, and Collaborationobjects.

Optional Fields and Default Values for JSON Data RepresentationsThe API reference documentation uses the term optional in describing JSON datarepresentation fields.

Optional has a slightly different meaning depending on the data type:

• String: default is null if not specified.

• int: default is zero (0) if not specified.

• boolean: default is false if not specified.

Return ValuesYou can control the response payload's content type by specifying the JSON or HTMLMIME type in the "Accept" HTTP header.

The content type defaults to 'application/json'. Examples are presented in JSON.

You can specify the value 'text/html' to get an HTML version of the JSON that isreturned.

Name PatternsAll external class names begin with the letter X, followed by the version number,followed by a noun (for example, Conversation, Message, or People), followed by oneor more modifiers, depending on the function of the class.

The following table describes the class name conventions and the associatedfunctions, using the Conversation resource type as an example.

XV1Conversation. . . Action

Info Get information about a Conversation (GET).


4-17

XV1Conversation. . . Action

CreateInfo Create a Conversation and set properties (POST).

FilterInfo Get Conversations that meet the filter criteria (GET).

MemberCreateInfo Add a member to a Conversation and set properties (POST).

MemberInfo Get information about a member of a Conversation (GET).

MessageCreateInfo Add a message in a Conversation (POST).

PropertyCreateInfo Set properties for a Conversation (POST).

PropertyInfo Get a property for an existing Conversation (GET).

PropertyUpdateInfo Set a property for a Conversation (PUT).

UpdateInfo Update attributes for a Conversation (PUT).

ListInfo Get a list of all Conversations (GET).

MemberListInfo Get a list of all direct members of the Conversation (GET).

PropertyListInfo Get a list of all properties for the Conversation (GET) .

StarListInfo Get a list of starred Conversations and their messages (GET) .

XObjectID

Each object in the REST API for Conversations has a unique ID. From that ID, you canload the object, if you have sufficient permissions. Many data transfer objects (DTOs)specify IDs of other objects related to the current object. Some examples includeParentID, ModifiedByUserID, CreatedByUserID, and ConversationID. These are alllinks or references to other objects in the system.

Note that the ID parameter represents a name for fields, an ObjectID or an External IDfor Conversation objects, and an Object ID or sign in name for users.

URL EncodingFor readability, examples might be shown in literal text, but your requests shouldalways be URL-encoded (percent-encoded).

For example:

/conversations?filter={"LimitToStarred":true,"ExcludeMuted":true}

This example should be URL-encoded as follows:

/conversations?filter=%7B%22LimitToStarred%22%3Atrue%2C%22ExcludeMuted%22%3Atrue%7D

PaginationPagination capabilities are supported by default on all GET operations that have aresponse payload of XV1*ListInfo (for example, XV1ConversationListInfo), unlessotherwise specified.


4-18

You can use offset and count in the query argument, where the default values are 0and 20 respectively. For example:

https://<host:[<port>]/osn/social/api/conversations/<conversationID>/messages?offset=0&count=25

This request gets the first 25 messages, returning them with the newest message first.You can send additional requests to get incrementally older posts in the Conversation.

FiltersFilter capabilities are supported where specified.

To use a filter, specify the filter query argument in JSON format, using URL encodingas appropriate. For example, this request returns starred Conversations but no mutedConversations:

/conversations?filter={"LimitToStarred":true,"ExcludeMuted":true}

Sort OrderThe currently assigned sort order determines the order in which results are returned.

You can change the sort order using the SortField field, which is available inXV1ConversationFilterInfo, XV1SocialObjectFilterInfo, and others. For example, thisrequest returns results sorted by Conversation age, with the newest Conversation first:

/conversations?filter={"LimitToStarred":true,"ExcludeMuted":true,"SortField":CONVERSATION_IS_NEW}

LocalizationThis background information about localization might be useful as you areimplementing or troubleshooting an Oracle Content and Experience integration.

Some of the concepts described in this section go beyond the REST API.

Localization is performed according to the following steps:

1. Choose a language locale.

a. If an HTTP request exists and has an X-Waggle-ForceLanguage header, thenuse the X-Waggle-ForceLanguage header value as the language locale andgo to step 2.

b. If a particular user is signed in or otherwise identified, check to see if the userhas set a preferred language locale in their user profile. If set, use it and go toStep 2.

A language locale from LDAP will be copied to the user profile in OracleContent and Experience. If the LDAP realm has sync-on-authenticationenabled, then for each sign in, the LDAP values will overwrite the user profilesettings. However, if the user changes the value in their Oracle Content and


4-19

Experience profile, it is not written back to LDAP; Oracle Content andExperience does not write any attributes to LDAP.

If the LDAP Preferred Language is not supported in Oracle Content andExperience (for example, ar), English is displayed regardless of theapplication default language setting.

c. If an HTTP request exists and has an Accept-Language header, use theAccept-Language header to select the language locale.

Using the Accept-Language header, perform a lookup as described inRFC-4647 section 3.4. This will result in a language locale being chosenbased on an exact or partial match of the header, the available translationbundles, and the bundle of last resort.

d. If the server has a language locale set, use it.

e. Select the host machine default language locale.

2. Choose a translation bundle with the exact or longest possible partial match of thechosen language locale. If no exact or partial match exists, then choose thebundle for English.

Supported Locale Codes

The currently supported locale codes are:

cs (Czech)da (Danish)de (German)en (English)es (Spanish))fi (Finnish)fr (French)fr-CA (French-Canadian)hu (Hungarian)it (Italian)ja (Japanese)ko (Korean)nl (Dutch)no (Norwegian)pl (Polish)pt-br or pt_BR (Portuguese-Brazilian)ro (Romanian)ru (Russian)sv (Swedish)tr (Turkish)zh-CN or zh_CN (Chinese-Simplified)zh-TW or zh_TW (Chinese-Traditional)

Name Field Length LimitThe Name field for objects, such as Conversation names or User names, has a lengthlimit of 256 characters.


4-20

HTTP Status Codes and Error HandlingHTTP status codes for the Collaboration REST API follow.

Status Code Description

200 Request Successful.

4xx Bad requests. Invalid URI, invalid body format.

401 Unauthorized. Should sign in or get a security token.

403 Forbidden. Access denied.

5xx Internal server error.

For all responses, the status code is also available in the actual payload in theStatusCode field. For all non-HTTP Status 200 responses, a message explaining thecause of the error is available in the return value. For example:

{"StatusCode" : "401","StatusCode" : "Unauthorized","ResourceID" : "waggle.modules.realm.InvalidLogin","ResourceMessage" : "Login required."}

Exception Response Fields

Field Description

statusCode The HTTP status code.

statusMessage The HTTP status message.

exceptionID The exception ID.

exceptionClass The exception class.

exceptionMessage The exception message.

exceptionDate The exception date.

Collaboration ResourceUse the Collaboration resource API endpoints to interact with your cloud resourcesthat enable real-time collaboration between individuals and teams and connect yourbusiness processes, enterprise applications, and content.

With the Collaboration resource, you can manage these objects:

• Conversations

• Members of conversations (direct and indirect)

• Documents associated with conversations

• Messages and replies to messages in conversations

• Followups on messages for users

• Applinks and hybrid links for conversations

• Inbound mail tokens


4-21

• Properties and user properties of conversations

• Likes for conversations and messages

• Stars for conversations and messages

Also, you can list folder IDs that have associated conversations.

For endpoint descriptions and examples, see "Collaboration" in REST API forConversations.

Configuration Resource for ConversationsUse the Configuration resource API endpoints to configure resources and services.

With the Configuration resource, you can manage these configuration properties:

• hasMore

• items

• nextURL

• previousURL

• total (number of available items)

For endpoint descriptions and examples, see "Configuration" in REST API forConversations.

Security ResourceUse the Security resource API endpoints to manage connections and access.

With the Security resource, you can manage connections for users and conversations.

For endpoint descriptions and examples, see "Security" in REST API forConversations.

Social ResourceUse the API endpoints of the Social resource to help users mark favoriteconversations and documents and collaborate with each other.

With the Social resource, you can manage followups and stars for users.

To manage collaboration for other users, you need to have a dedicated "IntegrationUser" role. See Functionality Provided Through User Roles in Administering OracleContent and Experience.

For endpoint descriptions and examples, see "Social" in REST API for Conversations.

REST API for DocumentsYou can use the Oracle Cloud REST API for Documents to create client applicationsthat interact with folders and files stored on an Oracle Content and Experience server.

The following topics provide overview information about developing with the REST APIfor Documents:

Chapter 4REST API for Documents

4-22










• Version History

• REST API Features for Documents

• Applinks Resource

• Catalog Resource

• Collections Resource

• Configuration Resource for Documents

• Files Resource

• Folders Resource

• Metadata Collection Resource

• Publiclinks Resource

• Shares Resource

• Sites Resource

• Templates Resource

• Users Resource









Version HistoryThe REST API for Documents identifies its version by including a version number inthe URI in the form of /x.y/ folders, such as /1.2/.

To use a particular implementation of the API, you must reference that version in theURI. For more information about referencing a particular version of the API, see Service Call URI and Version.

Version 1.0

Version 1.0 provides basic folder, file, resource, and version identification services andtheir methods.

Version 1.1

Version 1.1 adds the following major services and their methods:

• Metadata Collection Resource

A metadata collection is a simple way of managing custom metadata fields thatyou can then use to store and retrieve metadata values for individual folders andfiles.


4-23








• Users Resource

Service requests and responses that referenced the simple user string in version1.0 now reference the user object.

These search requests were added:

– User email search

– Fulltext search for a folder in the user’s home directory

– Fulltext search for a file in the user’s home directory

• Applinks Resource

• Publiclinks Resource

• Shares Resource

• Collections Resource

The Files Resource service includes these additional calls:

• Reserve File (POST)

• Unreserve File (POST)

• Get File Thumbnail (GET)

• Get File Rendition Page Count (GET)

• Generate File Renditions (POST)

• Get File Page Rendition (GET)

The Files Resource also supports additional mimeType, reservedBy, andreservationTime elements.

Requests were added to the Metadata Collection Resource for these tasks:

• Enable or disable a metadata collection

• Enable or disable fields in a metadata collection

• Get a metadata collection definition

• Get user metadata

• Get share metadata

• Get application links metadata

• Get public links metadata

• Get assigned metadata collections to a file showing enabled or disabled fieldstatus

• Get assigned metadata collections to a folder showing enabled or disabled fieldstatus

• Delete a metadata collection

The Folders Resource includes additional createdby and modifiedby elements inresponses.

The Applinks Resource supports an additional userLocale element.

The Upload File Version (POST) method no longer requires the use of parentID inthe multipart request.


4-24

An errorKey field was added to responses.

The catalog category was renamed metadata-catalog. The catalog name willcontinue to be supported as an alias for metadata-catalog.

Version 1.1 of the REST API for Content Management provides a Web ApplicationDefinition Language (WADL) definition file. Oracle JDeveloper uses this file tointerface with the API.

The REST API for Content Management 1.1 is the legacy version of the REST API forDocuments.

Version 1.2

Version 1.2 includes all the functionality of Version 1.1 and adds the following majorservices and their methods:

• Sites Resource, for creating a site from an existing site.

• Templates Resource, for creating a site from a template.

The REST API for Documents, Version 1.2, is the ongoing version of the REST API forDocuments.

REST API Features for DocumentsFeatures of the REST API for Documents apply to all services.

The following topics describe these common features:

• REST Overview

• Service Call URI and Version

• Service Request

• Service Response

• Security

• Sort Order

• Pagination

• Links Identification

• HTTP Methods

• HTTP Status Codes

• Error Codes

REST OverviewREST, or Representational State Transfer, uses basic methods such as GET, POST,PUT, and DELETE over a standard protocol, such as HTTPS, to submit requests froma client application to operate on objects stored on a server.

A request is in the form of a uniform resource identifier (URI) that identifies theresource, such as a file or folder, on which to operate and includes any parametersnecessary for the operation. The resource itself is represented by a globally uniqueidentifier (GUID).


4-25


Each request from the client to a server contains all of the information necessary tounderstand the request and does not rely on the server to store information about theindividual request or about any relationship between requests. Session state is stored(cached) entirely on the client.

You can use the REST API for Documents to create client applications to interact withfolders and files stored on an Oracle Content and Experience server.

For information about the hierarchy of the REST API objects and methods, see RESTAPI for Documents.

Service Call URI and VersionA service call includes an HTTPS method, such as POST, GET, PUT, or DELETE,and a resource identified by a Uniform Resource Identifier (URI).

The URI is in this format:

https://{host}[:port]/serviceid/api/version/resourcePath

Note:

HTTPS is supported. HTTP is not supported.

The REST API identifies its version by including a version number in the URI in theform of /x.y/ folders, where x is incremented for subtractive changes or modificationsto existing functionality and y is incremented when new features are added. Forexample:

https://www.example.com/documents/api/1.1

The Catalog Resource lists the currently supported API versions for the instance.

Service RequestA REST API supports a direct URL and JSON data format for service requests.

REST API for Documents includes examples of service requests.

URL Parameters

Unless otherwise noted, you can include service request parameters directly in theURL. The following example of the Query User (GET) service call includes therequired info parameter in the URL itself:

https://www.example.com/documents/api/1.1/users/items?info=smith

JSON Parameters

Unless otherwise noted, you can submit service request parameters in JSON format.The following example shows a simple service call and the info parameter in a JSON-formatted request:

https://www.example.com/documents/api/1.1/users/items


4-26




{ "info": "smith"}

Multipart Requests

Some service calls require a multipart request. For these types of requests, you mustinclude the parameters in a JSON-formatted request. For an example of a multipartrequest, see the Examples tab of "Upload File Version" under "Files" in REST API forDocuments.

Header Parameters

Some types of information, such as authentication information, are passed in therequest header rather than in the body of the request. This is also true for servicerequests that use an application link (applink). An applink grants access to a particularfile or folder resource for a particular user. The applink enables you toprogrammatically carry out other operations on that resource on behalf of theassociated user for a period of time. A service call that uses an applink includes theapplink identifier and its access token in the header.

For an example, see the applink header parameters on the Examples tab of "RefreshApplink Token" under "Applinks" in REST API for Documents.

For more information about applinks, see Applinks Resource.

Service ResponseThe REST API supports the JSON and XML data formats for service responses.

The Download File (GET) service call returns the contents of a specified file.

You can specify the data format for the response using the Accept HTTP header. Ifyou don't specify a data format, JSON is used by default for the response. Forexample:

Accept: application/xml

The service response includes a general status code and, in some cases, a faultresponse body to help diagnose the issue. This information is returned in the specifiedJSON or XML format.

Requests that do not reach a valid API endpoint, such as improperly formed requests,may return a response in a format other than JSON or XML. These types of errorstypically occur during code development, not with properly tested and deployedapplications.

Examples of service responses are included with the API descriptions in REST API forDocuments.

SecurityOracle Content and Experience uses a multilayered approach to protect your systemand content.


4-27






Security Feature Description Who Manages It and Where

User accounts You need an account with a username and password to accessOracle Content and Experience.

Identity domain administratorsmanage user accounts in theInfrastructure Classic Console.

User roles Each user is assigned one ormore roles to control whatfunctionality and areas of the webuser interface they can access.

Identity domain administrators orservice administrators assign userroles in the Infrastructure ClassicConsole.

Groups Groups make it easy to grantmultiple users access to folders,conversations, and content types.By adding someone to a group orremoving them from a group, youcan quickly update thepermissions to all the items thatgroup has access to.

Service administrators shouldcreate high-level organizationalgroups. Users can createadditional groups as necessary.

Mobile devicepasscodes

When accessing files on a mobiledevice, you can set a passcode toprovide additional security. Thepasscode is a four-digit numberthat is set and managed on yourdevice. It's used in addition to youruser name and password.

Users manage their passcodes ontheir mobile devices.

Revoke authorizationfor a mobile device

If a user loses their device or it’staken, they should remove thatdevice's authorization to accessthe service. The next timesomeone tries to activate the appon the device, the account issigned out and all local contentstored on the device for thataccount is deleted.

Users can revoke a device fromthe web client.


4-28


Single Sign-On (SSO) If Federated Single Sign-On(SSO) is currently available foryour Oracle Content andExperience Cloud environment,you can enable it to customizesign-in procedures. When SingleSign-On (SSO) is enabled, userscan sign in to one domain usingcorporate security credentials andaccess another domain withoutsigning in again. For example,perhaps you are an administratorfor your company which has twoOracle Cloud Services and youmust provision these services toyour company’s organization,roles, and users. Your companymay also have on-premiseapplications and cloud servicesfrom other vendors. It’s importantthat communication betweenthese services and applications isdone in a secure fashion. WithSSO, users can sign in to all ofthem using the same set ofcredentials that are managed byusing your identity domain system.

Account administrators can enablesingle sign-on (SSO) in theInfrastructure Classic Console.

File encryption Files are protected using SecureSockets Layer (SSL) technology.Files are encrypted while they'reuploaded (in transit) and whenthey’re stored (at rest) in thecloud. Files at rest that are storedusing the Oracle Storage Cloudservice are encrypted using a256–bit RSA encryption algorithm.That prevents unauthorized use ofthe files.Any files downloaded to a mobiledevice are also encrypted. Youcan't access those files outside ofthe Oracle Content andExperience app unless youspecifically download the file foruse on the device.

File encryption is handledautomatically by Oracle Contentand Experience.

File type and sizerestrictions

You can specify which types offiles can be uploaded and restrictthe size of uploaded files.

Service administrators configurefile type and size restrictionsthrough the Oracle Content andExperience Administrationinterface.

Virus scanning When you upload files to thecloud, they can be checked by avirus scanner. Any files found tobe infected are quarantined in theTrash bin and a special iconmarks the file as infected.

Service administrators configurevirus scan settings through theOracle Content and ExperienceAdministration interface.


4-29


File access control You have total control over whocan access your files. You canadd co-workers as members of afolder. The added users aregranted default access rights, butfolder managers can also changethose rights.In addition to sharing folders, youcan also share files using links. Ifyou send a link to a member of afolder, the member can sign in anduse the file in the service. If yousend the link to a non-member,that person is restricted fromseeing other files in the folder.

Service administrators set thedefault role for new foldermembers and set default linkbehavior.

Users control access when they share content.

Conversationencryption

Conversations at rest are storedusing the Oracle Storage Cloudservice and are encrypted using a256–bit RSA encryption algorithm.That prevents unauthorizedaccess to conversation content.

Conversation encryption ishandled automatically by OracleContent and Experience.

Site creation andsharing restrictions

You can specify who can create,share, and use sites functionality,which lets users design, build,publish, and manage websites thatare hosted in Oracle Cloud.

Service administrators configuresites settings through the OracleContent and ExperienceAdministration interface.

Site security When you publish a site and makeit available online, it’s publiclyavailable to anyone. However, youcan change the security settingsfor the site to require users to signin. You can also require that usershave a specific role assigned tothem.

Site owners and managers controlthe security for individual sites.

Site sharing With site sharing, you specifyindividual users who can accessyour unpublished (offline) site andallow them to view, modify, ormanage the site based on thepermission you give them.

Site owners and managers controlthe security for individual sites.

Site componentsharing

Some components provide accessto shared resources such asfolders, files, or conversations.Component sharing considersboth site security (who can viewthe published site) and resourcesharing (who can view and workwith folders, files, andconversations).

Site component sharing is handledautomatically by Oracle Contentand Experience based on site andresource security.


4-30


Cross-OriginResource Sharing(CORS)

Cross-Origin Resource Sharing(CORS) allows a web page tomake requests such asXMLLHttpRequest to anotherdomain. If you have a browserapplication that integrates withOracle Content and ExperienceCloud but is hosted in a differentdomain, add the browserapplication domain to OracleContent and Experience Cloud’sCORS origins list.

Service administrators configureCORS through the Oracle Contentand Experience Administrationinterface.

Proxy service Oracle Content and ExperienceCloud includes a proxy service, sothat you can use REST serviceswhich have Cross-OriginResource Sharing (CORS)limitations or require serviceaccount credentials. The proxyservice is a reverse proxy server.It provides a URL to which webbrowsers connect. The proxyservice then acts as anintermediary between the webbrowser and a remote RESTservice (or endpoint). The proxyservice explicitly adds CORSsupport to all endpoints and canoptionally insert service accountcredentials to requests comingfrom web browsers.

Service administrators configurethe proxy service through theOracle Content and ExperienceAdministration Integrationsinterface.

Embedded contentwhitelist

You can display content fromOracle Content and Experiencewithin other domains. Forexample, you might embed theOracle Content and Experienceweb user interface into your ownweb applications to access folderand document managementfeatures inside your application.The embedded content appearsonly if embedded content isenabled and the domain is addedto allowed domains whitelist.

Service administrators configureembedded content settingsthrough the Oracle Content andExperience Administrationinterface.

Sort OrderFor services that return items in a folder, you can use the orderby parameter to orderthe results based on a specified field name and sort order (ascending or descending).

For an example of the orderby parameter in use, see Examples in the description of"Get Home Folder Contents" under "Folders" in REST API for Documents.


4-31


PaginationPagination capabilities are supported by default on all GET operations that have aresponse payload of XV1*ListInfo (for example, XV1ConversationListInfo), unlessotherwise specified.

You can use offset and count in the query argument, where the default values are 0and 20 respectively. For example:

https://<host:[<port>]/osn/social/api/conversations/<conversationID>/messages?offset=0&count=25

This request gets the first 25 messages, returning them with the newest message first.You can send additional requests to get incrementally older posts in the Conversation.

Links IdentificationAll service calls support the links=yes parameter, which returns link data thatidentifies the call itself and its relationship to other services.

The links parameter provides compliance with the HATEOAS (HTML as the Engineof Application State) standard, which uses valid HTML links returned by the server toidentify the current resource and to navigate from one resource to another.

Relationships

A service call typically returns a number of links, each with a relationship type thatidentifies how the link is related to the associated call. The following table describesthe most common relationship types.

Link Type Description

Self Identifies the current service call.

Canonical Identifies the preferred version of a resource call.

Child For hierarchical resources, such as folders, this link identifies the callto access the child item or items of the resource identified in thecurrent service call.

Parent For hierarchical resources, such as folders, this link identifies the callto access the parent item of the resource identified in the currentservice call.

Prev For service calls that include multiple pages of response data, this linkidentifies the call to access the previous page.

Next For service calls that include multiple pages of response data, this linkidentifies the call to access the next page.

The link information returned for resource metadata includes other types ofrelationships, including ones that identify the type of service, such as copy, for each ofthe services supported for the resource. For more information, see MetadataCollection Resource.


4-32

Example

This example shows the links portion (only) for the home folder in the response to thefollowing service call:

GET https://www.example.com/documents/api/1.1/folders/self/items?links=yes&limit=2&offset=1

The call requests a list of all the items in the home folder. Note that the call includesthe links parameter and pagination parameters to help illustrate the available linkrelationships. Also note that, because the folder is the home folder, there is no link torepresent the parent folder in the response.

"links": [ { "rel": "self", "href": "https://www.example.com/documents/api/1.1/folders/self/items?links=yes&limit=2&offset=1" }, { "rel": "canonical", "href": "https://www.example.com/documents/api/1.1/folders/self" }, { "rel": "children", "href": "https://www.example.com/documents/api/1.1/folders/self/items" }, { "rel": "prev", "href": "https://www.example.com/documents/api/1.1/folders/self/items?offset=0&limit=2" }, { "rel": "next", "href": "https://www.example.com/documents/api/1.1/folders/self/items?offset=3&limit=2" }],

HTTP MethodsThe REST API for Documents supports the following standard HTTP methods.

Method Description

GET Request information from the specified resource.

POST Create a new instance of a resource.

PUT Update an existing resource.

DELETE Delete a resource.

HTTP Status CodesA REST action returns a general status code.

For descriptions of the HTTP status codes that the REST API for Documents provides,see "Status Codes" under "Get Started" in REST API for Documents.


4-33


Error CodesSome status codes are accompanied by a fault response body to help you diagnosethe issue.

The following table describes general error codes returned by the errorCode field inthe fault response body for an action. The errorMessage field in the response providesa more detailed description of the error.

Error Code Description

0 The action was successful.

-1 General failure. This code is returned when a more specific statuscode is not available.

-16 A folder or file with the specified name or ID does not exist in thespecified location. This is typically returned as an HTTP 404 responsecode.

-17 A folder or file with the same name already exists in the target location.

-20 The user does not have sufficient privileges to perform the requestedoperation. This is typically returned as an HTTP 403 response code.

-26 The link is invalid or expired. This is typically returned as an HTTP 400response code.

The following example shows the error code and message portion of a response:

{ "errorCode": "-16", "errorMessage": "Security validation failed. 'FABCDEFGHIJKLMNOPQRSTUVWT0000000000100000001' does not exist. The error was caused by an internally generated issue. The error has been logged."}

Applinks ResourceUse the Applinks resource (applinks) to request access to a folder or file for aspecified user and role.

To create an applink, the requester must have admin privileges for the folder or file.That is, the requester must be the owner or have the manager role.

You can grant the specified user any standard role except the manager or owner role.

• Viewer: Viewers can look at files and folders but can't change things.

• Downloader: Downloaders can also download files and save them to their owncomputers.

• Contributor: Contributors can also modify files, update files, upload new files, anddelete files.

For an example of an applink definition, see Examples in the description of "CreateFile Applink" under "Applinks" in REST API for Documents.


4-34


Applink Encryption

All necessary resource object, user, and role information is encrypted and stored in theelements identified in the following table. These elements are returned with the applinkresponse and are used to programmatically carry out other operations on behalf of theassociated user for a defined period of time.

Service calls using an applink must include the associated appLinkID andaccessToken values in the request header.

Parameter Description

appLinkID This element uniquely identifies the resource.

accessToken This element provides access to the resource and expiresafter 15 minutes. You can refresh the access token anynumber of times within the time period defined by the refreshtoken (24 hours).

refreshToken This element enables you to request a new access tokenwhen the current access token expires. The refresh tokenexpires after 24 hours.

Locales for the userLocale Applink Parameter

The following table lists locale codes and the locales they represent for theuserLocale applink parameter.

Locale Code Locale

cs Czech

da Danish

de German

el Greek

en-CA English-CA

en-GB English-UK

en-US English-US

es Spanish

fi Finnish

fr French

fr-CA French-Canadian

hu Hungarian

it Italian

ja Japanese

ko Korean

nl Dutch

nb Norwegian_Bokmål

no Norwegian

pl Polish


4-35

Locale Code Locale

pt Portuguese-Portugal

pt-BR Portuguese-Brazilian

ru Russian

sk Slovak

sv Swedish

th Thai

tr Turkish

ro Romanian

zh-CN Chinese-Simplified

zh-TW Chinese-Traditional

Applink Events

The Applinks resource supports the AppLinkReady event.

Event Description

AppLinkReady Rather than send the required token data in a URL, which would makethe tokens publicly visible and store them in various caches, thismessage is sent from an HTML inline frame (iframe tag) that containsthe embedded user interface, to notify the parent window that the inlineframe is ready to receive data from the Oracle Content and Experienceserver.

Message Handler Example

To pass the necessary keys (the short-term dAppLinkAccessToken and the long-termdAppLinkRefreshToken) into the inline frame without exposing them in a URL, use theAppLinkReady event. The basic steps follow:

1. The inline frame that contains the embedded user interface uses a URL withoutkeys to make the initial call to the Documents Cloud server.

2. The server downloads JavaScript to the inline frame, which posts theAppLinkReady message to the parent window.

3. The parent window posts data to the inline frame that contains the keys.

4. The inline frame sends another URL to the Documents Cloud server with theshort-term key in the header (not in the URL).

The following example illustrates a simple message handler. The createAppLinkfunction referenced in the example is not shown but is assumed to return thenecessary applink resource data:

$( document ).ready(function() { var id = "<Folder or File ID>"; var role = "contributor"; var assignedUser = "<User ID>"; // createAppLink function not shown but assumed to return appLink resource data obtained // from Create Folder Applink or Create File Applink service var appLink = createAppLink(id, role, assignedUser);


4-36

The Get CDN Configuration endpoint retrieves the CDN URL and description.

For REST endpoints and API descriptions, see "Configuration" in REST API forDocuments.

Files ResourceUse the Files resource (files) to manage files in a file system. A file is a uniquelyidentified item associated with a folder (or parent). The parameters of the resourcedefinition describe a physical file object.

Most operations, such as copy, move, and delete, are performed using only theinformation in the file resource definition. Actions that upload a new file or a new filerevision require a multipart request that also identifies the content of the physical fileobject.

For an example of a file definition, see the Examples tab in the description of "Get FileInformation" under "Files" in REST API for Documents.

Files Endpoints

For Files REST endpoints and API descriptions, see "Files" in REST API forDocuments.

Folders ResourceUse the Folders resource (folders) to manage folders in a file system. A folder is auniquely identified item associated with a "parent" folder and optionally with folder andfile "child" items.

These parent and child relationships create a hierarchy similar to the familiar folderstructure in a conventional file system.

For an example of a folder definition, see the "Examples" tab in the description of "GetFolder" under "Folders" in REST API for Documents.

Folders APIs

For REST endpoints and API descriptions, see "Folders" in REST API for Documents.

Metadata Collection ResourceUse the Metadata Collection resource (metadata) to manage folder and file metadata.A metadata collection is a simple way of managing custom metadata fields that youcan then use to store and retrieve metadata values for individual folders and files.

Within a collection, you can create one or more fields. To assign values to the fields ina metadata collection, you must first assign the collection to a particular folder or file.You can assign a collection to one or more folders or files, and any folder or file canhave one or more collections assigned to it.

With a collection, you can add or remove fields and manage the group of fields as awhole. When you assign a collection to a folder or file, you effectively add the fields tothe metadata for the folder or file. The values you assign to the fields are stored andretrieved as part of the metadata for the folder or file itself.


4-38








Metadata Inheritance

Custom metadata fields that you create and manage in a collection follow the samerules of inheritance that standard metadata fields follow. Metadata fields assigned to afolder are available to all folders and files in the hierarchy beneath that folder.Similarly, the values you assign to those fields are inherited by all folders and filesnested beneath that folder unless explicitly defined for a nested folder or file. Metadatavalues specified for a folder or file replace the inherited value for that folder and, by thesame rules of inheritance, for any folders or files in the hierarchy nested beneath thatfolder.

Field References

When setting or removing field values within a collections, there are two ways toreference collections and fields.

You can reference the collection and field names independently. Field references onthe same service call use the specified collection implicitly:

/metadata?collection={collection name}&{field name}={field value}[&{field name}={field value}]

Alternatively, you can specify the collection and field name with each field reference:

/metadata?{collection name}.{field name}={field value}[&{collection name}.{field name}={field value}]

Metadata Collection APIs

For REST endpoints and API descriptions, see "Metadata Collection" in REST API forDocuments.

Publiclinks ResourceUse the Publiclinks resource (publiclinks) to request access to a folder or file for anyuser, whether the user has an account or not.

You can have multiple, named links for the same resource with different access roles,expiration dates, and so on. You can also edit some of the information for an existingpublic link.

For an example of a publiclinks definition, see the Examples tab in the definition of"Get Public Link" under "Publiclinks" in REST API for Documents.

Publiclinks APIs

For REST endpoints and API descriptions, see "Publiclinks" in REST API forDocuments.

Shares ResourceUse the Shares resource (shares) to share a folder and its contents with a specifieduser.


4-39






For information about finding users, see “Get Users" or "Get User with Email Address"under "Users" in REST API for Documents.

When you share folders, you control the permissions each person has for the folderand its files by assigning a role to the person. The different roles determine what aperson can do with a shared file.

• Viewer: Viewers can look at files and folders but can't change things.



• Manager: Managers have all the privileges of the other roles and can add orremove other people as members.

Shares APIs

For REST endpoints and API descriptions, see "Shares" in REST API for Documents.

Sites ResourceUse the Sites resource (sites) to create an Oracle Content and Experience site fromanother site.

The Sites API provides basic site operations.

Sites APIs

For REST endpoints and API descriptions, see "Sites" in REST API for Documents.

Templates ResourceUse the Templates resource (templates) to create a site from a template.

The Templates API provides basic template operations.

Templates APIs

For REST endpoints and API descriptions, see "Templates" in REST API forDocuments.

Users ResourceThe Users resource (users) provides basic information about users to identify them forfolder sharing and file sharing.

Users APIs

For REST endpoints and API descriptions, see "Users" in REST API for Documents.


4-40







REST API for Sites ManagementThe Oracle Cloud REST API for Sites Management provides the ability to create sitesfrom templates and then manage the life cycle of those sites in Oracle Content andExperience.

The REST API for Sites Management has several categories of endpoints, which thefollowing table describes.


Components Import, export, list, read, copy, update, publish, share, delete, restore,and share components.

Policies Manage policies and manage the membership of policies with accesslists. You can read and edit policies associated with site managementoperations and control who can perform site management operationsusing access lists.

Requests Requests are made when creating a site. A site request is rejected orapproved through a review. You can list requests relating to sites editrequests that have been rejected, and retry failed requests. Also, youcan view reviews for site requests. Approve or reject requests for newsites or requests to copy sites.

Sites Create, list, read, copy, share, delete, restore, publish, activate, anddeactivate sites. Get the progress of site-related jobs and informationsuch as the associated repository and the user that created or lastmodified a resource. List sites and requests of a site.

Templates Import, export, list, read, copy, share, delete, and restore templates.List site templates and images. Get the progress of template-relatedjobs.

You can also create policies and associate them with a template to beused when creating a site, or delete policies associated with templates.You can use policies to enforce site-creation approval, who can use atemplate, and what security the site will have.

Themes Import, list, read, copy, publish, update, share, delete, and restorethemes.









REST API for Users and GroupsYou can use the Oracle Cloud REST API for Users and Groups to manage users,groups, one-on-one conversations, and pictures.

Chapter 4REST API for Sites Management

4-41









With the REST API for Users and Groups, you can manage this object:

• People

The REST API for Users and Groups uses the JSON data format and relies on aREST-based architectural style that provides a convenient and consistent approach torequesting and modifying data. The client specifies an action using an HTTP verb suchas POST, GET, PUT, or DELETE. It specifies a resource using a unique URL in thisformat:

https://oracleContentInstance-identityName.network.dataCenter.oraclecloud.com/osn/social/api/v1/resource-path

In the URI:

• oracleContentInstance is the name you chose for your Oracle Content andExperience Cloud instance when it was provisioned.

• identityName is the identity name you chose when you signed up with OraclePublic Cloud.

• network is the name of your network.

• dataCenter is the data center that Oracle Content and Experience Cloud is set upto use.

• resource-path is the relative path that defines the resource.





• REST API Features for Conversations




REST API for Webhooks ManagementThe Oracle Cloud REST API for Webhooks Management provides the ability tomanage webhooks in Oracle Content and Experience.

The REST API for Webhooks Management has the categories of endpoints listed inthe following table.


CSRF Token Returns a CSRF token.

Webhooks Create, delete, read, update, list logs, and list all webhooks.



Chapter 4REST API for Webhooks Management

4-42

















Download the Swagger File for a REST APIDownload a REST API Swagger file for use in your development project.

The Swagger file for each REST API is part of the published REST API document.You can download it from the left Navigation tree.

For example, to download and copy the Swagger file for the REST API for Documents:

1. On docs.oracle.com, open the REST API document at REST API for Documents.

2. On the left, click the download symbol:

3. Click the Swagger button:

The text from the Swagger file for the REST API is displayed.

Chapter 4Download the Swagger File for a REST API

4-43








4. From the Edit menu, choose Select All, and then choose Copy.

5. Paste the copied text into a text file.

Upload a REST API Swagger File into Mobile Cloud ServiceIn Oracle Mobile Cloud Service (MCS), you can create a REST connector API toconnect to the REST API for Documents.

If you provide a Swagger descriptor URL, the REST Connector API wizard canexamine the descriptive metadata and obtain resources and fields from it.

Only Swagger metadata in JSON format is currently supported.

A REST connector API is a configuration for communicating with a specific externalservice to send and receive data. REST connector APIs give you a standard way toconnect a mobile app to existing REST services and at the same time benefit from theOracle Mobile Cloud Service's built-in security, diagnostics, and analytics features.

The connector API communicates and passes information between the client and theserver using the HTTPS protocol. The information passed can be in the form of XMLor JSON (Javascript Object Notation). REST doesn’t contain a messaging layer. Ituses a set of rules to create a stateless service.

The REST Connector API wizard walks you through creating REST connector APIs,from specifying a remote service and setting security policies to testing your endpoints.Additionally, the wizard supports Swagger. When you provide a Swagger descriptorURL, the wizard introspects the endpoints available from that file. The availableresources are identified and displayed. You simply select the resources of the externalservice.

Chapter 4Upload a REST API Swagger File into Mobile Cloud Service

4-44

Only standard internet access ports 80 and 443 are supported. Connection to aservice can't be made using a custom port.

Use the REST Connector API wizard to quickly configure your connector API byproviding a name and description, specifying timeout settings, adding rules, setting asecurity policy, and testing it.

Creating a connection to an existing REST service can be a simple two-step operation:

1. Name your REST connector API.

2. Provide the URL to the external service.

In the REST Connector API wizard, on the page where the you would provide theURL to the Swagger file, there’s a link to the internal Oracle API catalog. You canget the Swagger URL from there and paste it in the field provided for thedescriptor.

You have the option of applying rules to form specific requests or responses for thedata that you want to access. In addition, you have the ability to configure client-sidesecurity policies for the service that you’re accessing and test and check the results ofyour connection.

As soon as it’s created, your REST connector API is listed on the Connectors page.When at least one REST connector API exists, you’ll be taken directly to theConnectors page when you click Connectors from the side menu. From the catalog,you can select the REST connector API and edit it, publish it, create a new version orupdate an existing version, deploy it if it has a Published state, or move it to the trash.

For more information, see "REST Connector APIs" in Developing Applications withOracle Mobile Cloud, Enterprise.

Search with the Querytext ParameterYou can use the querytext parameter of the Search Folders or Files APIs to takeadvantage of string search, tag search, and custom metadata field search at the sametime.

The querytext search string is available in the Search Folders or Files and the SearchFolders or Files Under Specific Folder ID endpoints, to match folder or file names andallow for tag search or custom metadata field search as well. You can use querytextto search an entire directory tree in your home (self) directory as well as sharedfolders.

To set up querytext searches with the REST APIs:

1. Create files and folders, and add tags to them for string searches.

Tags currently support only CONTAINS.

a. Plan where you will place each tag because tags are inherited from parentfolders.

b. Set tags, add tags, or remove tags with the following APIs: Set Folder Tags,Edit Folder Tags, Set File Tags, and Edit File Tags

2. Add metadata collections.

a. As an administrator, create global collections (personal collections are notsupported as indexed collections).

Chapter 4Search with the Querytext Parameter

4-45

b. Determine which fields you will need to support the search, and call APIs inthe metadata resource to index those fields.

There is a limit of 100 fields to be indexed. You cannot remove fields from theindex. The search is done on Favorite shared folders first and then othershared folders, up to 100. You may want to designate some folders asFavorites before searching, to ensure better search results.

c. Only a text or string type search is currently supported. Metadata fields of adate or integer type cannot be searched as date or number.

3. Build your query.

a. Use a search strings in the querytext parameter of the Search Folders orFiles and the Search Folders or Files Under Specific Folder ID endpoints tosearch your folder and file names, tags, and indexed metadata fields.

For examples of tags and custom metadata searches, see the descriptions ofthe endpoints in the REST API for Documents.

b. Search queries require URL encoding of the single-quotation-mark character( ') into %60. For example, Collection1.field1<CONTAINS>'myValue' turnsinto Collection1.field1<CONTAINS>%60myValue%60.

c. Start with simple queries to validate that your conditions do indeed find results.

d. You can build more complex queries by combining parentheses, <AND>clauses, and <OR> clauses.

Set Up Searches on Metadata FieldsSet up searchable metadata fields with the Metadata Collection resource of the RESTAPI for Documents. Then you can run text searches with custom fields.

To search metadata fields:

1. Sign in to Oracle Content and Experience as an administrator and create ametadata collection.

See Metadata Collection Resource.

2. As an administrator, check which metatdata fields are already searchable with theGet Searchable Metadata Fields endpoint, so you can determine how many fieldsyou can add to the search index.

This REST API call retrieves all metadata fields currently available for searchingcontent, The result list includes all metadata fields prefixed with their respectiveglobal metadata collection for the tenant. Each tenant is limited to 100 searchablefields.

3. Use the Set Searchable Metadata Fields endpoint of the REST API for Documentsto specify metadata fields that are searchable.

After you reach 100 fields, you cannot index new fields to become searchable.Fields cannot be deleted from the search index.

For custom metadata searches, the REST API for Documents supports only textsearches using CONTAINS. It does not support numeric or date searches. For example,custom metadata fields created through the web user interface are not searchablebecause they are numeric or date type fields.

Chapter 4Set Up Searches on Metadata Fields

4-46



For more information about these endpoints and examples of using them, see "SetSearchable Metadata Fields" and "Get Searchable Metadata Fields" under "MetadataCollection" in REST API for Documents.

Create and Use Applinks for File and Folder AccessYou can control access to files and folders in Oracle Content and Experience withapplink endpoints of the REST API for Documents.

The following endpoints let you control user access to files and folders:

• Create File Applink

• Create Folder Applink

• Refresh Applink Token

To create an applink for a user to access a file or folder, you must be the owner orhave the manager role. Either of these roles gives you admin privileges for the file orfolder.

When you create a file or folder applink for a user, you can grant the user any of theseroles:

• Viewer: Viewers can look at files and folders, but can't change things.



The response from the Create File Applink or Create Folder Applink REST APIincludes an applink ID, access token, and refresh token. For example:

{ "appLinkID":"LDhsn4VPTsnDnKpKLFZTCkjaPkYbMC6-3taYSdJAazckhezJ2HlSjs2THOou6cCAvxcRnw5gpXcU7pIRkCmWN8kEToJHFwwZ-ptWvPGhJaiirl9baL9mka14WnwpL6auOO40-gFMPvkPv23OtMnj2W3A==", "accessToken":"GYrSN5zuj0kOTE4k_60bKvdkxx2-ARA546A2T77GtEOgoPZPGgKk126OeCn1w-Ij", "appLinkUrl":"http://www.example.com/documents/embed/link/app/LDhsn4VPTsnDnKpKLFZTCkjaPkYbMC6-3taYSdJAazckhezJ2HlSjs2THOou6cCAvxcRnw5gpXcU7pIRkCmWN8kEToJHFwwZ-ptWvPGhJaiirl9baL9mka14WnwpL6auOO40-gFMPvkPv23OtMnj2W3A==/fileview/DFD11F62E911327CB1F160F6T0000000000100000001", "refreshToken":"Yc_b_dE8V03eDTCmcmC1gi_y3LVJTPiZOSQDhuS_VWim9E_FRpLQGtEhgxCNbKTG", "role":"manager", "id":"DFD11F62E911327CB1F160F6T0000000000100000001", "type":"applink", "errorCode":"0"}

The user needs to pass the applink ID and access token parameters in the requestheader for each REST API operating on the folder or file or on any child folder or file.

Chapter 4Create and Use Applinks for File and Folder Access

4-47


The response does not provide a link to the file or folder because headers cannot berepresented in a link.

The access token expires after 15 minutes. You can refresh the access token anynumber of times within the time period defined by a refreshed token (24 hours). Usethe refresh token to request a new access token when the current access tokenexpires. The refreshed token expires after 24 hours.

For more information about the applink REST APIs, see "Applinks" in REST API forDocuments.

Provide Access to Files and Folders with Public LinksTo give users access to files and folders, you can use public links to share the filesand folders with assigned users.

You can create multiple, named links for the same file or folder resource with differentaccess roles, expiration dates, and so on. You can also edit some of the informationfor an existing public link.

To provide access to a files and folders with a public links:

1. Use the Create File Public Link and Create Folder Public link REST APIs to createthe public links you need.

2. If you want to edit the available public link parameters, use Edit Public Link RESTAPI.

3. Use the Get File Public Link or Get Folder Public Link REST API to get informationabout the pubic links available for a file or folder.

For example, the follow Get Folder Public Link request specifies the folder IDF4E111D0D0645CD368453C2BT0000000000100000001:

GET . . ./publiclinks/folder/F4E111D0D0645CD368453C2BT0000000000100000001

If the HTTP Status Code is 200 and one or more public links are available for thespecified folder, the response returns information about public links defined for thefolder:

{ "count": "2", "errorCode": "0", "id": "F4E111D0D0645CD368453C2BT0000000000100000001", "type": "folder", "items": [ { "type": "publiclink", "linkID": "LF31C09DE51854DBBDA37A90T0000000000100000001", "linkName": "hasSecondLink", "ownedBy": { "displayName": "User AA", "loginName": "userAALoginName", "id": "U0EAA20910FAF3052ACB79E4T00000000001", "type": "user" },

Chapter 4Provide Access to Files and Folders with Public Links

4-48



"role": "viewer", "assignedUsers": "@everybody", "createdTime": "2015-06-02T19:30:37Z", "lastModifiedTime": "2015-06-02T19:30:37Z" }, { "type": "publiclink", "linkID": "LF5E5F73A444FFB8924EF8ACT0000000000100000001", "linkName": "hasFirstLink", "ownedBy": { "displayName": "User AA", "loginName": "userAALoginName", "id": "U0EAA20910FAF3052ACB79E4T00000000001", "type": "user" }, "role": "contributor", "assignedUsers": "@serviceinstance", "createdTime": "2015-06-10T16:15:37Z", "lastModifiedTime": "2015-06-10T16:15:37Z" } ]}

This response shows that two public links are available, one for users who areassigned the viewer role for the folder and one for users who are assigned thecontributor role. You use information from the response in API headers to sharethe folder with the assigned users (assignedUsers value) specified in the publiclink.

In the example, the second link grants contributor-level access to all accountholders for the Content and Experience instance that hosts the specified folder.

For example:

@serviceinstance/documents/link/LF5E5F73A444FFB8924EF8ACT0000000000100000001/folder/F4E111D0D0645CD368453C2BT0000000000100000001

4. To share a file or folder, use the information from the response in the headers ofother APIs, like Share Folder or Collection.

A web client can use a URL in one of the following formats to allow file or foldervisualization through a public link:

domain URL/documents/link/linkID/fileview/file ID

domain URL/documents/link/linkID/folder/folder ID

For more information about public links, see Publiclinks Resource or "Publiclinks" in REST API for Documents.

Chapter 4Provide Access to Files and Folders with Public Links

4-49


5Oracle Content and Experience SDKs

Oracle Content and Experience provides software development kits (SDKs) that helpyou integrate and extend Oracle Content and Experience functionality.

• Content SDK

• Mobile SDKs

Content SDKThe Content SDK for Oracle Content and Experience is a light-weight JavaScriptwrapper that interacts with the Content REST APIs.

This read-only SDK retrieves structured content, digital assets, and content layoutsthat are managed in Oracle Content and Experience. Different versions of the SDK areavailable for use in browser projects or NodeJS projects.

The Content SDK consists of three main modules:

• ContentSDK: The main entry-point object. The ContentSDK object lets you createclient objects to access content based on your requirements.

• ContentDeliveryClient : A client object that is set up to access published contentitems and digital assets.

• ContentPreviewClient : A client object that is set up to access content types,draft content items, and draft digital assets.

The Content SDK is made available as an Oracle open-source project on GitHub:

https://github.com/oracle/content-sdk-for-nodejs

You can download it for both NodeJS and Browser on the Oracle Content andExperience downloads page. It's also available for download from your Oracle Contentand Experience server. There is an AMD module for use through RequireJS in theBrowser and a CommonJS module for use in NodeJS server-side applications:

• Browser: load via RequireJS - https://{server}/_sitesclouddelivery/renderer/app/sdk/js/content.min.js

• Node: npm install - https://{server}/_sitesclouddelivery/renderer/app/sdk/npm/contentsdk-1.1.0.tgz

Detailed descriptions of the ContentSDK, ContentDeliveryClient, andContentPreviewClient classes are available at Content SDK.

Mobile SDKsThe Mobile SDKs for Oracle Content and Experience are read-only SDKs for retrievingpublished content items, digital assets, and content layouts that are managed inOracle Content and Experience.

5-1

http://www.oracle.com/pls/topic/lookup?ctx=cloud&id=cec-sdk-content-delivery

https://github.com/oracle/content-sdk-for-nodejs

https://www.oracle.com/middleware/technologies/content-experience-downloads.html


http://www.oracle.com/pls/topic/lookup?ctx=cloud&id=cec-sdk-content-delivery

The Mobile SDKs are light-weight iOS and Android bindings that interact with the REST API for Content Delivery. These SDKs can easily be integrated with any third-party iOS or Android mobile application. The Mobile SDKs let you fetch content fromthe server on the fly, without the need for rebuilding the app to modify content. TheSDKs also provide a wide range of advanced utilities and features such as responsecaching, a search request builder, and request/response modeling.

You can download the SDKs for iOS and Android on the Oracle Content andExperience downloads page. Each SDK includes a readme file that providesinstructions on how to use the SDK in your projects.

Mobile SDK downloads are here:


Chapter 5Mobile SDKs

5-2

http://www.oracle.com/pls/topic/lookup?ctx=cloud&id=cec-rest-api-content-delivery




6Embed the Web User Interface in OtherApplications

You can embed the Oracle Content and Experience web user interface for assets anddocuments in other applications. The embedded web interfaces can includeconversations, sites content, search results, and other Oracle Content and Exeriencefeatures.

The following topics describe the how to embed the web interface:

• Embed the Web User Interface for Assets

• Embed the Web User Interface for Documents

• Authentication and SSO Environments

• Real-Time Updates for Embedded Conversations

• Embed Documents Manager on a Site Page

• Security for Content in Other Domains

• Embed Content in Other Domains

• Browser Configuration Parameters

• Embed Search Results

• Embed Sites Content in Another Domain

• Integrate Folder and File Selection

• Configure the File Picker with the SitesSDK.filePicker Method

Embed the Web User Interface for AssetsEmbed the web user interface for assets into your own web applications to get accessto digital assets in an Oracle Content and Experience asset repository.

The next two figures show both versions of the web user interface. The first figureshows the user's assets with an asset repository selected in the standard interface

6-1

The following figure shows an example of the same asset selection using theembedded web interface, in the Assets View. Note that the banner and side panels arenot displayed in the embedded web user interface.

Chapter 6Embed the Web User Interface for Assets

6-2

To embed the Oracle Content and Experience web user interface for assets in aninline frame, add /embed immediately after the /assets element in the URL used topopulate the inline frame. For example, the following URL calls the standard userinterface for assets:

https://www.example.com/assets

Note:

The embedded web user interface adjusts the content to fit within windowsas small as 320 pixels wide. Windows smaller than 320 pixels begin to hidecontent on the right edge of the window.

You can specify configuration parameters on the URL that control some aspects of thebrowser display. For information about configuring the appearance of the embeddedweb user interface, see Browser Configuration Parameters.

The itemUploaded event occurs whenever a new asset is added to a folder orrepository, due to a user's interaction with the embedded client. The event payload

Chapter 6Embed the Web User Interface for Assets

6-3

contains the new item data and the container (folder or repository). Only one new itemwill be included in the event. If multiple items are uploaded, multiple events will occur.The event occurs after the upload is complete.

Embed the Web User Interface for DocumentsEmbed the web user interface for Oracle Content and Experience documents into yourown web applications to get access to the folder and document management featuresof the service.

To embed the Oracle Content and Experience web user interface for documents in aninline frame, add /embed to any member or public folder link immediately after the /documents element in the URL used to populate the inline frame. For example, thefollowing URL calls the standard user interface for documents and shows the homefolder for the current user:

https://www.example.com/documents/home/nameasc

To display the home folder in the embedded web user interface, use the following formof the URL:

https://www.example.com/documents/embed/home/nameasc

To open a specified folder in the embedded web interface, use the folder element inthe URL and specify the globally unique identifier (GUID) of the folder. For example,the following link opens the specified folder in the embedded web user interface.

https://www.example.com/documents/embed/folder/1713A5712BE73C37891915A0127B594F/nameasc

Note:

The embedded web user interface adjusts the content to fit within windowsas small as 320 pixels wide. Windows smaller than 320 pixels begin to hidecontent on the right edge of the window.

You can also embed member links and public links to folders and specify configurationparameters on the URL that control some aspects of the browser display. Forinformation about configuring the appearance of the embedded web user interface,see Browser Configuration Parameters.

Authentication and SSO EnvironmentsIf you have signed in to the full web client in another tab, then the embedded web userinterface will load without additional authentication, using the already establishedsession in the browser.

If there is no existing browser session, then the behavior of the /embed URL is topresent a sign in screen in a popup browser window. Once credentials are provided in

Chapter 6Embed the Web User Interface for Documents

6-4

the popup sign in window, the embedded client will reload without furtherauthentication.

Note:

This behavior requires that any browser popup blockers are configured toallow the popup to display.

When the page hosting the embedded web user interface is within the same OracleAccess Manager Domain (Single Sign On), the /embedsegment of the URL should bereplaced with /ssoembed. In ssoembed mode, the web user interface assumes thatthere is an existing SSO session established in the browser and no popupauthentication is required. For example:

https://www.example.com/documents/ssoembed/home/nameasc

Real-Time Updates for Embedded ConversationsUsing embedEnterHive enables real-time updates to a conversation from other userswho may be posting in the conversation as well as presence indicators for users asdisplayed in the conversation header, such as Active or Idle.

Embedding a conversation view in the web user interface disables back-channelcommunication with the server by default. This means the view is a static display ofthe conversation at the time it was loaded, and the view will not display real-timeupdates. To get real-time updates, you must add the parameter embedEnterHive to theURL used to load the embedded view. For example:

https://www.example.com/documents/embed/conversation/12345?embedEnterHive

The embedEnterHive parameter can also be used to display a folder or file view thathas a side-by-side conversation in the side bar, to get real-time updates on theconversation.

Using embedEnterHive is required in an embedded file view for annotations to functionproperly. For example:

https://www.example.com/documents/embed/fileview/fileid/_file.doc?embedEnterHive

The web user interface cannot accurately detect when the iframe containing it isdestroyed. When the embedEnterHive parameter is used, the hosting code must signalto the web user interface in the iframe to close the service. This done through apostMessage call as follows:

iframewindow.postMessage({message: "closeService"}, *);

This ensures the client properly sends an "exit hive" call to the server, discontinuingback-channel communication.

Chapter 6Real-Time Updates for Embedded Conversations

6-5

Embed Documents Manager on a Site PageYou can embed documents manager on a site page to provide a view of your homepage or files in Oracle Content and Experience.

See Documents in Building Sites with Oracle Content and Experience.

Security for Content in Other DomainsWhen you embed the Oracle Content and Experience web user interface, it’s enclosedin an inline frame. Security policies are enforced to minimize the security risks ofhosting external sites in inline frames.

In general, inline frames can host content if the protocol, domain, and port of the inlineframe are identical to those for the content it displays. For example, by default, aninline frame on the page http://www.example.com:12345/home.html can host contentonly if the content's protocol is also http, the domain is www.example.com and the portis 12345.

An administrator can explicitly identify domains outside of the host domain and allowcontent from those domains to display in the embedded web user interface.

Note:

Before implementing a web interface integration that uses inline frames, besure you understand the possible security risks associated with hostingexternal sites in inline frames. Security measures vary between differentbrowsers and different browser versions. For more information, see http://www.w3.org/TR/UISecurity/.

Oracle Content and Experience displays content for authorized users in the embeddedweb interface. Supported content includes folders, member links, and views ofindividual files.

All unsupported content, such as public links and content from unauthorized domains,opens in a new browser tab or window (depending on the browser settings).

Embed Content in Other DomainsYou can display content from Oracle Content and Experience within other domains.For example, you might embed the Oracle Content and Experience web user interfaceinto your own web applications to access folder and document management featuresinside your application.

To allow users to embed content, enable embedded content and add domains:


2. In the System Settings menu, click Security.

3. Under Embedded Content , select Enabled.

Chapter 6Embed Documents Manager on a Site Page

6-6

http://www.w3.org/TR/UISecurity/

http://www.w3.org/TR/UISecurity/

4. In the Allowed domains box, enter a list of permitted domains, separated bycommas. Domains must be in the form www.example.com.

• To restrict the domain to a particular port, include the port in the specification.For example, www.example.com:12345.

• If you want to allow a domain that has multiple sub-domains, you can use the* wildcard character. For example, www.example.* includes the domainswww.example.com, www.example.co.uk, and so on.

To learn about embedding the Oracle Content and Experience web user interface, see Embed the Web User Interface in Other Applications.

Browser Configuration ParametersYou can include optional parameters in the URL for a folder or folder link to controlsome aspects of the browser display. This can be very useful for embedding the webuser interface in other applications.

Layout Configuration

You can append the layout configuration parameter (lyt) and a single value to theend of a URL for a folder or folder link using the following format:

{URL}/lyt={value}

For example, the following URL uses a member link to display the associated folder inthe embedded web interface with a grid layout:

https://www.example.com/documents/embed/folder/FDB8AC67BE3FCFB4984E1327T0000DEFAULT00000000/_Resources/lyt=grid

Note:

You can use the layout parameter with folders and folder links in both thestandard and embedded web interfaces.

Value Description

list Displays the folder content in the standard list layout.

grid Displays the folder content in the standard grid layout.

Embed Mode Configuration

You can specify an embed mode configuration as a URL query parameter:

• hide: Hides elements that are visible by default when embedded.

• show: Shows elements that are visible by default when embedded.

Options of the embed mode configuration apply only when you use embed mode URLs,including applink URLs. You can use the following embedded views:

• Assets View (embed/assets)

Chapter 6Browser Configuration Parameters

6-7

• Folder View (embed/folder/{folderId}) or (embed/folder/home)

• File View (embed/fileview/{fileId})

• Conversations List (embed/conversations)

• Conversation View (embed/conversations/{conversationId})

• Themes View (embed/themes)

For example:

/documents/embed/folder/{folderId}?hide=header+actions&show=branding&singlesel

In the Assets View, you can use the repository configuration parameter to preselectthe Repository filter value:

https://www.example.com/embed/assets/repository/{repositoryID}

You can add individual options directly as parameters. Combine multiple hide andshow options with either a plus sign (+) or comma (,). For example:

hide=header+breadcrumbs+sidebar

The following table lists the options you can use for embed mode configuration.

Parameter Value Description

autoplay Auto play video and audio content

channel <channelId> Preselect the channel filter value. Must bevalid for the initially loaded (preselected)repository.

channeloptions <channelId>+

<channelId>+. . .

Limit the Channel filter control to the providedlist

channeloptions none Hide the Channel filter control altogether

collapsetn Start with thumbnails area collapsed

collection <collectionId> Preselect the collection filter value. Must bevalid for the initially loaded (preselected)repository.

collectionoptions <collectionId>+

<collectionId>+. . .

Limit the Collection filter control to theprovided list. The list can contain collectionsfrom any repository in the repositoryOptionslist. Control will display only collectionvalidation for any selected repository.

collectionoptions none Hide the Collection filter control altogether

contenttype article+blog+. . . Preselect the listed content type filters for theAssets View

contenttypeoptions none Hide the Content Items section in the AssetsView

contenttypeoptions article+blog. . . Display the listed content type filters asavailable options

docsonly Include only documents in list

fitoriginal Start document at original size


6-8


fitpage Start with document fit to page

fitwidth Start with document fit to width

foldersonly Include only folders in list

hide actions Hide all document actions

hide add Hide action Add in the Assets view header

hide breadcrumbs Hide breadcrumb area

hide collections Hide action Collections in the Assets viewheader

hide copy Hide action copy

hide delete Hide action delete

hide dnload Hide action download

hide favs Hide Favorite actions and View menu

hide fitpage Hide fit to page action in file view

hide fitwidth Hide fit to with action in File View

hide header Hide content header

hide move Hide action move

hide new Hide header create action (new folder)

hide nextprev Hide next and previous controls (File View)

hide pin Hide annotation mode pin

hide props Hide action props

hide rename Hide action rename

hide reserve Hide action reserve

hide share Hide action share

hide sidebar Hide sidebar

hide thumbs Hide viewer thumbnail area

hide toolbar Hide toolbar (Folder View)

hide trash Hide Trash View menu

hide upload Hide action upload

languageoptions en-US+fr-FR+. . . Limit the Language filter control to theprovided list

languageoptions none Hide the Language filter control altogether

launch Launch documents on view (opens new tabversus inline)

loop Loop video and audio content

mute Mute video and audio content

nofocus Don’t take focus

noopen Disable action open for folders in Folder Viewand conversations in conversation list(conversation list becomes multiselect)

novidctls Hide video controls

noview Disable action view for files in Folder View

repository <repositoryId> Preselect the Repository filter value in theAssets View

repositoryoptions <repositoryId>+

<repositoryId>+. . .

Limit the Repository filter control to theprovided list. Must include the repositoryparameter value, if provided.


6-9


show backbutton Add a back arrow

show branding Show branding header (hidden in embedmode)

simpleDisplay Simplified select list

singlesel Single select

status published+approved+rejected+draft+pending

Preselect the lists status filters

statusoptions none Hide the Status panel altogether

statusoptions published+approved+rejected+draft+pending

Display the listed status filters as availableoptions

type images+video+documents

Preselect the listed type filters for the AssetsView

typeoptions images+video+documents

Display the listed type filters as availableoptions

typeoptions none Hide the Digital Assets Type section or Typepanel in the Assets View

wide Display wide content area

Browser Configuration

The embed mode configuration has replaced the legacy browser /cfg settings.Existing /cfg settings are supported in embed mode if no legacy query parameters arespecified.

Embed Search ResultsIn an embedded web user interface for Oracle Content and Experience, search resultsare available through an embed URL.

For example, the embed URL format for displaying search results for document andfolder types follows:

https://domain-name/documents/embed/search/search-string/documents?hide=titlemenu

The hide=titlemenu option parameter must be passed in the URL to hide the list filterdrop-down menu. The search type cannot be filtered in an embed URL.

In an embed URL, you can use the same search string that you can use in a URL thatis not embedded. For information about search strings, see Search Content andConversations in Collaborating on Documents with Oracle Content and Experience.

You can use these search types in an embed URL:

• documents

• conversations

• folder (scoped folder)

Chapter 6Embed Search Results

6-10

For example, the embed URL format for displaying search results within a scopedfolder follows, sorted by last updateds:

https://domain-name/documents/search/search-string/folder/lastupdated/folder_guid?hide=titlemenu

You can use these sort-by types in an embed:

• lastupdated

• filesize

• name

For example, the format for displaying search results for conversation types follows,sorted by last updated:

https://domain-name/documents/embed/search/search-string/conversations/lastupdated?hide=titlemenu

Embed Sites Content in Another DomainYou can embed an Oracle Content and Experience site or a site page into a pageserved from another domain.

To embed a site or site page into an iframe on an external site page that is servedfrom another domain, set the Embeddable Site property to Yes on the site propertiespage.

See Embed Content in Other Domains in Administering Oracle Content andExperience.

Integrate Folder and File SelectionYou can access folders and files stored on Oracle Content and Experience Cloud fromyour own applications.

Two online tutorials show how to make REST calls to Oracle Content and ExperienceCloud from a web page using JavaScript. These tutorials are on each provisionedinstance, at a location similar to this URL:

https://<host_name>[:<port>]/documents/static/api/<tutorial>

The tutorials document the code and code options and provide a demonstration of thefunctionality.

Tutorial Description

FilePickerTutorial.html Provides an interface button and supporting JavaScript code toselect one or more folders or files and returns the REST responsethat includes the selection. This method is useful for workingdirectly with folders and files using the credentials of a provisioneduser.

Chapter 6Embed Sites Content in Another Domain

6-11

Tutorial Description

LinkPickerTutorial.html Provides an interface button and supporting JavaScript code toselect a file and return the public link to the file. This method isuseful for providing public access to a specific file.

Both tutorials include options for using an application link (applink) to access foldersand files. An application link provides access to a folder or file for a user with aparticular role for a period of time. You can use the application link on subsequentcalls that access the associated folder or file without having to establish usercredentials with each call. For more information, see Applinks Resource.

Configure the File Picker with the SitesSDK.filePickerMethod

You can use the SitesSDK.filePicker() method to pass configuration parameters in aURL for the embeddable File Picker user interface.

Browser Configuration Parameters describes the configuration parameters you canpass.

You can specify a configuration parameter with either of two options:

• Name-value pair

SitesSDK.filePicker({ <name>: <value-in-string>

For example:

SitesSDK.filePicker({ statusoptions: 'published+draft',

• Name only

SitesSDK.filePicker({ <name>: <value-in-boolean>

For example:

SitesSDK.filePicker({ autoplay: true,

Custom options are enabled in an asset URL or a document URL.

The following example uses the hello-there app:

SitesSDK.filePicker({ statusoptions: 'published+draft', autoplay: true, showReset: true, hide: 'sidebar',

Chapter 6Configure the File Picker with the SitesSDK.filePicker Method

6-12

docsonly: true, singlesel: true, 'multiSelect': false, 'supportedFileExtensions': ['jpg', 'png']

This example would generate the following URL for the embedded File Picker:

http://localhost:8080/documents/embed/folder/home/nameasc?scheme=light&thinheader=true&layout=grid&docsonly&noview&wide&singlesel&statusoptions=published+draft&autoplay&hide=sidebar

Chapter 6Configure the File Picker with the SitesSDK.filePicker Method

6-13

7Set Proxies

To set proxies, you can configure a proxy server that provides a URL to which webbrowsers can connect.

• Configure Proxy Service Settings

• Debug Proxy Service Endpoints

Configure Proxy Service SettingsOracle Content and Experience includes a proxy service, so that you can use RESTservices that have Cross-Origin Resource Sharing (CORS) limitations or requireservice account credentials.

The proxy service is a reverse proxy server. It provides a URL to which web browsersconnect. The proxy service then acts as an intermediary between the web browserand a remote REST service (or endpoint). The proxy service explicitly adds CORSsupport to all endpoints and can optionally insert service account credentials torequests coming from web browsers.

If you are using a REST server (or endpoint) which already supports CORS anddoesn't require the use of service account credentials, you don't need to register it withthe proxy service. You can instead register it directly with the Oracle Cloud REST APIfor Content Management.

1. After you sign in to the Oracle Content and Experience web application as anadministrator, click Integrations in the Administration area of the navigation menu.

2. Under Proxy Service, select Enable.

3. Using the following steps, define any credentials needed by your endpoints, anddefine the endpoints you want to use the proxy service.

Credentials

When an endpoint uses a credential, the proxy service adds basic accessauthentication (via the HTTP Authorization header) to requests made by webbrowsers. If the browser request already includes the Authorization header, thebrowser request Authorization header will be used instead of the one in the credential.

This gives you the flexibility to provide a read-only credential for most requests, butallow individual requests to provide their own write-capable authentication as needed.

Providing a credential to an endpoint gives all users of the endpoint the same effectivepermissions granted to the user defined in that credential. To ensure you don’tinadvertently create a security risk, take the following precautions:

• Don’t provide a credential for an endpoint unless absolutely necessary. If possible,let the browser requests provide their own Authorization header instead.

• If you must provide a credential, try to use one which has read-only access on thetarget endpoint.

7-1

• Limit the allowed methods on the endpoint to what is actually required. Unlessabsolutely necessary, always disable the PUT, POST, and DELETE methods onan endpoint.

• When possible, limit the Target URI for the endpoint to a specific area offunctionality. For example, rather than providing the base URI to the full API suchas http://example.api/, you might be able to limit it to a specific area such ashttp://example.api/weather/ (for weather-related requests) or http://example.api/date/ (for date-related requests).

If an endpoint requires credentials, define a credential and select it in the endpointdefinition:

1. Click Create new Credential, and complete the following information.

2. In the Credential Name box, enter a name for the credential that will make clearto other users what the credential is for (for example, DocsAPIUser).

3. In the Username box, enter the user that should be used to authenticate allrequests with the endpoint.

4. In the Password box, enter the password for the user you entered.

5. In the Keywords box, optionally provide space-delimited keywords for thecredential. Keywords are purely informational for your own needs and do not alterthe functionality of the credential. Keywords can include alphanumeric characters,periods, hyphens, and underscores.

The Keywords field is exposed by the proxy service API and can be viewed bynon-administrator users. Never include user names, passwords, API keys, or othersensitive information in the Keywords field.

6. Click Save.

The new credential is available to use with one or more endpoints. It appears in theCredential drop-down list when you create or edit an endpoint.

Endpoints

1. Define the remote API endpoint you want to use the proxy service. Click Createnew Endpoint, and complete the following information:

a. In the Endpoint Name box, enter a name for the endpoint that will make clearto other users what this endpoint is (for example, Content Management API1.1).

b. Under Enable Endpoint, select Enabled.

You can disable individual endpoints as necessary, rather than disabling thewhole proxy service.

c. In the Path Name box, enter a path name for the endpoint (for example,docs). This will become part of the URL path to access the endpoint (forexample, /pxysvc/proxy/docs).

The name must be unique, URL-safe, and lowercase, and it must start with aletter. It can include alphanumeric characters, hyphens, and underscores.

d. In the Target URI box, enter the URI for the endpoint (for example, http://service.example.com/documents/api/1.1).

e. Under Credential, if necessary, select the credentials to use for this endpoint.This list is populated by the credentials you created using the steps above.

Chapter 7Configure Proxy Service Settings

7-2

f. Under HTTP Methods, select the HTTP methods you want to enable for thisendpoint.

GET and OPTIONS methods are always enabled.

g. In the Keywords box, optionally provide space-delimited keywords for theendpoint. Keywords are purely informational for your own needs and do notalter the functionality of the endpoint. Keywords can include alphanumericcharacters, periods, hyphens, and underscores.

The Keywords field is exposed by the proxy service API and can be viewedby non-administrator users. Never include user names, passwords, API keys,or other sensitive information in the Keywords field.

h. In the Connection Timeout box, enter the maximum number of seconds towait when trying to make a connection with the target URI.

i. In the Socket Timeout box, enter the maximum number of seconds to wait fora pooled connection in the proxy service.

j. In the Connection Request Timeout box, enter the maximum number ofseconds to wait when trying to make a connection with the proxy service.

k. Test your endpoint, by clicking Save and Debug. See Debug Proxy ServiceEndpoints.

l. When you’re satisfied with the result, click Save and Close.

Debug Proxy Service EndpointsYou can quickly test a proxy service endpoint without writing any test code. This canbe a valuable tool to see how requests and responses are handled between your webbrowser, the proxy service, and the target URI of the endpoint.

1. After defining the endpoint, test it by clicking Save and Debug.

Alternatively, in the list of endpoints, click next to the endpoint you want todebug.

At the top of the Debug Endpoint section, you see the URI mapping, whichshows how the endpoint’s local path name is mapped to the target URI of theendpoint. Both the local path and the target URI are links so you can make surethey are pointing to the correct locations.

2. Optionally, enter a user name and password and additional headers to use for thetest request. These credentials will be used in lieu of any credential already set onthe endpoint. This enables you to test or verify the use of credentials withoutmaking them available to all users of the endpoint.

3. Optionally, enter additional headers to use for the test request. Enter one headerper line, using the standard format Name: Value. For example: Content-Type:application/json.

4. Select an HTTP method, then provide a complete path for the request.

If you select POST or PUT, in the Data box, enter the content which should besent in the POST or PUT request body.

5. Click Submit Request.

6. In the Debug Result section, expand the panels to see the detailed results:

Chapter 7Debug Proxy Service Endpoints

7-3

• Browser Request to Proxy: Displays the HTTP request headers and bodysent by the web browser to the proxy service.

• Proxy Request to Endpoint: Displays the HTTP request headers and bodysent by the proxy service to the target URI of the endpoint. If the endpointuses a credential, an authorization header is inserted in the request, but theheader value isn’t shown in the debug results.

• Endpoint Response to Proxy: Displays the HTTP response headers andbody sent by the target URI of the endpoint back to the proxy service.

• Proxy Response to the Browser: Displays the HTTP response headers sentby the proxy service back to the web browser. If the target URI of the endpointdoesn’t return CORS headers, the proxy service inserts them in its responseto the browser.

7. If necessary, change the debug request and submit the request again.

Note:

The old debug results are overwritten with the new results.

8. When you’re satisfied with the result, click Close.

Chapter 7Debug Proxy Service Endpoints

7-4

8Develop Custom Actions with ApplicationIntegration Framework (AIF)

You can use Application Integration Framework (AIF) to define actions that areexposed in the web interface, respond to user selections, call third-party services, andspecify how the results are presented to the user.

• Application Integration Framework Overview

• Configuration File Format

• Application Properties

• Action Command

• Invoke Command

• Presentation Command

• Expressions

• Variables

• Localization

Application Integration Framework OverviewApplication Integration Framework (AIF) provides a simple and effective way tointegrate third-party services and applications into the Oracle Content and Experienceweb interface.

Using AIF, you can quickly define the actions that are exposed in the web interface,respond to user selections, call third-party services, and specify how the results arepresented to the user. The framework supports variables and expressions andprovides multiple language support.

Custom AIF applications are not applied when you access them through an applink orpublic link.

The definition for one or more integrations is stored in a single file in JSON format. Asa developer, you can upload the configuration file and add it to a list of availableapplications. You can also edit and validate the configuration file directly in the webinterface, enable or disable the app for general use, set preferences, or delete the app.

The definition for one or more integrations is stored in a single configuration file inJSON format. The configuration file defines and manages the interactions between theapp, native objects and web interface elements. The configuration file includes:

• App properties including tenant and user preferences

• Actions that are exposed in the web interface and the service calls they make

• How the results are presented to the user

• Interface strings with support for multiple languages

8-1

As a developer, you can add the configuration file, enable the integration, and providetenant and account information to get started. You can also edit and validate theconfiguration file directly in the web interface, download the configuration file, or deletethe app.

To manage apps created with Application Integration Framework, sign in as adeveloper, open your user menu, choose Administration, and then chooseIntegrations. Under Custom Actions, click Add.

Chapter 8Application Integration Framework Overview

8-2

From the Applications page, you can use the following options.

Setting Description

Enable or disable the application for users. When you enable theapplication, you can specify preferences for the application from theuser menu, by choosing Preferences and then ApplicationsSettings. You specify the user preferences resource in theuserPrefs element in the configuration file.

Browse local folders and files to locate and upload an applicationconfiguration file.

Display the information defined for the application and specified in theinfo element of the configuration file.

Display the preferences resource defined in the tenantPrefs elementof the configuration file.

Chapter 8Application Integration Framework Overview

8-3

Setting Description

Open the configuration file in the integrated JSON editor. The editorvalidates the syntax of the file to ensure that the file contains validJSON code. Changes you make to the configuration file areimmediately available in the enabled application.

Changes you make to the configuration file are stored only in theserver copy of the file. To back up your changes, use the Downloadicon to save the file locally.

Download the file from the server to a local destination.

Delete the configuration permanently.

When you delete a configuration file, the deletion is permanent. Thefile can’t be restored from the trash.

Configuration File FormatThe definition for one or more integrations is stored in a single configuration file inJSON format.

The extension of an AIF configuration file must be .conf.

As an developer, you can upload the configuration file and make it available to users.See Application Integration Framework Overview.

A sample configuration file for one application follows. All keys and values in theconfiguration are case-sensitive.

{ "id": "ExampleCoPublishing", "name": "APP_SUBMIT_TO_PUBLISH_DOCS_NAME", "description": "APP_SUBMIT_TO_PUBLISH_DOCS_DESC", "category": "CUSTOM", "supportEmail": "[email protected]", "baseUrl": "http://www.example.com/", "info": { "documentation": "Opens a URL with a description of the app in a popup window", }, "info": { "presentation": { "view": "POPUP" }, "invoke": { "method": "GET", "url": "http://www.example.com/ExampleCoDescr.jsp", "data": "" } }, "tenantPrefs": { "presentation": { "view": "POPUP" }, "invoke": { "method": "GET", "url": "http://www.example.com/ExampleCoAdmin.jsp", "data": "" }

Chapter 8Configuration File Format

8-4

}, "userPrefs": { "presentation": { "view": "POPUP" }, "invoke": { "method": "GET", "url": "http://www.example.com/ExampleCoUser.jsp?user={user.id}", "data": "" } }, "actions": [ { "id": "submitToPublish", "name": "ACTION_SUBMIT_TO_PUBLISH_NAME", "description": "ACTION_SUBMIT_TO_PUBLISH_DESC", "type": "UI", "trigger": "MENU", "presentation": { "view": "POPUP", "popupWidth": 700, "popupHeight": 400 }, "evaluate": "type=='folder' && user.isMember && user.role=='owner' && !isReservedByAnotherUser", "invoke": { "method": "GET", "url": "http://www.example.com/ExampleCoSubmit.jsp?user={user.id}&ids=[{id},]&names=[{name},]" }, "multi": false }, { "id": "showPublishStatus", "name": "ACTION_SHOW_PUBLISH_STATUS_NAME", "description": "ACTION_SHOW_PUBLISH_STATUS_DESC", "type": "UI", "trigger": "SELECT", "presentation": { "view": "POPUP", "popupWidth": 300, "popupHeight": 200 }, "evaluate": "type=='file' && user.isMember && user.role=='owner' && _.contains(['doc','','docx','xls','xlsx','ppt','pptx','tif','png'], extension) && (_.isEmpty(reservedById) || reservedById === user.id)", "invoke": { "method": "GET", "url": "http://www.example.com/ExampleCoSubmit.jsp?user={user.id}&ids=[{id},]&names=[{name},]" }, "multi": false }, { "id": "publishDirect", "name": "ACTION_PUBLISH_DIRECT_NAME", "description": "ACTION_PUBLISH_DIRECT_DESC", "type": "DIRECT", "trigger": "MENU", "presentation": { "view": "CLIENT",


8-5

"popupWidth": 500, "popupHeight": 100 }, "evaluate": "type=='folder' && user.isMember && user.hasPrivilegesAs(item, 'owner')", "invoke": { "method": "GET", "url": "http://www.example.com/ExampleCoMenuAction.jsp" }, "multi": false } ], "stringsMap": { "en": { "APP_SUBMIT_TO_PUBLISH_DOCS_NAME": "ExampleCo Publishing Technical Articles", "APP_SUBMIT_TO_PUBLISH_DOCS_DESC": "Submit an article for the ExampleCo technical knowledge base.", "ACTION_SUBMIT_TO_PUBLISH_NAME": "Publish", "ACTION_SUBMIT_TO_PUBLISH_DESC": "Submits the selected document for review and approval to ExampleCo publishing.", "ACTION_SHOW_PUBLISH_STATUS_NAME": "Select ExampleCo", "ACTION_SHOW_PUBLISH_STATUS_DESC": "Shows currently selected row info in ExampleCo Publishing", "ACTION_PUBLISH_DIRECT_NAME": "Audit", "ACTION_PUBLISH_DIRECT_DESC": "Sends an audit event to ExampleCo when document is selected" } }}

The Application Integration Framework supports simple use of the JavaScriptunderscore library (http://underscorejs.org); however, AIF does not allow definingfunctions as parameters of underscore functions.

The sections that follow describe the functional areas of the Application IntegrationFramework.

Functional Area Description

Application Properties Describes the application properties.

Action Command Describes the general elements of the action command. Use theaction command to specify how to trigger and start a task. Theinvoke and presentation components of the actioncommand are presented in their own sections.

Invoke Command Describes the elements of the invoke command. Use theinvoke command to call a third-party service, page, or script.

Presentation Command Describes the elements of the presentation command. Use thepresentation command to specify how the third-party contentretrieved by the invoke command is presented to the user.

Expressions Provides examples and general information about expressionsused with the invoke and evaluate commands.

Variables Provides descriptions of the available item and user variables, thepermissions and status objects, and AIF functions.

Localization Provides an example and general information about how tolocalize an app with translated labels and descriptions.


8-6

http://underscorejs.org

Application PropertiesThe following table shows the properties of an Application Integration Frameworkapplication.

Property Required Description

id Yes A non-empty string that uniquely identifies theapplication across Oracle Content and Experience.

name Yes A non-empty string that is displayed for the application’sweb user interface. It can also be a key that can betranslated using translation maps defined instringsMap.

description No A string that is displayed with the application name inthe web user interface. It can also be a key that can betranslated using translation maps defined instringsMap.

category No Category of the application. CUSTOM is the only allowedvalue. If you do not explicitly include category in theconfiguration file, it is dynamically added duringapplication configuration and is given the default valueof CUSTOM.

supportEmail No Email address of application support owner.

baseURL No Base URL used as a prefix to any relative URLsspecified in the application.

stringsMap No Used to map languages to translation objects, so thatkeys in the application definition can be translated to thecorresponding language.

info No Allows an integrator to show a dialog to displayinformation about the application. It contains presentation and invoke properties.

documentation No Lets you add comments in the file, such as a commentto identify the purpose of an action. You might add adocumentation property at the start of the codesample to describe the application itself.

tenantPrefs No Allows an integrator to expose application-level optionsin the preference settings. It contains presentationand invoke properties.

userPrefs No Allows an integrator to expose application-level optionsin the preference settings for users. It contains presentation and invoke properties.

actions Yes A collection of actions contained in the application. Itmust contain at least one action.

Action CommandUse the action command to specify how to trigger and start a specified task and howto present the results.

The following table shows the properties of an action command.

Chapter 8Application Properties

8-7


id Yes A non-empty string that uniquely identifies the action inthe application.

name Yes A non-empty string that is displayed for the action in theweb user interface. It can also be a key that can betranslated using translation maps defined instringsMap.

description No A string that is displayed for the action in a web userinterface tooltip. It can also be a key that can betranslated using translation maps defined instringsMap.

trigger No Specifies if the action is triggered through a contextmenu taskbar (MENU), or when the item is opened(SELECT). If you do not explicitly include trigger in theconfiguration file, it is dynamically added duringapplication configuration and is given the default valueof MENU.

In the Application Integration Framework, the SELECTtrigger occurs when an item is opened, not when simplychecked in a folder listing.

type No Specifies how action results are displayed to the enduser. Possible values are UI and DIRECT. If the value isDIRECT, a call is made to the URL specified withinvoke, and the response displays as a notification inthe Oracle Content and Experience web interface, ifpossible. If the value is UI, the presentation propertyspecifies the type of web interface to use.

presentation No Specifies the presentation to use if type is set to UI.Possible values are CLIENT to embed the action resultsin the integrations side panel on the right of the display,POPUP to display action results in a separate browserdialog, and WINDOW to display action results in a newbrowser window or tab. If type is set to UI andpresentation is omitted, it is added to the action withthe default value of CLIENT. See PresentationCommand.

multi No Specifies if the action applies when multiple items areselected (true) or not (false). If you do not explicitlyinclude multi in the configuration file, it is dynamicallyadded during application configuration and is given thedefault value of false.

evaluate Yes Must be valid JavaScript Boolean value that evaluatesto true or false for the selected item. For moreinformation about expression evaluation, see Expressions.

invoke Yes Specifies the external service in an invoke command touse when action is triggered. See Invoke Command.

Invoke CommandUse the invoke command to call an external service, page, or script.

Chapter 8Invoke Command

8-8

The following table shows the properties of the invoke command.


method Yes Specifies the HTTP method to use for invocation. Validvalues are GET, POST, PUT, DELETE, and HEAD.

url Yes A URL expression to specify the URL for the third-partyservice. It can be an absolute or relative URL. If arelative URL is specified, it will be added to the baseUrlof the application, if specified.

data No An expression that specifies data to be sent with theURL. See Expressions.

A JSON payload can added to the request body as astring object.

appLinkRole No If the action is a request to create an application link(applink), use appLinkRole to specify the role to usefor the applink. Valid values are contributor,downloader, and viewer.

header No A custom header to include when making POST calls.

token No Specifies if any special security token needs to bepassed. Valid values are PCS (PCS OAUTH token) andNONE.

Presentation CommandUse the presentation command to specify how the third-party content retrieved by theinvoke command is presented to the user.

The following table shows the properties of the presentation command.


view No Specifies how action response content is displayed tothe user. Use CLIENT to embed results in theapplication, POPUP to display results in a separatebrowser dialog, or WINDOW to display results in a newbrowser window or tab.

If you use CLIENT with the SELECT trigger, actionresults are displayed in the integrations side panel onthe right of the display. The integrations panel must beopen for the results to display. The SELECT triggeroccurs when an item is opened, not when simplychecked in a folder listing. If you use CLIENT with theMENU trigger, action results are displayed in a pop-updialog. If you do not explicitly include view in theconfiguration file, it is dynamically added duringapplication configuration and is given the default valueof CLIENT.

popupWidth No A number specifying the width of the container. If noneis specified, a default value is used, depending on thecontext.

Chapter 8Presentation Command

8-9


popupHeight No A number specifying the height of the container. If noneis specified, a default value is used, depending on thecontext.

ExpressionsThe invoke and evaluate commands accept expressions, which can include variablesand operators that are evaluated at runtime.

Invoke Expressions

An invoke expression is a template used to generate URL and data values at runtimeby replacing the variables specified in the template with their runtime values. Variablescan reference one or more selected items, information about the current user, andother system information.

• Anything enclosed in a brace { } is considered to be a key value that is mapped tothe corresponding attribute of a file, folder, or the currently signed-in user. Userattributes are prefixed by user.

For example, if John Smith is the current user, userid={user.name} resolves tothis:

userid=John Smith

• For multiselection, use the [repeated template separator] syntax. The repeatedtemplate is resolved for each selected item, and resolved strings for items areseparated by the specified delimiter.

For example, for items with GUIDs x189 and y234, item=[{id},] resolves to this:

item=x189,y234

Evaluate Expressions

An evaluate expression determines if the item or items selected by the user qualify fora particular action. The expression can contain zero or more variables that arereplaced with their runtime values before the expression is evaluated. This expressionmust be a valid JavaScript expression after all the values of the variables are replacedwith their values at runtime.

The expression must evaluate to true or false. If the result is true, the action is madeavailable as specified by the trigger property. If the result is false, the action is notmade available to the user.

For example, the following expression returns a true value only if all three conditionsevaluate to true: the item selected in the interface is a file, the user is signed in (notaccessing the file using a public link or applink), and the user is the owner of the file.

"evaluate": "type=='file' && user.isMember && user.role=='owner'

Antother example is item.meta.<custom property group name>.<custom propertygroup field name>.

Some commonly used JavaScript comparison and logical operators follow.

Chapter 8Expressions

8-10

Operator Description

== equal to

!= not equal to

> greater than

< less than

= greater than or equal to

<= less than or equal to

&& logical and

|| logical or

! logical not

VariablesYou can use variables in applications to dynamically provide information about thecurrent user, the currently selected item or items, and other types of information.Variables are evaluated at runtime when the application is used.

You can use a category prefix (item or user) with variable names to make therelationship explicit, especially in cases where variable names are the same, such asname. If a variable is not prefixed by any category, item is used as the category.

For example, to specify the folder or file name, use item.name. To specify the username, use user.name. If you specify name without the category, then item.name (thefolder or file name) is assumed.

Folder and File Item Variables

The following variables are specific to a folder or file item that is currently selected bythe user. Folder and file variables belong to the item category. The following table listsvariables that apply to both folder and file items.

Folder or FileVariable

Description

id Item GUID

name Item name

description Item description

type Item type

parentid Item parent ID

ownerId Item owner GUID

ownername Item owner name

creatorname Item creator name

createdat Date and time item was created

lastmodifierid GUID of the user who most recently modified the item

lastmodifiername Name of the user who most recently modified the item

modifiedat Date and time the item was last modified

Chapter 8Variables

8-11

Folder or FileVariable

Description

size Size of the item

permissions Actions the user is allowed to perform on the item

state State of the item

applink Applink created by AIF for this user to access the item, ifappLinkRole was specified in the invoke command

The appLink object has id, url, and accessToken properties thatcan be passed in the URL or data as {appLink.id},{appLink.url}, and {appLink.accessToken}, respectively.

favorite Whether the item is a favorite of the user or not

File-Item Specific Variables

The following variables are specific to a file item that is currently selected by the user.File variables belong to the item category. The table lists variables that apply to fileitems only.

File Variable Description

originalname Original name of the item

extension Extension of the item

revision Item’s revision

mimetype Mime type of the item

reservedbyid GUID of the user who reserved the item

reservedbyname Name of the user who reserved the item

reservedat Date and time when the item was reserved

isreservedbyanotheruser Whether the item is reserved by a user other than the current user

Item Permissions

Permissions is a JSON object that you can query to determine the permissionsassociated with an item. The properties return a Boolean value.

PermissionProperties

Description

annotationDelete User has delete permission for annotations on the item.

annotationRead User has read permission for annotations on the item.

annotationUpdate User has update permission for annotations on the item.

annotationWrite User has write permission for annotations on the item.

directShareDelete User has delete permission for the item shared with the user.

directShareRead User has read permission for the item shared with the user.

directShareUpdate User has update permission for the item shared with the user.

directShareWrite User has write permission for the item shared with user.

fileDelete User has delete permission for the file.

Chapter 8Variables

8-12

PermissionProperties

Description

filePreview User has preview permission for the file.

fileRead User has read permission for the file.

fileUpdate User has update permission for the file.

fileWrite User has write permission for the file.

folderDelete User has delete permission for the folder.

folderPreview User has preview permission for the folder.

folderRead User has read permission for the folder.

folderUpdate User has update permission for the folder.

folderWrite User has write permission for the folder.

linkShareDelete User has delete permission for the item shared with the user through alink.

linkShareRead User has read permission for the item shared with the user through alink.

linkShareUpdate User has update permission for the item shared with the user througha link.

linkShareWrite User has write permission for the item shared with the user through alink.

Item State

State is a JSON object that you can query to determine certain states of an item. Theproperties return a Boolean value.

State Property Description

isAnnotated The item has annotations.

isAnnotatedLatest The item has the most recent annotations.

isLinked The item has named sharing links defined for it.

isShared The item is directly shared with specified users.

isSyncd The item is included in the content synced through the desktop client.

isInTrash The item is currently in the trash.

User Variables

The following variables are relative to the current user or session, or both.

Variable Description

id User’s GUID

name User’s name

loginname User’s sign in name

email User’s email address

timezone User’s time zone

Chapter 8Variables

8-13


ismember Returns true if the user is not accessing an item through public link orapp link and false otherwise

ispubliclink Returns true if the user is accessing the item through a public link andfalse otherwise

isapplink Returns true if the user is accessing the item through an applink andfalse otherwise

role Current user's role for an item

hasprivilegesas Specified with a user role as a string argument to determine if the userhas the specified role

API Functions

Use the following utility functions with evaluate or invoke expressions to returninformation about a specified item.


isReservedByAnotherUser(item) Returns true if the item is reserved by another user, orreturns false otherwise

hasPrivilegesAs(item, role) Returns true if the user has role privileges for the item, orreturns false otherwise

getUserRole(item) Returns the user’s role for the item

LocalizationUse the stringsMap element to provide localized versions of labels and descriptionsused in the integration.

The following example shows sample application and action names and descriptionsin English and German.

"stringsMap": { "en": { "APPLICATION_NAME": "Localization Test", "APPLICATION_DESCRIPTION": "This example provides translated content.", "ACTION1": "Action1", "ACTION2": "Action2", "ACTION1DESC": "Action1 description", "ACTION2DESC": "Action2 description" }, "de": { "APPLICATION_NAME": "Lokalisierung Beispiel", "APPLICATION_DESCRIPTION": "Dieses Beispiel liefert übersetzten Inhalte.", "ACTION1": "Aktion1", "ACTION2": "Aktion2", "ACTION1DESC": "Aktion1 Beschreibung", "ACTION2DESC": "Aktion2 Beschreibung" }

Chapter 8Localization

8-14

9Use Content Connectors

You can use content connectors to connect to third-party content repositories, such asGoogle Drive or Dropbox, and import content from the repository into Oracle Contentand Experience.

When you set up a content connector to use in Oracle Content and Experience, youcan get values for the custom fields for Oracle WebCenter Content as well as anumber of third-party services, including Google Drive, Dropbox, OneDrive, andYouTube.

The following sections describe how to set up these content connectors.

• Enable a Content Connector

• Disable a Content Connector

• Configure a Google Drive Content Connector

• Configure a Microsoft OneDrive Content Connector

• Configure a Dropbox Content Connector

• Configure a YouTube Content Connector

• Configure WebCenter Content and Oracle Content and Experience for the WCCConnector

• Create and Configure a Custom Content Connector

• Provide Configuration Parameter Values for a Content Connector

• Delete a Content Connector

Enable a Content ConnectorOracle Content and Experience provides preconfigured content connectors for GoogleDrive, Microsoft OneDrive, Dropbox, WebCenter Content, and YouTube. A serviceadministrator can enable any or all of these through the Administration Integrationsweb interface.

9-1

To enable a preconfigured content connector:

1. Sign in to the Oracle Content and Experience web interface as an administrator ordeveloper.

2. Click Integrations in the Administration area of the navigation menu.

3. In the Integrations menu, choose Content Connectors.

4. Click Enable next to the content connector you want to enable.

5. Change the information and settings as necessary:

• Name: You can change the default content connector name to a user-friendlyname.

• Description: You can change or add the description.

• Connector service URL: This read-only field becomes editable if the URLcan’t connect to the service. Once the URL can connect, it displays as readonly again.

• Redirect URL: Make note of the redirect URL in this read-only field. You'llneed to specify the URL later for the content connector configuration.

• Accept self-signed certificate: Select this option if you will accept acertificate signed by the third-party provider.

• User name: Enter your administrator user name.

• User password: Enter your administrator password.

• Connector tags: You can assign tags that will be applied to assets pulledfrom the content connector (for example, the content connector name). Thislets you search for all items from that content connector in an asset repository.

• Enabled for end users: To enable the content connector, select this checkbox, or deselect it to disable the content connector.

6. Enter custom field values on the Custom Fields tab. For information about how toget the values for the custom fields, see Configure a Google Drive ContentConnector, Configure a Dropbox Content Connector, Configure a MicrosoftOneDrive Content Connector, Configure a YouTube Content Connector, or Configure WebCenter Content and Oracle Content and Experience for the WCCConnector.

7. Click Save.

After a content connector is configured to connect to a third-party content provider, youcan enable it by clicking Enable next to the connector on the Content Connectorspage.

Disable a Content ConnectorA service administrator can use the connector framework to disable a contentconnector in an Oracle Content and Experience instance at any time.

To disable a content connector:



Chapter 9Disable a Content Connector

9-2


4. Click Disable next to the content connector you want to disable.

After a content connector is disabled, it's no longer available on the Add From drop-down menu on the Assets page, until it is enabled again. You can now click theEnable button to enable the content connector again.

Configure a Google Drive Content ConnectorAfter you configure and enable a Google Drive content connector, you can connect toGoogle Drive and pull required content from it into Oracle Content and Experience.

To configure a Google Drive content connector:

1. Get the Oracle Content and Experience host name and authorization URL details.

a. Sign in to Oracle Content and Experience as an Administrator or Developer.

b. Click Integrations in the Administration area of the navigation menu on theleft.

c. In the Integrations menu, choose Content Connectors.

d. Click the checkbox next to the Google Drive content connector.

e. Click Create.

f. On the General tab, note the Redirect URL, which will be in this format:

https://<hostname>.<domainname>.com:<port>/documents/web/AR_COMPLETE_AUTHORIZATION

The Redirect URL field is truncated. Double-click the field to copy the value toyour clipboard.

2. Create a Google Drive app:

a. Go to https://console.developers.google.com/project in a browserwindow.

b. Sign in with a Google user name and password.If you've already created projects in the Google Developers Console, you willsee the list of created projects. If not, the Manage resources screen willappear.

c. Click Create Project.You’ll be redirected to a page where you can enter Project Name and ProjectID values to help you recognize your project in the console.

d. Click Create.Your project will be created, and you'll be redirected to your projects list in theconsole.

e. Go to the dashboard through menu navigation, APIs & Services >Dashboard, from the left corner icon.

f. Click the name of the project you recently created to go to your projectdashboard.

g. Select a library. Go to Library page through menu navigation, APIs &Services > Library, from the left corner icon.

Chapter 9Configure a Google Drive Content Connector

9-3

h. Search for the "Google Drive API" library, then select and enable it.

i. Search for the "Google Picker API" library, then select and enable it.

j. From the left corner icon, navigate to APIs & Services > Credentials >OAuth Consent Screen tab. Check your email address and enter yourproduct name, GDrivePickerApp, and save it.

k. Click the Credentials tab to open a popup in which you can select an OAuthclient ID option under the Create credentials select box.

l. Select your application type, Web application.

m. Name the client and add the Authorized redirect URIs.

i. In Authorized redirect URI, paste the redirect URL you copied fromOracle Content and Experience.The redirect URI must be the same as your application installation URL.

ii. In Authorized Javascript Origins, paste the redirect URL, but removeeverything after the port.If you get the message "Invalid Origin", click the authorized domains listand add your domain.

iii. Press ENTER, and then click Save.

Once you have added to the authorized domains, you should be able to createan OAuth ID. Note the values of Client ID and Client Secret.

3. Create credentials to get the API key (Developer Key). Click Create Credentialsand then API key in the drop-down menu. Note the value of API Key. This is theDeveloper Key you'll enter in the Oracle Content and Experience when youconfigure the Google Drive connector.

4. Get the App ID.

a. From the left corner icon, navigate to IAM & admin > Settings.

b. From that page note the value of Project Number. This is the App ID you'llenter in the Oracle Content and Experience when you configure the GoogleDrive connector.

5. Configure the connector in Oracle Content and Experience.

a. Go back to configuring the Google Drive content connector in Oracle Contentand Experience.

b. On the General tab:

• Select whether you'll accept a self-signed certificate.

• In the Connector tags field, you can assign tags that will be applied toassets pulled from the content connector (for example, the contentconnector name). This lets you search for all items from that contentconnector in an asset repository.

• Make sure Enabled for end users is selected.You can review the Terms of use and Privacy Policy below the Enablefor end users button.

c. Click the Custom Fields tab, and enter the following information:

• Client ID

• Client Secret

• Developer Key (API Key)

Chapter 9Configure a Google Drive Content Connector

9-4

• App Id (Project Number)

d. When you're done, click Save.

6. Associate the connector with one or more asset repositories.

a. Click Assets in the Administration area of the navigation menu on the left.

b. Open an existing repository or click Create to create a new one.

c. If you're creating a new repository, specify the repository name, publishingchannels, languages, and other options.

d. Under Connectors, select one or more connectors to associate with therepository.This menu lists all the content connectors that have been configured andenabled in your Oracle Content and Experience instance.

If any of the connectors you select have content types associated with them,the types appear under Content Types.

After a Google Drive content connector is enabled, configured, and associated with arepository, it's available in the asset repository for Oracle Content and Experienceusers to import content, through the Add drop-down menu, Import from GoogleDrive option on the Assets page.

Configure a Microsoft OneDrive Content ConnectorAfter you configure and enable a Microsoft OneDrive content connector, you canconnect to OneDrive and pull required content from it into Oracle Content andExperience.

To configure a OneDrive content connector:





d. Click the checkbox next to the OneDrive content connector.

e. Click Create.




2. Create a OneDrive app:

a. Sign in to the Microsoft developer console at https://apps.dev.microsoft.com using a Microsoft user name and password:

b. Click Add an app.

Chapter 9Configure a Microsoft OneDrive Content Connector

9-5

c. Enter an application name, and click Create. The sampleApp Registrationscreen is displayed.

d. Under Properties, type a name for your application.

e. Note the Application id value.

3. Add a web platform.

a. Under Platforms, click Add Platform.

b. In the Add Platform popup, click Web.

c. In the Add Platforms dialog box under Platforms, click Add URL, and pastethe redirect URL you copied from Oracle Content and Experience.

d. Click Save.

e. Under Microsoft Graph Permissions, you can add Delegated Permissionsand Application Permissions.The default permission is User.Read. There's no need to change that forOneDrive content connector integration with Oracle Content and Experience.

You need to add the following permissions in Microsoft Graph Permissions:Files.ReadWrite, offline_access along with the existing User.Readpermission.

4. Generate a password.

a. Under Application Secrets, click Generate a New Password.

b. Note the password, which will not be displayed again.

c. Click Ok.

The password needs to be generated after you add the URL. More than onepassword can be generated for an app. All passwords will work.

5. Configure the connector in Oracle Content and Experience:

a. Go back to configuring the OneDrive content connector in Oracle Content andExperience.






• Client ID (the value of Application id that you noted down earlier)

• Client Secret (the value of the generated password)




Chapter 9Configure a Microsoft OneDrive Content Connector

9-6





After a OneDrive content connector is configured, enabled, and associated with arepository, it's available in the asset repository for Oracle Content and Experienceusers to download content, through the Add drop-down menu, Import from MicrosoftOneDrive option on the Assets page

Important:

An authorized application for a OneDrive content connector must provide alink to https://account.live.com/consent/Manage, or to another locationspecified for an OCS OneDrive content connector, with a clear indication thatend users can go to that Microsoft site to revoke permissions at any time. Ifend users must take additional steps to disable the authorized application'saccess to end-user information, then the application must clearly indicate toend users the additional steps required to disable access. Theserequirements do not apply where Microsoft provides the end-user webinterface.

Configure a Dropbox Content ConnectorAfter you configure and enable a Dropbox content connector, you can connect toDropbox and pull required content from it into Oracle Content and Experience.

To configure a Dropbox content connector:





d. Click the checkbox next to the Dropbox content connector.

e. Click Create.




Chapter 9Configure a Dropbox Content Connector

9-7

2. Create a Dropbox app:

a. Go to https://www.dropbox.com/developers/apps in a Browser window

b. Sign in with a Dropbox user name and password.

c. Go to My apps.

d. Click Create App, and on next screen, in Step 1, choose a Dropbox API.

e. Choose an access type and name for your application, and click Create App.For production deployment of the Dropbox app, refer to Dropboxdocumentation for the approval required: https://www.dropbox.com/developers/reference/developer-guide#production-approval.

f. After the app is created, you can add or configure additional values on thenext screen.

g. Note the values of App key and App secret.

3. In the OAuth 2 - Redirect URIs section, paste the Redirect URL you copied fromOracle Content and Experience.

4. On the Dropbox App page, navigate to the lower section, Chooser/Saverdomains, and add the host name used to access Oracle Content and Experienceto this section.

5. Configure the connector in Oracle Content and Experience.

a. Go back to configuring the Dropbox content connector in Oracle Content andExperience.






• App key

• App secret







Chapter 9Configure a Dropbox Content Connector

9-8


After a Dropbox content connector is configured, enabled, and associated with arepository, it's available in the asset repository for Oracle Content and Experienceusers to download content, through the Add drop-down menu, Import from Dropboxoption on the Assets page.

Configure a YouTube Content ConnectorAfter you configure and enable a YouTube content connector, you can connect toYouTube and pull required content from it into Oracle Content and Experience.

To configure a YouTube content connector:





d. Click the checkbox next to the Youtube content connector.

e. Click Create.

f. You can override the default content connector settings, as described in Enable a Content Connector.You do not need to select the Accept self-signed certificate option.

2. Enter any name and give the Connector Service URL.

3. Click Verify Settings.This lists the custom fields of the YouTube content connector.

In the Connector Tags field, you can assign tags for assets that the contentconnector pulls into Oracle Content and Experience.

4. Sign in to https://console.developers.google.com/project and create credentials toget the API key (Developer Key). Click Create Credentials and then API key inthe drop-down menu. Note the value of API Key. This is the Developer Key you'llenter in Oracle Content and Experience when you configure the YouTubeconnector.

5. Specify a value for Application Name, which can be anything.

6. Click Save.

7. Make sure Enabled for end users is selected.You can review the Terms of use and Privacy Policy below the Enable for endusers button.

8. Map source metadata to content types for the connector.When you configure a content connector, you can do field mapping from sourcemetadata to content type fields. A repository administrator or system administratorcan allow creation of content types for a connector. You can create content typeson the Mappings tab of the Connector Settings page. To map source metadatato a content type:

a. Sign in to Oracle Content and Experience as a system administrator and clickIntegrations under Administration in the left navigation menu.

Chapter 9Configure a YouTube Content Connector

9-9

https://console.developers.google.com/project

b. On the Assets page, click Create.

c. On the Create Repository page, define your repository.

i. Specify the connector name, publishing channels, languages, and otheroptions.

ii. Under the Connectors option, select Youtube from the drop-down menuto associate the YouTube content connector with the repository.If the YouTube connector has content types associated with it, the typesappear under the Content Types option. If you want the contentconnector to have additional fields, you can add them on the Mappingstab of the Connector Settings page.

If the Allow Content Type Creation checkbox on the General tab isselected, the mapping of source metadata to Oracle Content andExperience content types will be automatically populated. You can changethe automatic mapping on the Connector Settings page.

d. If the Allow Content Type Creation checkbox on the General tab is notselected, you need to map the source metadata to Oracle Content andExperience content types on the Connector Settings page:

i. On the Mappings tab, choose a source type from the Source ContentType drop-down menu and an Oracle Content and Experience type fromthe OCE Content Type drop-down menu, such as YoutubeVideos, tomap the Source Data Field to the Target Data Field.

ii. Repeat for each source content type.

iii. Click Save.

iv. Enable a Content Connector.This type mapping must be done for all source types before the contentconnector is enabled. If you want to change the mapping, you need todisable the connector, make your changes, and then enable the connectoragain. Whenever an administrator saves the connector after modifying acontent type, the connector framework will attempt to seed the contenttype again. If you remove any associated content type that is required forthe selected connector, the save will fail.

9. Create Content Items.See Use Structured Content in Creating Experiences with Oracle Content andExperience.



b. Open an existing repository, or click Create to create a new one.

c. If you're creating a new repository, specify the repository name, publishingchannels, languages, and other options. You need to configure the languagesthat are expected from the connector. For example, some of the languagesthat YouTube supports are en, en-CB, and en-AU. If these are not configured,content item creation may fail.

d. Under Connectors, select Youtube to associate the YouTube contentconnector with the repository.This menu lists all the content connectors that have been configured andenabled in your Oracle Content and Experience instance.

Chapter 9Configure a YouTube Content Connector

9-10


Configure WebCenter Content and Oracle Content andExperience for the WCC Connector

An administrator can configure WebCenter Content (WCC) and Oracle Content andExperience for the WCC content connector so site users can pull content from theWebCenter Content Server into their sites.

Map Source Metadata to Content Types for a WCC ConnectorWhen you create a WCC content connector in Oracle Content and Experience, youcan do field mapping from source metadata to content type fields.

A repository administrator or system administrator can allow creation of content typesfor a content connector.

You can create content types for a connector on the Mappings tab of the ConnectorSettings page.

To map source metadata to a content type:

1. Sign in as a system administrator in your browser and click Integrations underAdministration in the left navigation menu.

2. On the Assets page, click Create.

3. On the Create Repository page, define your repository.

a. Specify the connector name, publishing channels, languages, and otheroptions.

b. Under the Connectors option, select one or more connectors from the drop-down menu to associate with the repository.

This menu lists all the content connectors that have been configured in yourOracle Content and Experience instance, such as Google Drive, andWebCenter Content.

If any of the connectors you select have content types associated with them,the types appear under the Content Types option. If you want the contentconnector to have additional fields, you can add them on the Mappings tab ofthe Connector Settings page.

If the Allow Content Type Creation checkbox on the General tab is selected,the mapping of source metadata to Oracle Content and Experience contenttypes will be automatically populated. You can change the automatic mappingon the Connector Settings page.

4. If the Allow Content Type Creation checkbox on the General tab is not selected,you need to map the source metadata to Oracle Content and Experience contenttypes on the Connector Settings page:

a. On the Mappings tab, choose a source type from the Source Content Typedrop-down menu and an Oracle Content and Experience type from the OCEContent Type drop-down menu, to map the Source Data Field to the TargetData Field.

Chapter 9Configure WebCenter Content and Oracle Content and Experience for the WCC Connector

9-11

b. Repeat for each source content type.

c. Click Save.

d. Enable the connector.

See Enable a Content Connector.

This type mapping must be done for all source types before the content connectoris enabled. If you want to change the mapping, you need to disable the connector,make your changes, and then enable the connector again. Whenever anadministrator saves the connector after modifying a content type, the connectorframework will attempt to seed the content type again. If you remove anyassociated content type that is required for the selected connector, the save willfail.

Create and Configure a Custom Content ConnectorAfter you create and configure a custom content connector, you'll be able to connect itto a third-party content repository and import content from the repository into OracleContent and Experience.

To create and configure a custom content connector:

1. Create an app for the custom content connector. See Develop ContentConnectors.

2. Create the connector in Oracle Content and Experience.




d. Click Create.

e. On the Connector Settings page, provide information for registration of yourcustom content connector. If you will accept a certificate signed by the third-party provider, select Accept self-signed certificate.

f. Click Next. Once the details are verified, the Custom Fields tab will appear.

g. Click the Custom Fields tab, and configure the custom fields that weredefined for your content connector.Custom properties are connector-specific. Every connector has its ownrequirement to connect to a remote store; for example, one connector mightneed just ClientID and ClientSecret, while another might require ClientID,ClientSecret, AppID, and so on.

h. If the connector's picker type is CUSTOM, the following fields are displayedunder the Connector Tags field:

• Custom Picker URL: Provide the name of the custom picker packaged inyour content connector, if any. This setting is not applicable when you usethe common web user interface.If your content connector is deployed on an instance that uses a self-signed certificate, the picker launched from Oracle Content andExperience will show an error as it is launched in an iframe. You mustlaunch the picker URL in a new browser tab, accept the certificateexplicitly, and then launch the URL from Oracle Content and Experience.

Chapter 9Create and Configure a Custom Content Connector

9-12

• Hide OK/Cancel: This setting indicates whether or not you want OracleContent and Experience to embed your picker in their dialog. Leave thissetting unchecked if you use the common web user interface.

3. When you're done, click Save.

4. If your custom content connector is of type METADATA and you want to mapsource metadata to content type fields, either manually or to edit the automaticmappings, click the Mappings tab. You must, map content types and metadatabefore enabling the connector.

5. On the Content Connectors page, click Enable next to the custom contentconnector you created.







Create Content Types for a ConnectorA repository administrator or system administrator can allow creation of content typesfor a content connector.

You can create content types for a connector on the Mappings tab of the ConnectorSettings page.

Map Source Metadata to Fields in a Content TypeThe WebCenter Content connector and some custom content connectors (connectorswith type METADATA) allow you to map source metadata to Oracle Content andExperience content type fields.

Typically a source system has metadata associated with each content file. When youimport a content file to an asset repository, you can use that source metadata topopulate the fields in a content item, such as an employee record.

You can have the connector automatically create a content type for the contentimported through a connector, with each piece of source metadata automaticallymapped to a field in the content type. You can also customize the automatic mappingsor map your own content type to the source content type. If you want to use your owncontent type, you must create it before creating mappings in the connector.

If your source content repository has multiple content types, you can select a differentOracle Content and Experience content type to map to each source type.

Content type and field mapping must be done for all source types before the contentconnector is enabled. If you want to change the mappings, you need to disable the

Chapter 9Create and Configure a Custom Content Connector

9-13

connector, make your changes, and then enable the connector again. Whenever anadministrator saves the connector after modifying a mapping, the connector frameworkwill attempt to seed the content type again. If you remove any associated content typethat is required for the selected connector, the save will fail.

To map source metadata to fields in a content type:

1. Sign in to Oracle Content and Experience as an Administrator or Developer.

2. Click Integrations in the Administration area of the navigation menu on the left.


4. Click Configure next to the connector you want to add mappings to.

5. If you want to automatically create a content type for imported content, withcontent type fields that are automatically mapped to the source metadata, selectAllow content type creation. You can change the automatic mappings on theMappings tab.

6. To create manual mappings or to edit the automatic mappings, click the Mappingstab:

a. Select a Source Content Type, then select the Oracle Content andExperience content type you want to map to it.

b. Map each Source Data Field to a Target Data Field.

c. Repeat for each source content type.

7. When you're done, click Save.

Provide Configuration Parameter Values for a ContentConnector

A service administrator can register a content connector on the cloud storageprovider’s website to get configuration parameter values to enter for the contentconnector in Oracle Content and Experience.

Only one set of user credentials is stored for a signed-in Oracle Content andExperience user. If you need to use a separate user to fetch data, use ManageSources and revoke the authorization for the existing user. Then you can usecredentials for a second user.

Before you configure the content connector in Oracle Content and Experience, youneed to get custom field information from the third-party content repository's website(such as Google Developers) by registering the content connector as an applicationthat you want to integrate.

Here's the information you'll need for the various content connectors:

• Google Drive: Client ID, Client Secret, Developer Key, and App Id

• Microsoft OneDrive: Client ID and Client Secret

• Dropbox: App Key and App Secret

• WebCenter Content: WebCenter Content Server JAX-WS Connection URI,WebCenter Content Server JAX-WS Client Policy, and WebCenter Content ServerWeb Context Root


Chapter 9Provide Configuration Parameter Values for a Content Connector

9-14


3. Click the Configure button next to a content connector.

4. Click the Custom Fields tab, and enter the information you collected from thethird-party content repository's website.

5. Click Save to save the configuration parameter values.

After a content connector is configured and enabled, it's available in the assetrepository for Oracle Content and Experience users to download content, through theAdd From drop-down menu on the Assets page.

Delete a Content ConnectorA service administrator can delete a disabled custom content connector in an OracleContent and Experience instance at any time.

You cannot delete a preconfigured content connector. You can delete only newlyadded content connectors (custom content connectors).

To delete a content connector:



3. If the content connector is enabled, click Disable next to it.

4. Click Delete next to the custom content connector.

Chapter 9Delete a Content Connector

9-15

10Develop Content Connectors

You can use the Oracle Content and Experience connector framework to develop yourown content connectors to bring content you have already created elsewhere intoOracle Content and Experience, manage it centrally, and use it in new experiencesacross multiple channels.

The Oracle Content and Experience connector framework enables you to bringcontent you have already created elsewhere into Oracle Content and Experience,manage it centrally, and use it in new experiences across multiple channels.

Part of Oracle Content and Experience, the connector framework integrates withremote content stores to let you bring content into Oracle Content and Experience aseasily as uploading files from your desktop. You can plug in any type of content storeto Oracle Content and Experience, making it a content hub.

The connector framework abstracts the functionality that is provided and implementedby end connectors. It does so by providing the REST API interface to configure acontent connector as well as to call content-related APIs on the end store, likebrowsing the remote file system and copying the files from a remote store to OracleContent and Experience.

The following sections describe how to develop custom content connectors:

• Connector REST API Interface

• Connector SDK

• Build a New Content Connector

• Content Connector Configuration and Registration

• Content Connector Execution Flow

• Pexels Content Connector Sample Implementation

• Download the CEC Content Connector Sample and SDK

Connector REST API InterfaceYou can deploy and run content connectors anywhere and implement them with anytechnology stack, as long as they can be called from Oracle Content and Experiencethrough REST APIs.

Content connectors are deployable binaries that use Restful services for the remotestores implementing the REST interfaces (SPIs/SDK) defined by Oracle Content andExperience. They internally use cloud store native SDKs to connect to remotesystems.

Connector SDKTo help you build a new content connector, Oracle Content and Experience providesthe Connector SDK

10-1

This SDK contains:

• A javadoc

• A JAR file containing DTO and REST interfaces

• The connector.yaml file, which documents the REST APIs and the payloads

The Connector SDK is in the cec-connector-sdk.zip file.

Build a New Content ConnectorTo build a new content connector as a Restful service, a developer needs toimplement the Restful interfaces provided by the connector framework.

The Oracle Content and Experience connector framework has the following interfaces.

• APIResource Interface: This interface is the starting point of the contentconnector. You simply return the version that's supported.

• ServerResource Interface: When a developer or administrator registers acontent connector in the Oracle Content and Experience server, Oracle Contentand Experience calls this service to get the basic details about the connectorserver, such as these:

– Authorization type:

* OAUTH: If the remote cloud store supports 3-legged OAuth authentication

* BASIC_AUTH: If the remote cloud store supports Basic authentication

Note:

Oracle no longer supports Basic authentication for generalconsumption.

* NO_AUTH: If the remote store doesn’t require any authentication

– Picker type: Oracle Content and Experience supports the Oracle Content andExperience generic picker to list the file system. If the content connectorsupports the native picker, then the content connector implementer canimplement JavaScript APIs to integrate that picker with the Oracle Content andExperience UI. The picker type can be one of three values:

1. COMMON, using the common UI

2. CUSTOM, using a custom UI

3. NATIVE, using a native UI like Google Drive or Microsoft OneDrive

– Also use this Interface to define custom fields for the content connector.Custom properties are connector specific, so the connector framework can’tprovide such a properties list by itself. Every content connector has its ownrequirement to connect to a remote store; for example, one content connectormight need just ClientID and ClientSecret, while another might requireClientID, ClientSecret, AppID, and so on. Each content connector canprovide a custom properties list to the Oracle Content and Experience serverby ServerResource. If any of these properties need to be filled in by adeveloper or administrator during configuration, the connector framework willsurface them in the administration UI.

Chapter 10Build a New Content Connector

10-2

This service will be called only once, at the time of registration.

• AuthorizationResource Interface: Used to complete the authorization beforecontent from the remote store can be copied to the Oracle Content andExperience repository. This interface has support for both OAuth and Basicauthentication protocols.

– 3-legged OAuth authentication

* In the OAuth flow, the Oracle Content and Experience UI, based on thecustom property value provided by the content connector, supports OAuthauthentication. It triggers an OAuth flow by calling the connectorframework, which in turn calls the /authorization/authorization URLsservice on the content connector to get the authorization URL.

* The Oracle Content and Experience UI renders the authorization URL in abrowser, where the user authorizes the application and gives OracleContent and Experience permission to access the token for furthercommunication. To complete the authorization and get the OAuth token,the Oracle Content and Experience server will call the /authorization/completedAuthorizations service on the content connector. To complete3-legged OAuth, the Oracle Content and Experience server also providesthe redirect callback servlet, which the remote store will call to completethe authorization process.

– Basic authentication: In case the content connector supports Basicauthentication, the Oracle Content and Experience UI will prompt the user toenter a user name and password, which it will pass to the Oracle Content andExperience server (connector framework). The connector framework will callthe /authorization/ basicAuthorization service to pass the credentialsand will expect the content connector to validate with the remote store if thecredentials are correct.

• FileSystemResource Interface: The connector framework supports the genericfile picker, which can be used by content connectors to render the file-systeminformation for a user to browse the files. But, the content connector needs toimplement the /filesystem service to use this functionality. Highlights of thisservice follow:

– The user can browse the file system like any other file picker; for example, theGoogle Drive or Microsoft OneDrive picker.

– This supports pagination.

– The user can also specify the search criteria to get the filtered result.

• ContentResource Interface: The connector framework uses the service /content to get the actual content (the bytes of the files) stored in the cloud store.

This service returns javax.ws.rs.core.Response as a response, and theresponse entity is the content of the file. The response should include the followingheaders:

– Content-Length: Set to the entity length, or -1 if unknown.

– Content-Type: Set to the content type, or application/octet-stream if amore accurate type is not possible.

– Content-Disposition: Set to the disposition type of attachment, and includesa filename parameter (for example, Content-Disposition: attachment;filename="meeting agenda.doc"). Note that file names with spaces must be


10-3

in quotation marks. See RFC 6266 for details about the format and encodingof the header.

Each of these interfaces is described in more detail, with examples of REST payloads,in the following sections:

• REST Interfaces for Configuration, Authorization, and Fetching Content

• REST Interfaces for File System Browsing and Searching

• Content Picker

• Authorization

REST Interfaces for Configuration, Authorization, and FetchingContent

A content connector needs to implement he following REST APIs for defining theconnector configuration, setting up authorization, and fetching content.

/rest/api

Implements intradoc.connectorcommon.server.APIResource

Here you return the latest version supported by the content connector.

GET http://host:port/connector/rest/api

[ "v1"]

/rest/api/v1/server

Implements intradoc.connectorcommon.server.ServerResource

This returns information about the content connector configuration, like theauthentication type, picker type, and custom fields it exposes.

GET http://host:port/connector/rest/api/v1/server

{ "name": "Pexels Connector", "nameLocalizations": [ { "locale": "en", "localizedString": "Pexels Connector" } ], "version": " (, , )", "about": "Pexels Connector.<br>Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved.", "aboutLocalizations": [ { "locale": "en", "localizedString": "Pexels Connector.<br>Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved." } ],


10-4

"authenticationType": "NO_AUTH", "pickerType": "CUSTOM", "enableMultiUserCopyBack": false, "maxUploadSize": 1073741824, "fields": [ { "ID": "ProxyHost", "datatype": "STRING", "siteSettable": true, "userSettable": false, "connectorSettable": false, "authorizationURLParameter": false, "label": "HTTP Proxy Hostname", "labelLocalizations": [ { "locale": "en", "localizedString": "HTTP Proxy Hostname" } ], "description": "The HTTP proxy hostname, leave blank to disable.", "descriptionLocalizations": [ { "locale": "en", "localizedString": "The HTTP proxy hostname, leave blank to disable." } ], "required": false }, { "ID": "ProxyPort", "datatype": "STRING", "siteSettable": true, "userSettable": false, "connectorSettable": false, "authorizationURLParameter": false, "label": "HTTP Proxy Port", "labelLocalizations": [ { "locale": "en", "localizedString": "HTTP Proxy Port" } ], "description": "The HTTP proxy port number, leave blank to default to port 80.", "descriptionLocalizations": [ { "locale": "en", "localizedString": "The HTTP proxy port number, leave blank to default to port 80." } ], "required": false },


10-5

{ "ID": "ProxyScheme", "datatype": "STRING", "siteSettable": true, "userSettable": false, "connectorSettable": false, "authorizationURLParameter": false, "label": "HTTP Proxy Scheme", "labelLocalizations": [ { "locale": "en", "localizedString": "HTTP Proxy Scheme" } ], "description": "The HTTP proxy scheme, leave blank to default to http.", "descriptionLocalizations": [ { "locale": "en", "localizedString": "The HTTP proxy scheme, leave blank to default to http." } ], "required": false }, { "ID": "ClientID", "datatype": "STRING", "siteSettable": true, "userSettable": false, "connectorSettable": false, "authorizationURLParameter": false, "label": "Client ID", "labelLocalizations": [ { "locale": "en", "localizedString": "Client ID" } ], "description": null, "descriptionLocalizations": [], "required": true } ], "supportedConnectorTypes": [ "COPY" ], "proprietorName": "", "serviceProviderName": "Pexels", "nativeAppInfos": null}

/rest/api/v1/authorization/authorizationURLs

Implements intradoc.connectorcommon.server.AuthorizationResource


10-6

This is required only if the content connector supports OAuth.

It returns the authorization URL to which the browser will redirect to invoke the Oauthflow where the user provides credentials and authorizes the access. The redirect URLpassed in the payload is what the OAuth provider will redirect to with temporary code.

POST http://host:port/connector/rest/api/v1/authorization/authorizationURLs

HeadersContent-Type:application/jsonX-CEC-ClientID:client-idX-CEC-ClientSecret:client-secretX-CEC-ProxyHost:proxy-hostX-CEC-ProxyPort:80X-CEC-ProxyScheme:http Payload{"redirectURL":"http://host:port/documents/web/AR_COMPLETE_AUTHORIZATION"} Response{ "authorizationURL": "https://domain/oauth/authorize?response_type=code&client_id=id://host:port/documents/web/AR_COMPLETE_AUTHORIZATION", "fieldValueMap": null}

/rest/api/v1/authorization/completedAuthorizations


This is required only if the content connector supports OAuth.

This is called to complete the second part of the OAuth flow, where the code obtainedfrom the OAuth provider in the previous step is passed along with the client ID andsecret to obtain the access token and refresh token along with expiry times. Thisinformation is then returned to Oracle Content and Experience, which stores itsecurely against the signed-in user.

POST http://host:port/connector/rest/api/v1/authorization/completedAuthorizations

HeadersContent-Type:application/jsonX-CEC-ClientID:client-idX-CEC-ClientSecret:client-secretX-CEC-code:codeX-CEC-ProxyHost:proxy-hostX-CEC-ProxyPort:80X-CEC-ProxyScheme:httpContent-Type:application/json Payload{"redirectURL":"http://host:port/documents/web/AR_COMPLETE_AUTHORIZATION"}


10-7

Response{ "authorized": true, "authorizedUserDisplayName": null, "authorizedUserEmailAddress": null, "authorizedUserPictureURL": null, "fieldValueMap": { "RefreshToken": "refresh-token", "AccessToken": "access-token" }}

/rest/api/v1/authorization/basicAuthorization


This is required only if the content connector supports BASIC authorization. Here thesign in credentials are passed in the headers where the password field is base64encoded. It is always recommended that a content connector be deployed on an SSLendpoint.

POST http://host:port/connector/rest/api/v1/authorization/basicAuthorization


HeadersContent-Type:application/jsonX-CEC-UserName:userX-CEC-UserPwd:passwordX-CEC-ProxyHost:proxy-hostX-CEC-ProxyPort:80X-CEC-ProxyScheme:http

Responsetrue

/rest/api/v1/content

Implements intradoc.connectorcommon.server.ContentResource

Given a file ID, this return the input stream for a file.

GET http://host:port/connector/rest/api/v1/content?uri=fFileGUID:xxxx

Request HeadersX-CEC-ClientID:client-idX-CEC-ProxyHost:proxy-hostX-CEC-ProxyPort:80X-CEC-ProxyScheme:http Response Headerscontent-disposition attachment; filename=pexels-photo-xxxx.jpegcontent-type image/jpeg


10-8

Response BodyFile Content

REST Interfaces for File System Browsing and SearchingIf a content connector uses the common picker available out of the box with OracleContent and Experience, then the content connector needs to implement the followingREST API.

This REST API is required for the Common UI.

/api/v1/filesystem

Implements intradoc.connectorcommon.server.FilesystemResource

This interface supports search as well as where queryText is passed.

POST http://host:port/connector/rest/api/v1/filesystem

Request HeadersX-CEC-ClientID:client-idX-CEC-ProxyHost:proxyX-CEC-ProxyPort:80X-CEC-ProxyScheme:httpContent-Type:application/json Request Body{ "itemCount": "50", "itemStartRow": "0", "itemsSortField": "ASC", "queryText": "animals"} Response{ "numItems": 50, "hasMoreItems": true, "totalItemsCount": 7190, "fileSystemInfo": { "uri": "fFolderGUID:null", "parentUri": "fFolderGUID:null", "name": "/", "description": null, "isDirectory": true, "size": null, "mimeType": null, "extension": null, "creator": null, "createdTimeStamp": null, "lastModifiedBy": null, "lastModifiedTimeStamp": null, "browseURL": null, "thumbnailURL": null,


10-9

"directoryContents": [ { "uri": "45170", "parentUri": "fFolderGUID:null", "name": "kittens-cat-cat-puppy-rush-45170.jpeg", "description": "kitten cat rush lucky cat", "isDirectory": false, "size": null, "mimeType": "image/jpeg", "extension": "jpeg", "creator": "Pixabay", "createdTimeStamp": null, "lastModifiedBy": null, "lastModifiedTimeStamp": null, "browseURL": "https://images.pexels.com/photos/45170/kittens-cat-cat-puppy-rush-45170.jpeg", "thumbnailURL": "https://images.pexels.com/photos/45170/kittens-cat-cat-puppy-rush-45170.jpeg?auto=compress&cs=tinysrgb&fit=crop&h=200&w=280", "directoryContents": null, "version": null, "additionalInformation": { "photographer": "Pixabay", "photographer_url": "http://api-server.pexels.com/@pixabay" } }, { "uri": "66898", "parentUri": "fFolderGUID:null", "name": "elephant-cub-tsavo-kenya-66898.jpeg", "description": "elephant cub kenya savanna", "isDirectory": false, "size": null, "mimeType": "image/jpeg", "extension": "jpeg", "creator": "Pixabay", "createdTimeStamp": null, "lastModifiedBy": null, "lastModifiedTimeStamp": null, "browseURL": "https://images.pexels.com/photos/66898/elephant-cub-tsavo-kenya-66898.jpeg", "thumbnailURL": "https://images.pexels.com/photos/66898/elephant-cub-tsavo-kenya-66898.jpeg?auto=compress&cs=tinysrgb&fit=crop&h=200&w=280", "directoryContents": null, "version": null, "additionalInformation": { "photographer": "Pixabay", "photographer_url": "http://api-server.pexels.com/@pixabay" } },. . .more entries. . . ],


10-10

"version": null, "additionalInformation": null }

The itemCount value represents the page size, and the itemStartRow value indicatesthe starting index of the current page requested. You can use these values todetermine the page number to retrieve and the number of records to fetch from yourbackend.

Content PickerOracle Content and Experience supports two mechanisms for integration so users canbrowse and select content and assets to bring into Oracle Content and Experience.

The content picker for a content connector can be either the common content picker ora custom one:

• The common content picker is provided by Oracle Content and Experience.

With the generic common picker, Oracle Content and Experience provides a basicframework and capabilities to build content browsing and selection. This worksseamlessly in conjunction with the Connector Framework SDK and the APIsdefined.

• The custom picker needs to be built by the content connector and can be builtusing any JS technology.

The custom picker is typically used in cases where the content connector builds itsown experience for accessing content in the remote store. Some stores have theirown native pickers, which the content connector could reuse for integrating withthe asset repository; for example, Google Drive, Microsoft OneDrive, and Dropbox.Additionally, the content connector can develop its own picker UI following thepredefined interfaces and callback mechanisms prescribed by Oracle Content andExperience.

If the content connector uses the common picker, then the connector needs to definepickerType in the server implementation:

intradoc.connectorcommon.server.ServerResource implementation

serverInfo.pickerType = PickerType.COMMON;

The content connector also needs to implement theintradoc.connectorcommon.server.FilesystemResource interface. Theimplementation needs to adhere to following guidelines in its filesystem RESTimplementation:

1. The content connector must append "fFolderGUID:" in uri, parentUri for eachfolder in the response of fileSystem.

2. A few fields are mandatory for every folder and file to be set inFileSystemResource for the common UI to work without any issues: uri,parentUri, and name. If parentUri is not applicable, then it can be set tofFolderGUID:null.

3. You must know the size of the result set being returned up front; that is,totalItemsCount needs to be set.


10-11

Use the Common UI

If the content connector uses the common picker, then it needs to define pickerTypein the eserver implementation:


serverInfo.pickerType = PickerType.COMMON;

The content connector also needs to implement theintradoc.connectorcommon.server.FilesystemResource interface. Theimplementation needs to adhere to following guidelines in its filesystem RESTimplementation:

1. The content connector must append "fFolderGUID:" in uri, parentUri for eachfolder in the response of fileSystem.

2. A few fields are mandatory for every folder and file to be set inFileSystemResource for the common UI to work without any issues: uri,parentUri, and name. If parentUri is not applicable, then it can be set tofFolderGUID:null.

3. You must know the size of the result set being returned up front; that is,totalItemsCount needs to be set.

The common UI supports customizations, which can be defined in the connectorconfiguration. The following table describes the additional settings that can be passedin a connector's ServerResource implementation.

Property Values Description

hide_breadcrumbs true

false (default)

To show or hide breadcrumbs

nextPrevPaginationEnabled

true

false (default)

To show page with next andprev buttons for pagination

For numbered pagination,don't set this property to true.

CommonPickerShowVideoView

true

false (default)

Card layout will be displayed,with each card having thefollowing items:• Iframe with video link• Description of video• Channel name

CommonPickerShowImageView

true

false (default)

Card layout will be displayed,with each card having thefollowing items:• Image thumbnail with link

to open full image in nexttab

• Photographer URL• Name of image• mimeType

show_termsOfUse true

false (default)

To show the terms andcondition link


10-12

Property Values Description

termsOfUse_link String If the show_termsOfUseproperty is true, then the linkfor terms and conditions isspecified using this property.

show_privacyPolicy true

false (default)

To show the privacy policy link

privacyPolicy_link String If the show_privacyPolicyproperty is true, then the linkfor the privacy policy isspecified using this property.

show_view_action true

false (default)

To show the view action onselect of item

page_size String

50 (default)

The size of one page. Ifresults are more than thegiven page size, then theresults will be paginated.

The settings are in the form of a map that needs to be set on ServerInfo. An examplefollows:

//Add UI Settings for the connector that will be read by the common picker Map<String,Object> additionalSettingsMap = new HashMap<String,Object>(); Map<String,String> uiSettingsMap = new HashMap<String,String>(); uiSettingsMap.put("CommonPickerShowImageView", "true"); uiSettingsMap.put("hide_breadcrumbs", "true"); uiSettingsMap.put("show_termsOfUse","true"); uiSettingsMap.put("show_privacyPolicy","true"); uiSettingsMap.put("termsOfUse_link","https://unsplash.com/terms"); uiSettingsMap.put("privacyPolicy_link","https://unsplash.com/privacy"); uiSettingsMap.put("show_view_action","true"); additionalSettingsMap.put("UISettings", uiSettingsMap); serverInfo.addtionalSettings = additionalSettingsMap;

The resulting JSON structure follows:

"addtionalSettings": { "UISettings": { "hide_breadcrumbs": "true", "show_view_action": "true", "CommonPickerShowImageView": "true", "termsOfUse_link": "https://unsplash.com/terms", "privacyPolicy_link": "https://unsplash.com/privacy", "show_privacyPolicy": "true", "show_termsOfUse": "true", "page_size": "30"


10-13

} }

Use a Custom UI

A content connector can implement a custom UI for its picker. This can be built usingany JS technology. However, it needs to invoke some predefined methods in OracleContent and Experience to obtain connector configuration and to pass back selections.The custom picker can be built to expose its own OK and Cancel buttons, in whichcase it needs to invoke the appropriate handlers. If the picker doesn't expose its ownOK and Cancel buttons, Oracle Content and Experience will provide this.

The pickerType needs to be defined as CUSTOM in the server implementation:


serverInfo.pickerType = PickerType.CUSTOM;

The custom implementation needs to include the following JS file in its library:

oracle-oce-custompicker.js

/*global window:true*/(function() { 'use strict'; var name = window.name; // name set on iframe element to uniquely identify the instance var receiver = window.opener || window.parent; var origin = "*"; function _postMessage(msg) { msg.name = name; receiver.postMessage(msg, origin); } var namespace = "OCE"; //todo: allow passing in data attribute if (!window[namespace]) { window[namespace] = {}; } var OCE = window[namespace]; if (!OCE.CustomPicker) { OCE.CustomPicker = { selection: [], addItem: function(id, name, type, size) { var item = {id: id, name: name, type: type, size: size}; this.selection.push(item); this.onChange(); }, removeItem: function(id) {


10-14

this.selection = this.selection.filter(function(item) { return item.id !== id; }); this.onChange(); }, onInit: function(cbInit) { var msg = { message: 'init', needAuthToken: true }; _postMessage(msg); this.messageListener = this.onPostMessage.bind(this); window.addEventListener('message', this.messageListener, false); this.cbInit = cbInit; }, onClose: function() { window.removeEventListener('message', this.messageListener, false); }, onPostMessage: function(event) { if (event.data && event.data.message === "init") { if (this.cbInit) { this.cbInit(event.data); } } }, onChange: function() { var msg = { message: 'change', selection: this.selection }; _postMessage(msg); }, onOk: function(selection) { selection = selection || this.selection; var msg = { message: 'ok', selection: this.selection }; _postMessage(msg); }, onCancel: function() { var msg = { message: 'cancel' }; _postMessage(msg); } }; }


10-15

})();

This JS file needs to be packaged in a content connector.

This library follows the JS postMessaging paradigm to pass information. The followingmethods are of interest.

onInit

The custom picker needs to invoke this method during its initialization. This is wherethe custom picker can get connector configuration information, like client ID andaccess token. The attributes defined in the connector configuration (/rest/api/v1/server) are passed via this method.

OCE.CustomPicker.onInit(function(data) { { if (data != null) { self.clientId = data.ClientID; //If connector uses OAuth self.AccessToken = data.AccessToken; //If connector uses BASIC auth self.user = data.UserName; self.password = Base64.decode(data.UserPwd); } //Use client id and access token to fetch data from back end. }})

onOk

If the custom picker exposes its own OK button, then it needs to invoke this method topass back the event to Oracle Content and Experience.

function pickerCallback(data) { if (data[google.picker.Response.ACTION] === google.picker.Action.PICKED) { data[google.picker.Response.DOCUMENTS].forEach(function(doc) { OCE.CustomPicker.addItem(doc.id, doc.name, "file", doc.sizeBytes); }); OCE.CustomPicker.onOk(); } else if (data[google.picker.Response.ACTION] === google.picker.Action.CANCEL) { OCE.CustomPicker.onCancel(); }}

onCancel


10-16

If the custom picker exposes its own Cancel button, then it needs to invoke thismethod to pass back the event to Oracle Content and Experience, like the onOkmethod does for the OK button in the preceding snippet.

addItem

This method needs to be invoked to pass back selections from the custom picker toOracle Content and Experience so that it displays the list of selected items in the Addto repository dialog. The IDs passed here are then used to fetch content with /rest/api/v1/content while adding an item to the asset repository.

addImage(selectedImages: Image[]) { selectedImages.forEach(o => { var name = "PexelsImages_" + o.uri; OCE.CustomPicker.addItem(o.uri, name, o.thumbnail, o.size); });}

removeItem

This method needs to be invoked when an item is unselected from a custom picker sothat the list maintained by Oracle Content and Experience is up to date. The final list isshown in the Add to repository dialog. The ID passed here is the same as the IDpassed in the addItem call.

removeImage(image: Image) { OCE.CustomPicker.removeItem(image);}

Package the custom picker in the connector. While registering the content connector,specify the following values:

1. Custom Picker URL: Such as http://host:port/pexels-picker/web (This is thecustom picker packaged in the content connector.)

2. Custom Picker uses its own OK/Cancel buttons: Leave it unchecked. (Thisindicates that you want Oracle Content and Experience to embed your picker intheir dialog.)

If the custom picker implements its own OK and Cancel buttons, then check this.

AuthorizationA content connector can support one of the following authorization models.

• No Auth

• OAuth

• Basic


10-17

No Auth

This is used when the content connector does not require any authorization. In thiscase, the connector picker is launched directly without invoking any authorizationscreen.

ServerResource Implementation

serverInfo.authenticationType = AuthenticationType.NO_AUTH

OAuth

This is used when a content connector supports OAuth. In this case, OCE ensuresthat the OAuth flow is invoked to fetch the access token. For subsequent access, thealready fetched token is used until it expires.

serverResource Implementation

serverInfo.authenticationType = AuthenticationType.OAUTH

The content connector also needs to define the required custom fields used in theOAuth flow.


{ FieldInfo field = new FieldInfo(); field.ID = UnsplashAdapter.FIELD_ID_REFRESH_TOKEN; field.label = ResourceBundleUtil.getDefaultLocalizedString("cds.unsplash.adapter.field.refreshtoken.label"); field.labelLocalizations = ResourceBundleUtil.getLocalizedData("cds.unsplash.adapter.field.refreshtoken.label"); field.datatype = FieldDatatype.STRING; field.userSettable = false; field.siteSettable = false; field.connectorSettable = true; field.authorizationURLParameter = false; serverInfo.fields.add(field);} { FieldInfo field = new FieldInfo(); field.ID = UnsplashAdapter.FIELD_ID_ACCESS_TOKEN; field.label = ResourceBundleUtil.getDefaultLocalizedString("cds.unsplash.adapter.field.accesstoken.label"); field.labelLocalizations =


10-18

ResourceBundleUtil.getLocalizedData("cds.unsplash.adapter.field.accesstoken.label"); field.datatype = FieldDatatype.STRING; field.userSettable = false; field.siteSettable = false; field.connectorSettable = true; field.authorizationURLParameter = false; serverInfo.fields.add(field);} { FieldInfo field = new FieldInfo(); field.ID = UnsplashAdapter.FIELD_ID_AUTHORIZATION_URL_PARAMETER_CODE; field.label = ResourceBundleUtil.getDefaultLocalizedString("cds.unsplash.adapter.field.authurl.code.label"); field.labelLocalizations = ResourceBundleUtil.getLocalizedData("cds.unsplash.adapter.field.authurl.code.label"); field.datatype = FieldDatatype.STRING; field.userSettable = false; field.siteSettable = false; field.connectorSettable = false; field.authorizationURLParameter = true; serverInfo.fields.add(field);} { FieldInfo field = new FieldInfo(); field.ID = UnsplashAdapter.FIELD_ID_AUTHORIZATION_URL_PARAMETER_ERROR; field.label = ResourceBundleUtil.getDefaultLocalizedString("cds.unsplash.adapter.field.authurl.error.label"); field.labelLocalizations = ResourceBundleUtil.getLocalizedData("cds.unsplash.adapter.field.authurl.error.label"); field.datatype = FieldDatatype.STRING; field.userSettable = false; field.siteSettable = false; field.connectorSettable = false; field.authorizationURLParameter = true; serverInfo.fields.add(field);

And also implement the following interfaces documented in the preceding text:

1. /rest/api/v1/authorization/authorizationURLs


10-19

2. /rest/api/v1/authorization/completedAuthorizations

Basic

This is used when content connector requires login credentials to connect to the backend. Here OCE will prompt you to enter sign-in details before launching the picker forthe first time. If the credentials are available, then they will be used.

Note:

Oracle no longer supports Basic authorization for external consumption.


serverInfo.authenticationType = AuthenticationType.BASIC

You also need to define all the login fields in the server implementation. These fieldswill display in the login screen.

// custom field for User Name{FieldInfo field = new FieldInfo();field.ID = "UserName";field.label = ResourceBundleUtil.getDefaultLocalizedString("cds.unsplash.adapter.field.username.label");field.labelLocalizations = ResourceBundleUtil.getLocalizedData("cds.unsplash.adapter.field.username.label");field.description = ResourceBundleUtil.getDefaultLocalized-String("cds.unsplash.adapter.field.username.desc");field.descriptionLocalizations = ResourceBundleUtil.getLocalizedData("cds.unsplash.adapter.field.username.desc");field.datatype = FieldDatatype.STRING;field.userSettable = true;field.siteSettable = false;field.connectorSettable = false;field.authorizationURLParameter = false;field.required = true;serverInfo.fields.add(field);}// custom field for password{FieldInfo field = new FieldInfo();field.ID = "UserPwd";field.label = ResourceBundleUtil.getDefaultLocalizedString("cds.unsplash.adapter.field.password.label");field.labelLocalizations = ResourceBundleUtil.getLocalizedData("cds.unsplash.adapter.field.password.label");field.description = ResourceBundleUtil.getDefaultLocalized-String("cds.unsplash.adapter.field.password.desc");field.descriptionLocalizations = ResourceBundleUtil.getLocalizedData("cds.unsplash.adapter.field.password.desc");field.datatype = FieldDatatype.PASSWORD;


10-20

field.userSettable = true;field.siteSettable = false;field.connectorSettable = false;field.authorizationURLParameter = false;field.required = true;serverInfo.fields.add(field);}

Besides this, the content connector needs to implement the following interface, asdescribed in the preceding text.

/rest/api/v1/authorization/basicAuthorization

Subsequently the user credentials (password base64 encoded) will be passed viaheaders for other calls, like filesystem and get content.

Content Connector Configuration and RegistrationOnce you have built your content connector, you need to register it in Oracle Contentand Experience. You can register a content connector through the Oracle Content andExperience administration web interface.

The minimum properties you are required to add to a content connector follow:

• Content connector name

• Content connector service URL

• User name and password, if the preceding URL access requires it

• Whether or not to accept a self-signed certificate

Once a content connector gets registered successfully and the content connectorservice URL is reachable, the Oracle Content and Experience server will call a serverservice on the content connector to get the custom properties and show those in theadministration UI. An administrator or developer can add values for those properties(for example, clientid and clientsecret for OAuth flows or the user name andpassword for a Basic authorization central account). Clicking Save saves all theseproperties with the connector framework. After you enable it, the content connectorbecomes available in the Add menu item of the Oracle Content and Experience UIAssets page.

See Create and Configure a Custom Content Connector in Administering OracleContent and Experience and Register the Content Connector, which describes how toregister and configure a Pexel content connector.

Content Connector Execution FlowFrom the Oracle Content and Experience UI Assets page, the user can click Add andchoose a content connector from the menu.

Based on the authorization type defined, the OAuth flow triggers or the user isprompted to add a user name and password for the Basic Auth flow (if a centralaccount has not been configured in the administration UI). For No Auth, the contentconnector picker is launched directly without invoking any authorization screen.

Chapter 10Content Connector Configuration and Registration

10-21

After successful authorization, the configured file picker (either common or custom) islaunched. It lists the files available to the user from the remote store.

The user can select one or more files. The selected files list is passed to the connectorframework. The connector framework then makes REST API calls to the remotecontent connector to fetch the content of the assets being added and copies them intothe Asset repository. This happens as a background process; however, the status ofthe add is displayed in the UI where success and failure can be tracked for each assetadded. Refer to the diagnostic logs for any failures.

Pexels Content Connector Sample ImplementationYou can use this sample implementation of a Pexels content connector to help buildyour own custom content connectors. The Pexels content connector lets contentcreators bring rich, high-quality images from the Pexels library into an Oracle Contentand Experience asset repository.

Pexels is a stock photography site where designers, bloggers, and others find photosto use for free. The Pexels content connector is built using the Connector FrameworkSDK provided by Oracle Content and Experience. Two versions of this contentconnector are available:

1. A content connector that uses a custom picker built using Angular JS. This versionis built by default.

2. A content connector that uses the common picker provided by Oracle Content andExperience.

The following sections describe how to develop a Pexels content connector.

• Install the Content Connector

• Register the Content Connector

• Test the Content Connector

• Understand the Content Connector Source Code

• Custom Picker UI

• Pexels REST APIs

• Change and Test the Content Connector Code

Install the Content ConnectorTo install the Pexels content connector, you need to meet the installation prerequisitesand then build the content connector WAR file.

The following sections describe the prerequisites and how to build the WAR file.

Check Prerequisites for InstallationYour system needs to be set up with node, npm, JDK, and Apache Maven before youinstall the Pexels content connector.

1. Ensure you have node and npm installed on your machine and set in PATH.Configure proxy if required.

See Configure Proxy Service Settings.

Chapter 10Pexels Content Connector Sample Implementation

10-22

2. Ensure you have latest JDK installed and set in PATH.

3. Ensure you have Apache Maven installed and set in PATH, with proxy configuredif required.

Build the Content Connector WAR FileDownload the content connector source bundle, unzip the bundle into a location onyour machine, and follow the instructions in the Readme file to generate the WAR file.

You can download the Oracle Content and Experience content connector sample andSDK from here:

https://your-cec-service/_sitesclouddelivery/renderer/app/sdk/connector/cec-connector-sample.zip

https://your-cec-service/_sitesclouddelivery/renderer/app/sdk/connector/cec-connector-sdk.zip

Briefly, the instructions are as follows:

1. In a command-line interface, go to pexelsPickerWeb\src\main\webapp.

2. Run pexels_setup.bat or pexels_setup.sh (based on your environment).

3. If the run is successful, pexels-picker.war file will be available in thepexelsPickerWeb\target folder.

The WAR file generated is the one that uses the custom picker UI, which was builtusing Angular JS.

Deploy this WAR file to your server. Run the following URLs to test that it works well:

1. GET http://host:port/pexels-picker/rest/api

2. GET http://host:port/pexels-picker/rest/api/v1/server

For expected output, see Understand the Content Connector Source Code.

Register the Content ConnectorTo use a Pexels content connector, you first need to access to the Pexels API. For thisyou need to register with Pexels and request access.

Follow the instructions in the Pexels API documentation, https://www.pexels.com/api/documentation/, to register the content connector and request access. After you makethe request, you will be provided with an API key that you need to capture. The PexelsAPI is rate-limited to 200 requests per hour and 20,000 requests per month. If youneed higher limits, contact Pexels.

1. Sign in to your Oracle Content and Experience instance as a developer oradministrator.

2. Go to Administration > Integration > Content Connectors and click Create.

3. Enter the details to register your Pexels content connector.

a. Name: Pexels


10-23

https://www.pexels.com/api/documentation/

https://www.pexels.com/api/documentation/

b. Description: Connector to bring Pexels images into Oracle Contentand Experience asset repository

c. Connector Service URL: http://host:port/pexels-picker/rest/api (aURL tested previously)

d. Check Accept Self-Signed Certificate (if required).

4. Click Verify Settings and then Save.

5. On the Content Connectors tab, click Configure to go back to the contentconnector configuration and provide the following values.

a. Custom Picker URL: http://host:port/pexels-picker/web/index.htmlThis is the custom picker packaged in a content connector. This setting is notapplicable when you use the common UI.

b. Hide OK/Cancel:Leave this setting unchecked. It indicates whether or not you want OracleContent and Experience to embed your picker in their dialog, which is notapplicable when you use the common UI.

6. Also provide the Client ID in the Custom Fields section:

7. Check Enable for End Users.

If your content connector is deployed on an instance that uses a self-signed certificate,the picker launched from Oracle Content and Experience will show an error as it islaunched in an iframe. You must launch the picker URL in a new browser tab, acceptthe certificate explicitly, and then launch the URL from Oracle Content andExperience.

The default timeout values for the content connector are set in the following twoproperties:

• ConnectorConnectionTimeout=20000

• ConnectorReadTimeout=30000

If you want to change the values of these properties, you can add the properties toyour config.cfg and then modify either or both values.


10-24

Test the Content ConnectorVerify the functionality of your Pexels content connector.

To test the content connector, go to the Assets tab and click Add. You should seeImport from Pexels in the drop-down menu. Ensure that you have created an assetrepository and selected it before you click Add. This will launch the Pexels pickershowing curated images up front.

This picker is either the custom UI packaged in the content connector or the commonpicker, depending on which you installed.

You can search for required images, select the ones you are interested in, and clickOK. This will open up the Add to Repository dialog, which lists the selected imagesyou can add. After you add them, the images should appear in the asset repository.

Understand the Content Connector Source CodeThe source code of the Pexels content connector contains REST APIs and a custompicker.

The Pexels content connector contains a set of REST APIs implemented using theOracle Content and Experience content connector interfaces. This is implemented asper the JAX-RS specification.

The Connector SDK and sample implementation are in the following files:

• cec-connector-sdk.zip

This file contains the SDK interface JAR, Javadoc, and connector.yaml file, whichdescribes the REST APIs and their payloads.


10-25

• oracle-oce-custompicker.js

This is the JS file that the content connector custom UI must package to interactwith Oracle Content and Experience.

• pexelsPickerWeb.zip

This file contains the Pexels content connector reference implementation.

Custom Picker UIThe Pexels picker packaged in the content connector is built using Angular JS. Itprovides the Custom Picker UI.

The Pexels picker files are in pexelsPickerWeb\src\main\webapp\src.

Pexels REST APIsThe Pexels content connector contains a set of REST APIs.

Change and Test the Content Connector CodeIf you make changes to the content connector code, you can run commands frompexelsPickerWeb\src\main\webapp to test the changes and rebuild the WAR file.

1. If you modify package.json to include additional libraries, run the followingcommand from pexelsPickerWeb\src\main\webapp:

npm install

2. If you make UI code changes, run the following command from pexelsPickerWeb\src\main\webapp:

ng build

3. Finally, run mvn from pexelsPickerWeb to rebuild the WAR file:

mvn clean install

Download the CEC Content Connector Sample and SDKA sample content connector and SDK are available for downlooad

You can download the following ZIP files, which contain the CEC content connectorsample and SDK:

• https://your-cec-service/_sitesclouddelivery/renderer/app/sdk/connector/cec-connector-sample.zip

• https://your-cec-service/_sitesclouddelivery/renderer/app/sdk/connector/cec-connector-sdk.zip

Chapter 10Download the CEC Content Connector Sample and SDK

10-26

11Use Webhooks

You can use webhook Endpoints for push notifications of content lifecycle and contentpublishing events.

See the following topics:

• Configure Webhooks

• Receive Push Notifications from a Content Lifecycle Webhook

• Receive Push Notifications from a Content Publishing Webhook

• Receive Push Notifications from a Site Publishing Webhook

• Use Endpoints for Push Notifications of Content Lifecycle, Content Publishing, andSite Publishing Events

Configure WebhooksYou can use webhooks to have Oracle Content and Experience automatically post anotification based on asset events.

For example, you might want to post a notification to an application when new contentis published, so that the application can consume the new content.

To create a webhook:

1. After you sign in to the Oracle Content and Experience web application as anadministrator, click Integrations in the Administration area of the navigation menu.

2. In the Integrations menu, click Webhooks.

3. Click Create.

4. Select the type of webhook you want to create:

• Asset Lifecycle Webhook: Receive push notifications about asset lifecyclechanges in a repository.

• Asset Publishing Webhook: Receive push notifications about assetspublished or unpublished to a channel.

• Site Publishing Webhook: Receive push notifications about site publishing.

5. Enter a name and description for the webhook. This name appears as a headingfor the posted conversation message.

6. Enable the webhook.

7. Provide information for webhook monitoring:

• If you're creating an asset lifecycle webhook, select the repository you want tomonitor for asset events.

• If you're creating an asset lifecycle webhook, select the repository you want tomonitor for asset events.

11-1

• If you're creating a site publishing webhook, specify the name of the site youwant to monitor for site events.

8. Select the events you want to generate notifications.

9. Select whether you want brief or detailed information about each event. For apublishing webhook, you can also select an empty notification.

• For asset lifecycle webhooks, brief notifications include who triggered event,what was the event, what item was involved with the event, in which repositorydid the event occur, when did the event occur; detailed notifications includethe same information listed in brief plus a list of all the fields in each contentitem or digital asset.

• For asset publishing webhooks, brief notifications include the IDs of eachpublished asset; detailed notifications include the same information listed inbrief plus a list of all the fields in each published asset.

10. Enter the target URL (endpoint) to which you want to post notifications.

11. If the endpoint requires authentication, select what type of authentication, and thenclick Details to enter the authentication information.Oracle Content and Experience webhooks support the following options toconfigure Authentication for the webhook notification receiver:

• None: The receiver does not require authentication.

• Basic: The receiver requires Basic Auth.

• Header: The receiver requires Secure Header.

12. Click Save.

To delete a webhook, click Delete next to the webhook.

To edit a webhook, click Edit next to the webhook.

Receive Push Notifications from a Content LifecycleWebhook

A content lifecycle webhook can send you push notifications about content lifecycleevents in an Oracle Content and Experience repository for content items andtaxonomies.

You can receive information about the following events from a content lifecyclewebhook:

• Content Item Created

• Content Item Updated

• Content Item Deleted

• Content Item Approved

• Content Item Published

• Content Item Republished

• Content Item Unpublished

• Digital Asset Created

• Digital Asset Updated

Chapter 11Receive Push Notifications from a Content Lifecycle Webhook

11-2

• Digital Asset Deleted

• Digital Asset Approved

• Digital Asset Published

• Digital Asset Republished

• Digital Asset Unpublished

• Collection Created

• Collection Deleted

A respository manager can create a content lifecycle webhook with a REST APIendpoint or on the Administration > Integrations > Webhooks > Settings page inthe Oracle Content and Experience web interface. On the Settings page for awebhook, users can configure the following settings:

• Name: A webhook name

• Description: A webhook description

• Status: An enabled or disabled status for the webhook. The default is disabled

• Repository: A repository to scope events for the webhook

• Events: A list of events for the webhook to send notifications

• Target URL: The URL of the endpoint to which notifications should be posted

• Authentication: A callback receiver security (None, Basic, or Header)

• Payload: The type of payload to send to the endpoint. (Brief or Detailed)

Name, Description, Status, Target URL, and Authentication are standard settingsfor a webhook. For the repository setting, pick a repository for which you haveManager permission.

Receive Push Notifications from a Content PublishingWebhook

A content publishing webhook can send you push notifications for asset and taxonomypublishing events in Oracle Content and Experience.

You can receive information about the following events from a content publishingwebhook:

• Asset Published to Channel

• Asset Republished to Channel

• Asset Unpublished to Channel

• Taxonomy Published

• Taxonomy Republished

• Taxonomy Unpublished

A channel manager can create a new content publishing webhook with a REST APIendpoint or on the Administration > Integrations > Webhooks > Settings page inthe Oracle Content and Experience web interface. This enables notifications aboutcontent published to the following channels:

Chapter 11Receive Push Notifications from a Content Publishing Webhook

11-3

• Public or secure custom publishing channels

• Publishing channels that Oracle Content and Experience creates for public orsecure enterprise sites

You can receive notifications about the following activities in the scope of a channel:

• Publish: A new content item, digital asset, or taxonomy is published.

• Republish A new version of a content item, digital asset, or taxonomy ispublished.

• Unpublish: A content item, digital asset, or taxonomy is unpublished.

Receive Push Notifications from a Site Publishing WebhookA site publishing webhook can send you push notifications for site publishing events inOracle Content and Experience.

A site manager can create a new site publishing webhook with a REST API endpointor on the Administration > Integrations > Webhooks > Settings page in the OracleContent and Experience web interface. This enables notifications about site publish,republish, and unpublish events.

Use Endpoints for Push Notifications of Content Lifecycle,Content Publishing, and Site Publishing Events

Oracle Content and Experience automatically delivers notifications to webhookendpoints about content publishing, content lifecycle, and site publishing events.

You subscribe to events for your webhooks to receive notification when the eventshappen, in the payloads for the endpoints. For example, if your endpoint subscribes toan event called DIGITALASSET_CREATED, when a digital asset is created in a repositoryyou specified, the webhook payload can tell you the name of the webhook, what timethe event happened, and who did the event.

You can use an endpoint to be notified when some action happens. Then OracleContent and Experience calls that endpoint. You can create webhooks using RESTendpoints, similar to other REST APIs. You need to specify a server URL for eachwebhook endpoint The GET, POST, PUT, and DELETE endpoints are hosted on theOracle Content and Experience server, so the same host name, port, and system isthe context for all the webhook endpoints.

You can create all the content items with the REST API or headless. You can alsocreate webhooks using the REST API, and listen to the events.

The webhook endpoints are as follows:

GET /webhooks Lists all webhooks.POST /webhooks Creates a webhook with the given information in the payload.GET /webhooks/{id} Reads a webhook with the given ID.PUT /webhooks/{id} Updates a webhook with the given information in the payload.DELETE /webhooks/{id} Deletes a webhook with the given ID.

Chapter 11Receive Push Notifications from a Site Publishing Webhook

11-4

Or you can create, configure, enable, or disable webhooks in the Oracle Content andExperience web UI at Administration > Integrations > Webhooks > Settings. See Configure Webhooks.

You can view event payloads, with Brief or Detailed output. Webhook payloadscontain the following data:

• Which webhook got invoked

• What event got triggered (maybe CONTENTITEM_UPDATED orCHANNEL_ASSETPUBLISHED)

• When the event was registered, and which user triggered it

• What entity is the subject of the event:

– For content lifecycle webhooks, it can be a content item or digital asset.

– For content publishing events, it will be a list of the identifiers of all publishedcontent.

Webhooks have three different formats, as the following table describes.

Format Output

Brief Output includes only basic informatio in thepayload. The output gives you details like whatthe action is, when it happened, in whatrepository, and who did the action.

Detailed Output includes all content information in thepayload. The output gives you the wholecontent item data, in a URL that you specify.

Empty Available only for content publishingwebhooks. If you specify Empty for the output,the payload contains only an identifierrepresenting the publish session ID.

If the endpoint requires authentication, you can select what type of authentication, andthen enter the authentication information.

Chapter 11Use Endpoints for Push Notifications of Content Lifecycle, Content Publishing, and Site Publishing Events

11-5

12Develop with OCE Toolkit

OCE Toolkit helps you develop site templates, themes, custom components, andcontent layouts for Oracle Content and Experience.

With OCE Toolkit, you work in your own development environment and can use assetrepositories, files, and folders in Oracle Content and Experience. OCE Toolkit hastools to create and develop custom components and site templates, including themesand content layouts. It includes a local test harness for quick, iterative developmentand sample unit tests to start with.

OCE Toolkit can help you do the following tasks:

• Set up your local development environment to use an Oracle Content andExperience instance for local development and testing of components, templates,themes, and content layouts

• Create components, site templates, and content layouts from samples, run them inthe test harness, explore them, and develop the components, templates, themes,and content layouts in a Developer Cloud Service environment

• Import components and site templates that were created in Oracle Content andExperience into a Developer Cloud Service project and environment for sourcemanagement and further development

• Export components, templates, and content layouts from a Developer CloudService environment for use in Oracle Content and Experience

• Copy an existing component, template, or content layout

• Write unit tests

• Optimize components

• Deploy your components and templates to Oracle Content and Experience

The following topics describe how to set up OCE Toolkit and develop with it on yourlocal machine or as a Developer Cloud Service project:

• Set Up OCE Toolkit on Your Local Machine

• Develop for Oracle Content and Experience with Developer Cloud Service

• Propagate Changes from Test to Production with OCE Toolkit

• Create a Site from a Template and Keep the Same GUIDs for Content

• Transfer or Update a Site from One Server to Another

• Index Site Pages with OCE Toolkit

• Index a Multilingual Site with OCE Toolkit

• Create a Simplified Component for Easy Component Development

• Compile a Site to Improve Runtime Performance for Site Pages

• Create a New Site or Asset Translation Job in the Oracle Content and ExperienceServer

12-1

• Translate a Site with a Language Service Provider

Set Up OCE Toolkit on Your Local MachineOn your local machine, create a folder to download OCE Toolkit from your OracleContent and Experience instance.

In a terminal window, enter these commands:

1. Make sure node and npm are in your PATH. Use NodeJS 8.0.0 or later.

2. Download the OCE Toolkit - for example, from GitHub - link

3. Install the dependencies:

cd <download-path>/content-and-experience-toolkit/sitesnpm install

4. Put cec on your path:

• Mac:

sudo ln -s $PWD/content-and-experience-toolkit/sites/node_modules/.bin/cec /usr/local/bin/cec

• Windows:Run SystemPropertiesAdvanced.exe and edit Environment Variables. Add<your download path>\content-and-experience-toolkit\sites\node_modules\.bin to the PATH variable, replacing <your download path>as appropriate.

5. Run the command line utility, cec, to get help about the commands.

cec

Complete the setup and prepare to use OCE Toolkit:

1. Install Dependencies Through npm

2. Create Source in Your Local File System

3. Use the cec Command-Line Utility

4. Test with a Local Test Harness

Install Dependencies Through npmUse npm (node package manager) to install sites dependencies for your project.

If you are using a proxy to access the Internet, set the proxy for npm with the npmconfig command. See https://docs.npmjs.com/misc/config. To set the proxy for bower,see https://bower.io/docs/config/.

Chapter 12Set Up OCE Toolkit on Your Local Machine

12-2

https://github.com/oracle/content-and-experience-toolkit/archive/master.zip

https://docs.npmjs.com/misc/config

https://bower.io/docs/config/

Note:

Ensure that you have Node.js 8.0.0 or later (https://nodejs.org/) installed onyour local computer.

In a terminal window, enter these commands:

1. cd content-and-experience-toolkit/sites

2. npm install

3. npm run install-cec

• Mac: Run the following command instead to add cec to /usr/local/bin:

sudo npm run install-cec

• Windows:

If the npm run install-cec command fails, run the following commands:

cd bin\cec npm installcd ..\..\npm run install-cec

Note:

In Windows, you can run 'start npm start' to start this in a new CommandPrompt window.

Create Source in Your Local File System

In a directory inside a git / SVN repository, type the following:

cec install

This will create a source tree, with a package.json file, and do an npm install to fetchdependencies into the source tree. Update package.json to include any furtherdependencies you need for your resources.

Set up connections to your Source and Target Oracle Content and Experienceinstances.

You can have one, two, or more registered servers, based on your scenario. It couldbe, for example, DEV, TEST, PROD, or DEV, PROD. You can test in a PROD serverand then use the OCE Toolkit CLI to publish and go-live. For example:

cec register-server DEV -e https://your-dev-instance.com -u user -p passwordcec register-server UAT -e https://your-test-instance.com -u user -p password


12-3

https://nodejs.org/

cec register-server PROD -e https://your-production-instance.com -u user -p password

Test your connections as follows:

cec list --server DEV

Use the cec Command-Line UtilityThe cec cross-platform command-line utility provides commands for creating andmanaging templates and components.

Before you use the cec command-line utility, create source in your local developmentenvironment for commands that require a connection to the Oracle Content andExperience server. See Create Source in Your Local File System.

Integrated help provides information to run the commands, with examples. To view thecec integrated help, you can type cec commands in the command line:

• In a terminal window, go to the cec directory.

• Type cec to list the cec commands.

cec------------------------Usage: cec <command> [options]

Run cec <command> -h' to get the detailed help for the command.

Commands:

Documents cec create-folder <name> Creates a folder or folder hierarchy on CEC server. [alias: cfd] cec share-folder <name> Shares folder with users and groups on CEC server. [alias: sfd] cec unshare-folder <name> Deletes user or group access to a shared folder on CEC server. [alias: usfd] cec download-folder <path> Downloads folder from CEC server. [alias: dlfd] cec upload-folder <path> Uploads folder to CEC server. [alias: ulfd] cec delete-folder <path> Deletes folder on CEC server. [alias: ] cec download-file <file> Downloads file <file> from CEC server. [alias: dlf] cec upload-file <file> Uploads file <file> to CEC server. [alias: ulf] cec delete-file <file> Deletes file on CEC server. [alias: ]

Components cec create-component <name> Creates the component <name>. [alias: cc] cec copy-component <source> [<destination>] Copies an existing


12-4

component named <source> to <destination>. [alias: cpc] cec import-component <zip> Imports a component from <zip>. [alias: ic] cec export-component <name> Exports the component <name> as a zip file. [alias: ec] cec download-component <names> Downloads the components <names> from the CEC server. [alias: dlcp] cec upload-component <names> Uploads the components <names> to the CEC server. [alias: ulcp] cec control-component <action> Performs action <action> on components on CEC server. [alias: ctcp] cec share-component <name> Shares component with users and groups on CEC server. [alias: sc] cec unshare-component <name> Deletes user or group access to a component on CEC server. [alias: usc]

Templates cec create-template <name> Creates the template <name>. [alias: ct] cec create-template-from-site <name> Creates the template <name> from site <site> on the CEC server. [alias: ctfs] cec download-template <name> Downloads the template <name> from the CEC server. [alias: dlt] cec compile-template <source> Compiles the site within the template. [alias: cmpt] cec copy-template <source> [<destination>] Copies an existing template named <source> to <destination>. [alias: cpt] cec import-template <zip> Imports a template from <zip>. [alias: it] cec export-template <name> Exports the template <name> as a zip file. [alias: et] cec upload-template <name> Uploads the template <name> to the CEC server. [alias: ult] cec delete-template <name> Deletes the template <name> on the CEC server. [alias: ] cec share-template <name> Shares template with users and groups on CEC server. [alias: stm] cec unshare-template <name> Deletes user or group access to a template on CEC server. [alias: ustm] cec describe-template <name> Describes the template <name> package. [alias: dst] cec create-template-report <name> Generates an asset usage report for the template <name> package. [alias: cttr] cec add-component-to-template <component> Adds a component to a template. [alias: actp] cec remove-component-from-template <component> Removes a component from a template. [alias: rcfp]

Themes cec add-component-to-theme <component> Adds a component to a theme. [alias: actt] cec remove-component-from-theme <component> Removes a component from a theme. [alias: rcft] cec control-theme <action> Performs action <action> on theme on CEC server. [alias: ctt]


12-5

cec share-theme <name> Shares theme with users and groups on CEC server. [alias: sth] cec unshare-theme <name> Deletes user or group access to a theme on CEC server. [alias: usth]

Sites cec create-site <name> Creates Enterprise Site <name>. [alias: cs] cec update-site <name> Update Enterprise Site <name>. [alias: us] cec transfer-site <name> Transfers Enterprise Site from one CEC server to another. [alias: ts] cec validate-site <name> Validates site <name>. [alias: vs] cec control-site <action> Performs action <action> on site on CEC server. [alias: cts] cec share-site <name> Shares site with users and groups on CEC server. [alias: ss] cec unshare-site <name> Deletes user or group access to a site on CEC server. [alias: uss] cec set-site-security <name> Sets site security on CEC server. [alias: sss] cec index-site <site> Index the page content of site <site> on CEC server. [alias: is] cec create-site-map <site> Creates a site map for site <site> on CEC server. [alias: csm] cec create-rss-feed <site> Creates RSS feed for site <site> on CEC server. [alias: crf] cec create-asset-report <site> Generates an asset usage report for site <site> on CEC server. [alias: car] cec upload-static-site-files <path> Uploads files to render statically from a site on CEC server. [alias: ulss] cec download-static-site-files <site> Downloads the static files from a site on CEC server. [alias: dlss] cec delete-static-site-files <site> Deletes the static files from a site on CEC server. [alias: ] cec refresh-prerender-cache <site> Refreshes pre-render cache for a site on CEC server. [alias: rpc] cec migrate-site <site> Migrates a site from OCI IC server to EC server. [alias: ms]

Assets cec download-content <channel> Downloads content in channel <channel> from CEC server. [alias: dlc] cec upload-content <name> Uploads local content to a repository on CEC server. [alias: ulc] cec control-content <action> Performs action <action> on channel items on CEC server. [alias: ctct] cec list-assets Lists assets on CEC server. [alias: la] cec copy-assets <repository> Copies assets to another repository on CEC server. [alias: ca] cec create-asset-usage-report <assets> Generates an asset usage report for assets on CEC server. [alias: caur]


12-6

Content cec create-repository <name> Creates a repository on CEC server. [alias: cr] cec control-repository <action> Performs action <action> on repository on CEC server. [alias: ctr] cec share-repository <name> Shares repository with users and groups on CEC server. [alias: sr] cec unshare-repository <name> Deletes user or group access to a repository on CEC server. [alias: usr] cec create-channel <name> Creates a channel on CEC server. [alias: cch] cec create-localization-policy <name> Creates a localization policy on CEC server. [alias: clp] cec list-server-content-types Lists all content types from server. [alias: lsct] cec share-type <name> Shares type with users and groups on CEC server. [alias: st] cec unshare-type <name> Deletes user or group access to a type on CEC server. [alias: ust] cec create-contentlayout <name> Creates a content layout based on a content type. [alias: ccl] cec add-contentlayout-mapping <contentlayout> Creates content type and content layout mapping for local template. [alias: aclm] cec remove-contentlayout-mapping <contentlayout> Removes a content layout mapping from a local template. [alias: rclm] cec add-field-editor <name> Adds a field editor to a field in a content type. [alias: afe] cec remove-field-editor <name> Removes a field editor from a field in a content type. [alias: rfe] cec migrate-content <name> Migrates content from OCI IC server to EC server. [alias: mc]

Translation cec list-translation-jobs Lists translation jobs. [alias: ltj] cec create-translation-job <name> Creates a translation job <name> for a site on CEC server. [alias: ctj] cec download-translation-job <name> Downloads translation job <name> from CEC server. [alias: dtj] cec submit-translation-job <name> Submits translation job <name> to translation connection <connection>. [alias: stj] cec refresh-translation-job <name> Refreshes translation job <name> from translation connection. [alias: rtj] cec ingest-translation-job <name> Gets translated job <name> from translation connection and ingest. [alias: itj] cec upload-translation-job <name> Uploads translation job <name> to CEC server. [alias: utj] cec create-translation-connector <name> Creates translation connector <name>. [alias: ctc] cec start-translation-connector <name> Starts translation connector <name>. [alias: stc] cec register-translation-connector <name> Registers a translation connector. [alias: rtc]

Groups


12-7

cec create-group <name> Creates an OCE group on OCE server. [alias: cg] cec delete-group <name> Deletes an OCE group on OCE server. [alias: ] cec add-member-to-group <name> Adds users and groups to an OCE group on OCE server. [alias: amtg] cec remove-member-from-group <name> Removes users and groups from an OCE group on OCE server. [alias: rmfg]

Local Environment cec create-encryption-key <file> Create an encryption key to encrypt/decrypt password for servers. [alias: cek] cec register-server <name> Registers a CEC server. [alias: rs] cec set-oauth-token <token> Set OAuth token for a registered server. [alias: sot] cec list Lists local or server resources. [alias: l] cec install Creates source tree. [alias: i] cec develop Starts a test server. [alias: d] cec sync-server Starts a sync server. [alias: scs]

Options: --help, -h Show help [boolean] --version, -v Show version number [boolean]------------------------cec create-folder------------------------Usage: cec create-folder <name>

Create a folder or folder hierarchy on CEC server. Specify the server with -s <server> or use the one specified in cec.properties file.

Options: --server, -s <server> The registered CEC server --help, -h Show help [boolean]

Examples: cec create-folder Projects Creates folder Projects under the Home folder cec create-folder Projects/Blogs Creates folder Projects under the Home folder and folder Blogs under Projects cec create-folder Projects -s UAT Creates folder Projects under the Home folder on the registered server UAT------------------------cec share-folder------------------------Usage: cec share-folder <name>

Shares folder with users and groups on CEC server and assign a role. Specify the server with -s <server> or use the one specified in cec.properties file. The valid roles are


12-8

manager contributor downloader viewer

Options: --users, -u The comma separated list of user names --groups, -g The comma separated list of group names --role, -r The role [manager | contributor | downloader | viewer] to assign to the users or groups [required] --server, -s <server> The registered CEC server --help, -h Show help [boolean]

Examples: cec share-folder Projects/Blogs -u user1,user2 -r manager Share folder Projects/Blogs with user user1 and user2 and assign Manager role to them cec share-folder Projects/Blogs -u user1,user2 -g group1 -r manager Share folder Projects/Blogs with user user1, user2 and group group1 and assign Manager role to them cec share-folder Projects/Blogs -g group1,group2 -r manager Share folder Projects/Blogs with group group1 and group2 and assign Manager role to them cec share-folder Projects/Blogs -u user1,user2 -r manager -s UAT Share folder Projects/Blogs with user user1 and user2 and assign Manager role to them on the registered server UAT------------------------cec unshare-folder------------------------Usage: cec unshare-folder <name>

Deletes user or group access to a shared folder on CEC server. Specify the server with -s <server> or use the one specified in cec.properties file.

Options: --users, -u The comma separated list of user names --groups, -g The comma separated list of group names --server, -s <server> The registered CEC server --help, -h Show help [boolean]

Examples: cec unshare-folder Projects/Blogs -u user1,user2 cec unshare-folder Projects/Blogs -g group1,group2 cec unshare-folder Projects/Blogs -u user1,user2 -g group1,group2 cec unshare-folder Projects/Blogs -u user1,user2 -s UAT------------------------cec download-folder------------------------Usage: cec download-folder <path>

Downloads folder and all its content from CEC server. Specify the server with -s <server> or use the one specified in cec.properties file. Optionally specify -f <folder> to save the folder on the local system.


12-9

Options: --folder, -f <folder> Local folder to save the folder on CEC server --server, -s <server> The registered CEC server --help, -h Show help [boolean]

Examples: cec download-folder Releases/1 Downloads folder Releases/1 from CEC server and save to local folder src/documents/ cec download-folder / Downloads all documents from CEC server and save to local folder src/documents/ cec download-folder Releases/1 -s UAT Downloads folder Releases/1 from the registered server UAT and save to local folder src/documents/ cec download-folder Releases/1 -f ~/Downloads Downloads folder Releases/1 from CEC server and save to local folder ~/Download/ cec download-folder Releases/1 -f . Downloads folder Releases/1 from CEC server and save to the current local folder cec download-folder site:blog1 -f ~/Downloads/blog1Files Downloads all files of site blog1 and save to local folder ~/Download/blog1Files cec download-folder theme:blog1Theme Downloads all files of theme blog1Theme and save to local folder src/documents/blog1Theme/ cec download-folder component:Comp1/assets Downloads all files in folder assets of component Comp1 and save to local folder src/documents/Comp1/assets/------------------------cec upload-folder------------------------Usage: cec upload-folder <path>

Uploads folder and all its content to CEC server. Specify the server with -s <server> or use the one specified in cec.properties file. Optionally specify -f <folder> to set the parent folder on CEC server.

Options: --folder, -f <folder> The parent folder on CEC server --server, -s <server> The registered CEC server --help, -h Show help [boolean]

Examples: cec upload-folder ~/Downloads/docs Uploads all content from ~/Downloads/docs to folder docs on the server cec upload-folder ~/Downloads/docs/ Uploads all content from ~/Downloads/docs to the Home folder on the server cec upload-folder ~/Downloads/docs -f Mydoc Uploads all content from ~/Downloads/docs to folder Mydoc/docs on the server cec upload-folder ~/Downloads/docs/ -f Mydoc Uploads all content from ~/Downloads/docs to folder Mydoc on the server cec upload-folder ~/Downloads/docs -s UAT Uploads all content from ~/Downloads/docs to folder docs on the registered server UAT cec upload-folder ~/Downloads/docs/ -f site:blog1/settings/misc Uploads all content from ~/Downloads/docs to folder settings/misc of site blog1 cec upload-folder ~/Downloads/docs -f theme:blog1Theme Uploads


12-10

all content from ~/Downloads/docs to folder docs of theme blog1Theme cec upload-folder ~/Downloads/docs -f component:Comp1 Uploads all content from ~/Downloads/docs to folder docs of component Comp1------------------------cec delete-folder------------------------Usage: cec delete-folder <path>

Deletes folder and all its content on CEC server. Specify the server with -s <server> or use the one specified in cec.properties file. Optionally specify -p to permanently delete the folder.

Options: --server, -s <server> The registered CEC server --permanent, -p Delete the folder permanently --help, -h Show help [boolean]

Examples: cec delete-folder Import/docs cec delete-folder Import/docs -s UAT cec delete-folder Import/docs -p cec delete-folder site:blog1/docs cec delete-folder theme:blog1Theme/docs cec delete-folder component:Comp1/docs------------------------cec download-file------------------------Usage: cec download-file <file>

Downloads file <file> from CEC server. Specify the server with -s <server> or use the one specified in cec.properties file. Optionally specify -f <folder> to save the file on the local system.

Options: --folder, -f <folder> Local folder to save the file --server, -s <server> The registered CEC server --help, -h Show help [boolean]

Examples: cec download-file Releases/Projects.pdf Downloads the file from CEC server and save to local folder src/documents/ cec download-file Releases/Projects.pdf -s UAT Downloads the file from the registered server UAT and save to local folder src/documents/ cec download-file Releases/Projects.pdf -f ~/Downloads Downloads the file from CEC server and save to local folder ~/Download/ cec download-file Releases/Projects.pdf -f . Downloads the file from CEC server and save to the current local folder cec download-file site:blog1/siteinfo.json Downloads the file from folder blog1 and save to local folder src/documents/blog1 cec download-file theme:blog1Theme/designs/default/design.css Downloads the css file from folder designs/default of theme blog1Theme and save to local folder src/documents/blog1Theme/designs/default/ cec download-file component:Comp1/assets/render.js Downloads the js file from folder assets of component Comp1 and save to local folder


12-11

src/documents/Comp1/assets/------------------------cec upload-file------------------------Usage: cec upload-file <file>

Uploads file <file> to CEC server. Specify the server with -s <server> or use the one specified in cec.properties file. Optionally specify -f <folder> to set the parent folder on CEC server.

Options: --folder, -f <folder> The parent folder on CEC server --server, -s <server> The registered CEC server --help, -h Show help [boolean]

Examples: cec upload-file ~/Documents/Projects.pdf Uploads the file to the Home folder cec upload-file ~/Documents/Projects.pdf -s UAT Uploads the file to the Home folder on the registered server UAT cec upload-file ~/Documents/Projects.pdf -f Doc/Plan Uploads the file to folder Doc/Plan cec upload-file ~/Documents/Projects.pdf -f site:blog1/settings/misc Uploads the file to folder settings/misc of site blog1 cec upload-file ~/Documents/style1.css -f theme:blog1Theme/designs/default Uploads the css file to folder designs/default of theme blog1Theme cec upload-file ~/Documents/comp1.js -f component:Comp1/assets Uploads the js file to folder assets of component Comp1------------------------cec delete-file------------------------Usage: cec delete-file <file>

Deletes file on CEC server. Specify the server with -s <server> or use the one specified in cec.properties file. Optionally specify -p to permanently delete the file.

Options: --server, -s <server> The registered CEC server --permanent, -p Delete the file permanently --help, -h Show help [boolean]

Examples: cec delete-file /docs/Projects.pdf cec delete-file /docs/Projects.pdf -s UAT cec delete-file /docs/Projects.pdf -p cec delete-file site:blog1/docs/Projects.pdf cec delete-file theme:blog1Theme/docs/Projects.pdf cec delete-file component:Comp1/docs/Projects.pdf------------------------cec create-component------------------------Usage: cec create-component <name>


12-12

Creates the component <name>. By default, it creates a local component. Optionally specify -f <source> to create from a different source.

Valid values for <source> are: local local-iframe remote sectionlayout Sample-File-List Sample-Folder-List Sample-Documents-Manager Sample-Process-Start-Form Sample-Process-Task-List Sample-Process-Task-Details Sample-Stocks-Embedded Sample-Text-With-Image Sample-To-Do Anchor Document-Search JET-CCA-Demo-Card MapFieldEditor Sample-OPA-Interview SimpleHTML SliderFieldEditor TextFieldEditor

Options: --from, -f <from> Source to create from --help, -h Show help [boolean]

Examples: cec create-component Comp1 cec create-component Comp2 -f Sample-File-List------------------------cec copy-component------------------------Usage: cec copy-component <source> [<destination>]

Copies an existing component named <source> to <destination>. <source> is a folder name from src/components

Options: --help, -h Show help [boolean]

Examples: cec copy-component Sample-To-Do Comp1 Copies Sample-To-Do to Comp1.------------------------cec import-component------------------------Usage: cec import-component <zip>

Imports a component from <zip>. Specify the absolute path of the zip file. The zip file name will be used as the component name.


12-13


Examples: cec import-component /home/Comp1.zip Imports the component Comp1.------------------------cec export-component------------------------Usage: cec export-component <name>

Exports the component <name> as a zip file.


Examples: cec export-component Sample-To-Do Exports the component Sample-To-Do.------------------------cec download-component------------------------Usage: cec download-component <names>

Downloads the components <names> from the Content and Experience Cloud server. Specify the server with -s <server> or use the one specified in cec.properties file.


Examples: cec download-component Sample-To-Do cec download-component Sample-To-Do,Sample-To-Do2 cec download-component Sample-To-Do -s UAT------------------------cec upload-component------------------------Usage: cec upload-component <names>

Uploads the components <names> to the Content and Experience Cloud server. Specify the server with -s <server> or use the one specified in cec.properties file. Optionally specify -p to publish the component after deploy. Optionally specify -f <folder> to set the folder to upload the component zip file.

Options: --folder, -f <folder> Folder to upload the component zip file --publish, -p Publish the component --server, -s <server> The registered CEC server --help, -h Show help [boolean]

Examples: cec upload-component Sample-To-Do Uploads the component Sample-To-Do to the server specified in cec.properties.


12-14

cec upload-component Sample-To-Do -s UAT Uploads the component Sample-To-Do to the registered server UAT. cec upload-component Sample-To-Do -p Uploads and publishes the component Sample-To-Do. cec upload-component Sample-To-Do,Sample-To-Do2 Uploads component Sample-To-Do and Sample-To-Do2. cec upload-component Sample-To-Do -f Import/Components Uploads file Sample-To-Do.zip to folder Import/Components and imports the component Sample-To-Do.------------------------cec control-component------------------------Usage: cec control-component <action>

Perform <action> on components on CEC server. Specify the components with -c <components>. Specify the server with -s <server> or use the one specified in cec.properties file. The valid actions are

publish

Options: --components, -c <components> The comma separated list of components [required] --server, -s <server> The registered CEC server --help, -h Show help [boolean]

Examples: cec control-component publish -c Comp1 Publish component Comp1 on the server specified in cec.properties file cec control-component publish -c Comp1 -s UAT Publish component Comp1 on the registered server UAT cec control-component publish -c Comp1,Comp2 -s UAT Publish component Comp1 and Comp2 on the registered server UAT------------------------cec share-component------------------------Usage: cec share-component <name>

Shares component with users and groups on CEC server and assign a role. Specify the server with -s <server> or use the one specified in cec.properties file. The valid roles are


Options: --users, -u The comma separated list of user names --groups, -g The comma separated list of group names --role, -r The role [manager | contributor | downloader | viewer] to assign to the users or groups [required] --server, -s <server> The registered CEC server


12-15

--help, -h Show help [boolean]

Examples: cec share-component Comp1 -u user1,user2 -r manager Share component Comp1 with user user1 and user2 and assign Manager role to them cec share-component Comp1 -u user1,user2 -g group1,group2 -r manager Share component Comp1 with user user1 and user2 and group group1 and group2 and assign Manager role to them cec share-component Comp1 -u user1,user2 -r manager -s UAT Share component Comp1 with user user1 and user2 and assign Manager role to them on the registered server UAT------------------------cec unshare-component------------------------Usage: cec unshare-component <name>

Deletes user or group access to a component on CEC server. Specify the server with -s <server> or use the one specified in cec.properties file.


Examples: cec unshare-component Comp1 -u user1,user2 cec unshare-component Comp1 -u user1,user2 -g group1,group2 cec unshare-component Comp1 -u user1,user2 -s UAT------------------------cec create-template------------------------Usage: cec create-template <name>

Creates the template <name>. By default, it creates a StarterTemplate. Optionally specify -f <source> to create from different source.

Valid values for <source> are: CafeSupremoLite JETStarterTemplate StarterTemplate BlogTemplate VBCSSamplesTemplate search_template

To create template based on a site on CEC server, specify -s <site> and specify the server with -r <server> or use the one specified in cec.properties file.

Options: --from, -f <source> Source to create from --site, -s <site> Site to create from --excludecontent, -x Exclude content --server, -r <server> The registered CEC server


12-16


Examples: cec create-template Temp1 cec create-template Temp2 -f CafeSupremoLite cec create-template Temp1 -s Site1 Create template Temp1 based on site Site1 on CEC server cec create-template Temp1 -s Site1 -x Create template Temp1 based on site Site1 on CEC server and exclude the content in the site cec create-template Temp1 -s Site1 -r UAT Create template Temp1 based on site Site1 on the registered server UAT------------------------cec create-template-from-site------------------------Usage: cec create-template-from-site <name>

Creates the template <name> from site <site> on the Content and Experience Cloud server. Specify the server with -r <server> or use the one specified in cec.properties file. Optionally specify <includeunpublishedassets> to include unpublished content items and digital assets in your template.

Options: --site, -s <site> Site to create from [required] --includeunpublishedassets, -i flag to indicate to include unpublished content items and digital assets in your template --server, -r <server> The registered CEC server --help, -h Show help [boolean]

Examples: cec create-template-from-site BlogTemplate -s BlogSite cec create-template-from-site BlogTemplate -s BlogSite -r UAT cec create-template-from-site BlogTemplate -s BlogSite -i -r UAT------------------------cec download-template------------------------Usage: cec download-template <name>

Downloads the template <name> from the Content and Experience Cloud server. Specify the server with -s <server> or use the one specified in cec.properties file.


Examples: cec download-template BlogTemplate cec download-template BlogTemplate -s UAT------------------------cec compile-template------------------------Usage: cec compile-template <source>

Compiles all the pages within the site of the template and places the compiled pages under the sites assets folder.


12-17

Optionally specify -s <server> to make content queries against this server (requires channelToken).Optionally specify -c <channelToken> to use this channelToken when generating any content URLs.Optionally specify -t <contentType> [draft | published] content to retrieve from the server type, defaults to published.Optionally specify -p <pages> the set of pages to compile.Optionally specify -d <debug> to start the compilation with --inspect-brk flag.Optionally specify -r <recurse> recurse through all child pages of specified pages.Optionally specify -l <includeLocale> include default locale when creating pages.Optionally specify -a <targetDevice> [desktop | mobile] target device type when using adaptive layouts.Optionally specify -v <verbose> to display all warning messages during compilation.

Options: --server, -s The registered CEC server --channelToken, -c The channel access token to use for content URLs --type, -t The type of content to retrieve from the serve [published | draft] --pages, -p The list of pages to compile --recurse, -r Compile all child pages of those specifed in the page list --debug, -d Start the compiler with "--inspect-brk" option to debug compilation --noDetailPages, -e Do not generate compiled detail pages --noDefaultDetailPageLink, -o Do not generate compiled detail page for items/content lists that use the default detail page --targetDevice, -a The target device type when using adaptive layouts [desktop | mobile] --includeLocale, -l Include default locale when creating pages --verbose, -v Run in verbose mode to display all warning messages during compilation. --help, -h Show help [boolean]

Examples: cec compile-template Temp1 Compiles the site in template Temp1 using content stored in the template. cec compile-template Temp1 -c channelToken Compiles the site in template Temp1 using the given channelToken for any content URLs. cec compile-template Temp1 -c channelToken -s UAT -t draft Compiles the site in template Temp1 retrieving draft content from the specified server. cec compile-template Temp1 -p 104,112,183 -r Compiles the specified pages in the site in template Temp1 including all child pages. cec compile-template Temp1 -d Waits for the debugger to be attached. Once attached, compiles the site in template Temp1.------------------------cec copy-template------------------------


12-18

Usage: cec copy-template <source> [<destination>]

Copies an existing template named <source> to <destination>. <source> is a folder name from src/templates


Examples: cec copy-template Temp1 Temp2 Copies Temp1 to Temp2.------------------------cec import-template------------------------Usage: cec import-template <zip>

Imports a template from <zip>. Specify the absolute path of the zip file. The zip file name will be used as the template name.


Examples: cec import-template /home/Temp1.zip Imports the template Temp1.------------------------cec export-template------------------------Usage: cec export-template <name>

Exports the template <name> as a zip file and provides the location of the zip file.

Options: --optimize, -o Optimize the template --help, -h Show help [boolean]

Examples: cec export-template Temp1 Exports the template Temp1.------------------------cec upload-template------------------------Usage: cec upload-template <name>

Uploads the template <name> to the Content and Experience Cloud server. Specify the server with -s <server> or use the one specified in cec.properties file. Optionally specify -f <folder> to set the folder to upload the template zip file.

Options: --folder, -f <folder> Folder to upload the template zip file --server, -s <server> The registered CEC server --optimize, -o Optimize the template --excludecontenttemplate, -x Exclude content template --help, -h Show help [boolean]


12-19

Examples: cec upload-template StarterTemplate Uploads the template StarterTemplate. cec upload-template StarterTemplate -s UAT Uploads the template StarterTemplate to the registered server UAT. cec upload-template StarterTemplate -f Import/Templates Uploads file StarterTemplate.zip to folder Import/Templates and imports the template StarterTemplate. cec upload-template StarterTemplate -o Optimizes and uploads the template StarterTemplate. cec upload-template StarterTemplate -x Exclude the "Content Template" from the template upload. "Content Template" upload can be managed independently.------------------------cec delete-template------------------------Usage: cec delete-template <name>

Deletes the template <name> on the Content and Experience Cloud server. Specify the server with -s <server> or use the one specified in cec.properties file. Optionally specify -p to permanently delete the template.

Options: --server, -s <server> The registered CEC server --permanent, -p flag to indicate to permanently delete the template --help, -h Show help [boolean]

Examples: cec delete-template BlogTemplate cec delete-template BlogTemplate -p cec delete-template BlogTemplate -s UAT------------------------cec share-template------------------------Usage: cec share-template <name>

Shares template with users and groups on CEC server and assign a role. Specify the server with -s <server> or use the one specified in cec.properties file. The valid roles are




12-20

Examples: cec share-template Template1 -u user1,user2 -r manager Share template Template1 with user user1 and user2 and assign Manager role to them cec share-template Template1 -u user1,user2 -g group1,group2 -r manager Share template Template1 with user user1 and user2 and group group1 and group2 and assign Manager role to them cec share-template Template1 -u user1,user2 -r manager -s UAT Share template Template1 with user user1 and user2 and assign Manager role to them on the registered server UAT------------------------cec unshare-template------------------------Usage: cec unshare-template <name>

Deletes user or group access to a template on CEC server. Specify the server with -s <server> or use the one specified in cec.properties file.


Examples: cec unshare-template Template1 -u user1,user2 cec unshare-template Template1 -u user1,user2 -g group1,group2 cec unshare-template Template1 -u user1,user2 -s UAT------------------------cec describe-template------------------------Usage: cec describe-template <name>

Describes the template <name> package such as theme, components and content types.


Examples: cec describe-template StarterTemplate Describes the template StarterTemplate package------------------------cec create-template-report------------------------Usage: cec create-template-report <name>

Generates an asset usage report for the template <name> package. Optionally specify -o to save the report to a json file.

Options: --includepagelinks, -i Include validating page links --output, -o Output the report to a JSON file --help, -h Show help [boolean]


12-21

Examples: cec create-template-report StarterTemplate cec create-template-report StarterTemplate -o The report will be saved to StarterTemplateAssetUsage.json at the current local location cec create-template-report StarterTemplate -o ~/Documents The report will be saved to ~/Documents/StarterTemplateAssetUsage.json cec create-template-report StarterTemplate -o ~/Documents/StarterTemplateReport.json The report will be saved to ~/Documents/StarterTemplateReport.json cec create-template-report StarterTemplate -i Include validating page links------------------------cec add-component-to-template------------------------Usage: cec add-component-to-template <component>

Adds a component to a template and the component will be packaged with the template when export or upload the template.

Options: --template, -t The template [required] --help, -h Show help [boolean]

Examples: cec add-component-to-template Sample-To-Do -t BlogTemp------------------------cec remove-component-from-template------------------------Usage: cec remove-component-from-template <component>

Removes a component from a template.

Options: --template, -t The template [required] --help, -h Show help [boolean]

Examples: cec remove-component-from-template Sample-To-Do -t BlogTemp------------------------cec add-component-to-theme------------------------Usage: cec add-component-to-theme <component>

Adds a component to a theme. Optionally specify -c <category> to set the component category.

Options: --theme, -t <theme> Theme [required] --category, -c <category> component category --help, -h Show help [boolean]

Examples: cec add-component-to-theme Sample-To-Do -t BlogTheme


12-22

cec add-component-to-theme Sample-To-Do -t BlogTheme -c Samples------------------------cec remove-component-from-theme------------------------Usage: cec remove-component-from-theme <component>

Removes a component from a theme.

Options: --theme, -t <theme> Theme [required] --help, -h Show help [boolean]

Examples: cec remove-component-from-theme Sample-To-Do -t BlogTheme------------------------cec control-theme------------------------Usage: cec control-theme <action>

Perform <action> on theme on CEC server. Specify the theme with -t <theme>. Specify the server with -s <server> or use the one specified in cec.properties file. The valid actions are

publish

Options: --theme, -t <theme> The theme [required] --server, -s <server> The registered CEC server --help, -h Show help [boolean]

Examples: cec control-theme publish -t Theme1 Publish theme Theme1 on the server specified in cec.properties file cec control-theme publish -t Theme1 -s UAT Publish theme Theme1 on the registered server UAT------------------------cec share-theme------------------------Usage: cec share-theme <name>

Shares theme with users and groups on CEC server and assign a role. Specify the server with -s <server> or use the one specified in cec.properties file. The valid roles are


Options: --users, -u The comma separated list of user names --groups, -g The comma separated list of group names --role, -r The role [manager | contributor | downloader | viewer] to


12-23

assign to the users or groups [required] --server, -s <server> The registered CEC server --help, -h Show help [boolean]

Examples: cec share-theme Theme1 -u user1,user2 -r manager Share theme Theme1 with user user1 and user2 and assign Manager role to them cec share-theme Theme1 -u user1,user2 -g group1,group2 -r manager Share theme Theme1 with user user1 and user2 and group group1 and group2 and assign Manager role to them cec share-theme Theme1 -u user1,user2 -r manager -s UAT Share theme Theme1 with user user1 and user2 and assign Manager role to them on the registered server UAT------------------------cec unshare-theme------------------------Usage: cec unshare-theme <name>

Deletes user or group access to a theme on CEC server. Specify the server with -s <server> or use the one specified in cec.properties file.


Examples: cec unshare-theme Theme1 -u user1,user2 cec unshare-theme Theme1 -u user1,user2 -g group1,group2 cec unshare-theme Theme1 -u user1,user2 -s UAT------------------------cec create-site------------------------Usage: cec create-site <name>

Create Enterprise Site on CEC server. Specify the server with -s <server> or use the one specified in cec.properties file.

Options: --template, -t <template> Template [required] --repository, -r <repository> Repository, required for enterprise site --localizationPolicy, -l <localizationPolicy> Localization policy --defaultLanguage, -d <defaultLanguage> Default language, required for enterprise site --description, -p <description> Site description --sitePrefix, -x <sitePrefix> Site Prefix --update, -u Keep the existing id for assets --server, -s <server> The registered CEC server --help, -h Show help [boolean]

Examples: cec create-site Site1 -t StandardTemplate Creates a


12-24

standard site cec create-site Site1 -t Template1 -r Repository1 -l LocalizationPolicy1 -d en-US Creates an enterprise site with localization policy LocalizationPolicy1 cec create-site Site1 -t Template1 -r Repository1 -d en-US Creates an enterprise site and uses the localization policy in Template1 cec create-site Site1 -t Template1 -r Repository1 -d en-US -s UAT Creates an enterprise site on server UAT cec create-site Site1 -t Template1 -u -r Repository1 -d en-US -s UAT Creates an enterprise site on server UAT and keep the existing id for assets------------------------cec update-site------------------------Usage: cec update-site <name>

Update Enterprise Site on CEC server using the content from the template. Specify the server with -s <server> or use the one specified in cec.properties file.

Options: --template, -t <template> Template [required] --excludecontenttemplate, -x Exclude content template --server, -s <server> The registered CEC server --help, -h Show help [boolean]

Examples: cec update-site Site1 -t Template1 Updates site Site1 using the content from template Template1 cec update-site Site1 -t Template1 -x Updates site Site1 using the content from template Template1 excluding the "Content Template"------------------------cec transfer-site------------------------Usage: cec transfer-site <name>

Transfers Enterprise Site from one CEC server to another. Specify the source server with -s <server> and the destination server with -d <destination>.

Options: --server, -s The registered CEC server the site is from [required] --destination, -d The registered CEC server to create or update the site [required] --repository, -r Repository, required for creating enterprise site --localizationPolicy, -l Localization policy, required for creating enterprise site --help, -h Show help [boolean]

Examples: cec transfer-site Site1 -s DEV -d UAT -r Repository1 -l LocalizationPolicy1 Creates site Site1 on server UAT based on site Site1


12-25

on server DEV cec transfer-site Site1 -s DEV -d UAT Updates site Site1 on server UAT based on site Site1 on server DEV------------------------cec validate-site------------------------Usage: cec validate-site <name>

Validates site <name> on CEC server before publish or view publishing failure. Specify the server with -s <server> or use the one specified in cec.properties file.


Examples: cec validate-site Site1 Validate site Site1 on the server specified in cec.properties file cec validate-site Site1 -s UAT Validate site Site1 on the registered server UAT------------------------cec control-site------------------------Usage: cec control-site <action>

Perform <action> on site on CEC server. Specify the site with -s <site>. Specify the server with -r <server> or use the one specified in cec.properties file. The valid actions are

publish unpublish bring-online take-offline

Options: --site, -s <site> Site [required] --usedcontentonly, -u Publish used content only --compilesite, -c Compile and publish site --staticonly, -t Only publish site static files --server, -r <server> The registered CEC server --help, -h Show help [boolean]

Examples: cec control-site publish -s Site1 Publish site Site1 on the server specified in cec.properties file cec control-site publish -s Site1 -u Publish the site and all assets added to the site's pages cec control-site publish -s Site1 -c Compile and publish site Site1 cec control-site publish -s Site1 -t Only publish the static files of site Site1 cec control-site publish -s Site1 -r UAT Publish site Site1 on the


12-26

registered server UAT cec control-site unpublish -s Site1 -r UAT Unpublish site Site1 on the registered server UAT cec control-site bring-online -s Site1 -r UAT Bring site Site1 online on the registered server UAT cec control-site take-offline -s Site1 -r UAT Take site Site1 offline on the registered server UAT------------------------cec share-site------------------------Usage: cec share-site <name>

Shares site with users and groups on CEC server and assign a role. Specify the server with -s <server> or use the one specified in cec.properties file. The valid roles are



Examples: cec share-site Site1 -u user1,user2 -r manager Share site Site1 with user user1 and user2 and assign Manager role to them cec share-site Site1 -u user1,user2 -g group1,group2 -r manager Share site Site1 with user user1 and user2 and group group1 and group2 and assign Manager role to them cec share-site Site1 -u user1,user2 -r manager -s UAT Share site Site1 with user user1 and user2 and assign Manager role to them on the registered server UAT------------------------cec unshare-site------------------------Usage: cec unshare-site <name>

Deletes user or group access to a site on CEC server. Specify the server with -s <server> or use the one specified in cec.properties file.


Examples: cec unshare-site Site1 -u user1,user2


12-27

cec unshare-site Site1 -u user1,user2 -g group1,group2 cec unshare-site Site1 -u user1,user2 -s UAT------------------------cec set-site-security------------------------Usage: cec set-site-security <name>

Makes the site publicly available to anyone, restrict the site to registered users, or restrict the site to specific users. Specify the server with -r <server> or use the one specified in cec.properties file. Optionally specify -a <access> to set who can access the site. The valid group names are

Cloud users Visitors Service users Specific users

Options: --signin, -s If require sign in to access site: yes | no [required] --access, -a The comma separated list of group names --addusers, -u The comma separated list of users to access the site --deleteusers, -d The comma separated list of users to remove access from the site --server, -r <server> The registered CEC server --help, -h Show help [boolean]

Examples: cec set-site-security Site1 -s no make the site publicly available to anyone cec set-site-security Site1 -s no -r UAT make the site publicly available to anyone on server UAT cec set-site-security Site1 -s yes Require everyone to sign in to access this site and any authenticated user can access cec set-site-security Site1 -s yes -a "Visitors,Service users" Require everyone to sign in to access this site and all service visitors and users can access cec set-site-security Site1 -s yes -a "Specific users" -u user1,user2 Require everyone to sign in to access this site and only user1 and user2 can access cec set-site-security Site1 -s yes -d user1 Remove user1's access from the site------------------------cec index-site------------------------Usage: cec index-site <site>

Creates content item for each page with all text on the page. If the page index content item already exists for a page, updated it with latest text on the page. Specify -c <contenttype> to set the page index content type. Optionally specify -p to publish the page index items after creation or update. Specify the server with -s <server> or use the one specified in


12-28

cec.properties file.

Options: --contenttype, -c <contenttype> page index content type --publish, -p publish page index items --server, -s <server> The registered CEC server --help, -h Show help [boolean]

Examples: cec index-site Site1 -c PageIndex cec index-site Site1 -c PageIndex -p cec index-site Site1 -c PageIndex -s UAT------------------------cec create-site-map------------------------Usage: cec create-site-map <site>

Creates a site map for site on CEC server. Specify the server with -s <server> or use the one specified in cec.properties file. Optionally specify -p to upload the site map to CEC server after creation. Optionally specify -c <changefreq> to define how frequently the page is likely to change. Optionally specify -t <toppagepriority> as the priority for the top level pages. Also optionally specify <file> as the file name for the site map.

The valid values for <changefreq> are:

always hourly daily weekly monthly yearly never auto

Options: --url, -u <url> Site URL [required] --changefreq, -c How frequently the page is likely to change. --file, -f Name of the generated site map file --languages, -l <languages> The comma separated list of languages used to create the site map --publish, -p Upload the site map to CEC server after creation --toppagepriority, -t Priority for the top level pages, a decimal number between 0 and 1 --server, -s <server> The registered CEC server --newlink, -n Generate new 19.3.3 detail page link --noDefaultDetailPageLink, -o Do not generate detail page link for items/content lists that use the default detail page --help, -h Show help [boolean]

Examples:


12-29

cec create-site-map Site1 -u http://www.example.com/site1 cec create-site-map Site1 -u http://www.example.com/site1 -s UAT cec create-site-map Site1 -u http://www.example.com/site1 -t 0.9 cec create-site-map Site1 -u http://www.example.com/site1 -f sitemap.xml cec create-site-map Site1 -u http://www.example.com/site1 -p cec create-site-map Site1 -u http://www.example.com/site1 -c weekly -p cec create-site-map Site1 -u http://www.example.com/site1 -l de-DE,it-IT------------------------cec create-rss-feed------------------------Usage: cec create-rss-feed <site>

Creates RSS feed for site <site> on CEC server. Specify the server with -s <server> or use the one specified in cec.properties file. Optionally specify -x <template> to specify the RSS template. Optionally specify -p to upload the RSS feed to CEC server after creation.

Options: --url, -u <url> Site URL [required] --query, -q Query for content items [required] --limit, -l The limit of the items returned from the query [required] --orderby, -o The order by for the query [required] --language, -i The language for the query --template, -x The RSS xml template --javascript, -j Javascript file that contains functions to process Mustache data --title, -t The RSS feed title --description, -d The RSS feed description --ttl How long the data will last in number of minutes --file, -f Name of the generated RSS feed file --publish, -p Upload the RSS feed to CEC server after creation --server, -s <server> The registered CEC server --newlink, -n Generate new 19.3.3 detail page link --help, -h Show help [boolean]

Examples: cec create-rss-feed Site1 -u http://www.example.com/site1 -q 'type eq "BlogType"' -l 10 -o name:asc -t "Blog RSS" cec create-rss-feed Site1 -u http://www.example.com/site1 -q 'type eq "BlogType"' -l 10 -o name:asc -t "Blog RSS" -x ~/Files/RSSTemplate.xml cec create-rss-feed Site1 -u http://www.example.com/site1 -q 'type eq "BlogType"' -l 10 -o name:asc -t "Blog RSS" -x ~/Files/RSSTemplate.xml -i fr-FR -f rssfrFR.xml------------------------cec create-asset-report------------------------Usage: cec create-asset-report <site>

Generates an asset usage report for site <site> on CEC server. Specify the server with -s <server> or use the one specified in cec.properties file. Optionally specify -o to save the report to a json file.

Options: --output, -o Output the report to a JSON file


12-30

--server, -s The registered CEC server --help, -h Show help [boolean]

Examples: cec create-asset-report Site1 cec create-asset-report Site1 -s UAT cec create-asset-report Site1 -o The report will be saved to Site1AssetUsage.json at the current local location cec create-asset-report Site1 -o ~/Documents The report will be saved to ~/Documents/Site1AssetUsage.json cec create-asset-report Site1 -o ~/Documents/Site1Report.json The report will be saved to ~/Documents/Site1Report.json------------------------cec upload-static-site-files------------------------Usage: cec upload-static-site-files <path>

Uploads files to render statically from a site on CEC server. Specify the site <site> on the server. Specify the server with -r <server> or use the one specified in cec.properties file.

Options: --site, -s The site on CEC server [required] --server, -r The registered CEC server --help, -h Show help [boolean]

Examples: cec upload-static-site-files ~/Documents/localBlog -s BlogSite cec upload-static-site-files ~/Documents/localBlog -s BlogSite -r UAT------------------------cec download-static-site-files------------------------Usage: cec download-static-site-files <site>

Downloads the static files from a site on CEC server. Specify the server with -s <server> or use the one specified in cec.properties file. Optionally specify -f <folder> to save the files on the local system.

Options: --folder, -f <folder> Local folder to save the static files --server, -s The registered CEC server --help, -h Show help [boolean]

Examples: cec download-static-site-files BlogSite Download the files and save to local folder src/documents/BlogSite/static cec download-static-site-files BlogSite -f ~/Documents/BlogSite/static Download the files and save to local folder ~/Documents/BlogSite/static cec download-static-site-files BlogSite -s UAT------------------------cec delete-static-site-files------------------------Usage: cec delete-static-site-files <site>

Deletes the static files from a site on CEC server. Specify the server


12-31

with -s <server> or use the one specified in cec.properties file.

Options: --server, -s The registered CEC server --help, -h Show help [boolean]

Examples: cec delete-static-site-files BlogSite cec delete-static-site-files BlogSite -s UAT------------------------cec refresh-prerender-cache------------------------Usage: cec refresh-prerender-cache <site>

Refreshes pre-render cache for a site on CEC server. Specify the server with -s <server> or use the one specified in cec.properties file.


Examples: cec refresh-prerender-cache BlogSite cec refresh-prerender-cache BlogSite -s UAT------------------------cec migrate-site------------------------Usage: cec migrate-site <site>

Migrates a site from OCI IC server to EC server. Specify the IC server with -s <server> and the EC server with -d <destination>.

Options: --server, -s The registered IC server the site is from --destination, -d The registered EC server to create the site [required] --repository, -r Repository [required] --template, -t The site template --name, -n Site name --description, -p Site description --sitePrefix, -x Site Prefix --help, -h Show help [boolean]

Examples: cec migrate-site Site1 -s ICServer -d ECServer -r Repo1 Migrates site Site1 from ICServer to ECServer cec migrate-site Site1 -s ICServer -d ECServer -r Repo1 -n newSite Migrates site Site1 from ICServer to ECServer and rename to newSite cec migrate-site Site1 -d ECServer -t ~/Documents/Site1Template.zip -r Repo1 Migrates site Site1 to ECServer with template Site1Template.zip from IC server------------------------cec download-content------------------------


12-32

Usage: cec download-content <channel>

Downloads content in channel <channel> from CEC server. By default all assets are downloaded, optionally specify -p to download only published assets. Specify the server with -s <server> or use the one specified in cec.properties file.

Options: --publishedassets, -p The flag to indicate published assets only --collection, -c Collection name --repository, -r Repository name, required when <collection> is specified --query, -q Query to fetch the assets --assets, -a The comma separated list of asset GUIDS --name, -n The name for this download, default to the channel name --server, -s The registered CEC server --help, -h Show help [boolean]

Examples: cec download-content Site1Channel Download all assets in channel Site1Channel and save to local folder src/content/Site1Channel cec download-content Site1Channel -n Site1Assets Download all assets in channel Site1Channel and save to local folder src/content/Site1Assets cec download-content Site1Channel -p Download published assets in channel Site1Channel cec download-content Site1Channel -s UAT Download all assets in channel Site1Channel on server UAT cec download-content Site1Channel -a GUID1,GUID2 Download asset GUID1 and GUID2 and all their dependencies in chanel Site1Channel cec download-content Site1Channel -q 'fields.category eq "RECIPE"' Download assets from the channel Site1Channel, matching the query, plus any dependencies cec download-content Site1Channel -r Repo1 -c Collection1 Download assets from the repository Repo1, collection Collection1 and channel Site1Channel cec download-content Site1Channel -r Repo1 -c Collection1 -q 'fields.category eq "RECIPE"' Download assets from repository Repo1, collection Collection1 and channel Site1Channel, matching the query, plus any dependencies------------------------cec upload-content------------------------Usage: cec upload-content <name>

Uploads local content from channel <name>, template <name> or local file <name> to repository <repository> on CEC server. Specify -c <channel> to add the template content to channel. Optionally specify -l <collection> to add the content to collection. Specify the server with -s <server> or use


12-33

the one specified in cec.properties file.

Options: --repository, -r <repository> The repository for the types and items [required] --template, -t Flag to indicate the content is from template --file, -f Flag to indicate the content is from file --channel, -c <channel> The channel to add the content --collection, -l <collection> The collection to add the content --server, -s <server> The registered CEC server --update, -u Update any existing content instead of creating new items --help, -h Show help [boolean]

Examples: cec upload-content Site1Channel -r Repo1 Upload content to repository Repo1, creating new items, and add to channel Site1Channel cec upload-content Site1Channel -r Repo1 -u Upload content to repository Repo1, updating existing content to create new versions, and add to channel Site1Channel cec upload-content Site1Channel -r Repo1 -l Site1Collection Upload content to repository Repo1 and add to collection Site1Collection and channel Site1Channel cec upload-content Site1Channel -r Repo1 -s UAT Upload content to repository Repo1 on server UAT and add to channel Site1Channel cec upload-content Template1 -t -r Repo1 -c channel1 Upload content from template Template1 to repository Repo1 and add to channel channel1 cec upload-content ~/Downloads/content.zip -f -r Repo1 -c channel1 Upload content from file ~/Downloads/content.zip to repository Repo1 and add to channel channel1------------------------cec control-content------------------------Usage: cec control-content <action>

Performs action <action> on channel items on CEC server. Specify the channel with -c <channel>. Specify the server with -s <server> or use the one specified in cec.properties file. The valid actions are

publish unpublish add remove

Options: --channel, -c Channel [required] --repository, -r Repository, required when <action> is add --server, -s The registered CEC server --help, -h Show help [boolean]

Examples:


12-34

cec control-content publish -c Channel1 Publish all items in channel Channel1 on the server specified in cec.properties file cec control-content publish -c Channel1 -s UAT Publish all items in channel Channel1 on the registered server UAT cec control-content unpublish -c Channel1 -s UAT Unpublish all items in channel Channel1 on the registered server UAT cec control-content add -c Channel1 -r Repo1 -s UAT Add all items in repository Repo1 to channel Channel1 on the registered server UAT cec control-content remove -c Channel1 -s UAT Remove all items in channel Channel1 on the registered server UAT------------------------cec list-assets------------------------Usage: cec list-assets

Lists assets on CEC server. Optionally specify -c <channel>, -r <repository>, -l <collection> or -q <query> to query assets. Specify the server with -s <server> or use the one specified in cec.properties file.

Options: --channel, -c Channel name --collection, -l Collection name --repository, -r Repository name, required when <collection> is specified --query, -q Query to fetch the assets --server, -s The registered CEC server --help, -h Show help [boolean]

Examples: cec list-assets List all assets cec list-assets -s UAT List all assets on registered server UAT cec list-assets -r Repo1 List all assets from repository Repo1 cec list-assets -c Channel1 List all assets from channel Channel1 cec list-assets -r Repo1 -l Collection1 List all assets from collection Collection1 and repository Repo1 cec list-assets -q 'fields.category eq "RECIPE"' List all assets matching the query------------------------cec copy-assets------------------------Usage: cec copy-assets <repository>

Copies assets to another repository on CEC server. Specify the server with -s <server> or use the one specified in cec.properties file.

Options: --collection, -l Collection name --channel, -c Channel name --query, -q Query to fetch the assets --assets, -a The comma separated list of asset GUIDS --target, -t The target repository [required] --server, -s The registered CEC server


12-35


Examples: cec copy-assets Repo1 -t Repo2 Copy all assets in repository Repo1 to Repo2 cec copy-assets Repo1 -t Repo2 -s UAT Copy all assets in repository Repo1 to Repo2 on server UAT cec copy-assets Repo1 -a GUID1,GUID2 -t Repo2 Copy asset GUID1 and GUID2 and all their dependencies in Repo1 to Repo2 cec copy-assets Repo1 -q 'fields.category eq "RECIPE"' -t Repo2 Copy assets from repository Repo1, matching the query, plus any dependencies to Repo2 cec copy-assets Repo1 -c Channel1 -t Repo2 Copy assets from the repository Repo1 and channel Channel1 to Repo2 cec copy-assets Repo1 -l Collection1 -t Repo2 Copy assets from the repository Repo1 and collection Collection1 to Repo2 cec copy-assets Repo1 -c Channel1 -q 'fields.category eq "RECIPE"' -t Repo2 Copy assets from repository Repo1, channel Channel1, matching the query, plus any dependencies to Repo2------------------------cec create-asset-usage-report------------------------Usage: cec create-asset-usage-report <assets>

Generates an asset usage report for assets on CEC server. Optionally specify -o to save the report to a json file. Specify the server with -s <server> or use the one specified in cec.properties file.

Options: --output, -o Output the report to a JSON file --server, -s The registered CEC server --help, -h Show help [boolean]

Examples: cec create-asset-usage-report GUID1 cec create-asset-usage-report GUID1 -s UAT cec create-asset-usage-report GUID1 -o The report will be saved to GUID1AssetUsage.json cec create-asset-usage-report GUID1,GUID2 -o The report will be saved to GUID1_GUID2AssetUsage.json cec create-asset-usage-report GUID1,GUID2 -o ItemReport.json The report will be saved to ItemReport.json------------------------cec create-repository------------------------Usage: cec create-repository <name>

Creates a repository on CEC server. Specify the server with -s <server> or use the one specified in cec.properties file. Optionally specify -d <description> to set the description. Optionally specify -t <contenttypes>


12-36

to set the content types. Optionally specify -c <channels> to set the publishing channels. Optionally specify -l <defaultlanguage> to set the default language.

Options: --description, -d The description for the repository --contenttypes, -t The comma separated list of content types for the repository --channels, -c The comma separated list of publishing channels to use in this repository --defaultlanguage, -l The default language --server, -s The registered CEC server --help, -h Show help [boolean]

Examples: cec create-repository Repo1 cec create-repository Repo1 -d "Blog Repository" -t BlogType,AuthorType -c channel1,channel2 -l en-US -s UAT------------------------cec control-repository------------------------Usage: cec control-repository <action>

Performs action <action> on repository on CEC server. Specify the server with -s <server> or use the one specified in cec.properties file. The valid actions are

add-type remove-type add-channel remove-channel

Options: --repository, -r Repository [required] --contenttypes, -t The comma separated list of content types to add to the repository --channels, -c The comma separated list of publishing channels to add to the repository --server, -s The registered CEC server --help, -h Show help [boolean]

Examples: cec control-repository add-type -r Repo1 -t Blog,Author cec control-repository add-type -r Repo1 -t Blog,Author -s UAT cec control-repository remove-type -r Repo1 -t Blog,Author cec control-repository add-channel -r Repo1 -c channel1,channel2 cec control-repository remove-channel -r Repo1 -c channel1,channel2------------------------cec share-repository------------------------Usage: cec share-repository <name>

Shares repository with users and groups on CEC server and assign a role. Specify the server with -s <server> or use the one specified in


12-37

cec.properties file. Optionally specify -t to also share the content types in the repository with the users. Optionally specify -y <typerole> to share the types with different role. The valid roles are

manager contributor viewer

Options: --users, -u The comma separated list of user names --groups, -g The comma separated list of group names --role, -r The role [manager | contributor | viewer] to assign to the users or groups [required] --types, -t Share types in the repository --typerole, -y The role [manager | contributor | viewer] to assign to the users or groups for types --server, -s <server> The registered CEC server --help, -h Show help [boolean]

Examples: cec share-repository Repo1 -u user1,user2 -r manager Share repository Repo1 with user user1 and user2 and assign Manager role to them cec share-repository Repo1 -u user1,user2 -g group1,group2 -r manager Share repository Repo1 with user user1 and user2 and group group1 and group2 and assign Manager role to them cec share-repository Repo1 -u user1,user2 -r manager -s UAT Share repository Repo1 with user user1 and user2 and assign Manager role to them on the registered server UAT cec share-repository Repo1 -u user1,user2 -r manager -t Share repository Repo1 and all the types in Repo1 with user user1 and user2 and assign Manager role to them cec share-repository Repo1 -u user1,user2 -r manager -t -y contributor Share repository Repo1 with user user1 and user2 and assign Manager role to them, share all types in Repo1 with user user1 and user2 and assign Contributor role to them------------------------cec unshare-repository------------------------Usage: cec unshare-repository <name>

Deletes user or group access to a repository on CEC server. Specify the server with -s <server> or use the one specified in cec.properties file. Optionally specify -t to also delete the user or group access to the content types in the repository.

Options: --users, -u The comma separated list of user names --groups, -g The comma separated list of group names --types, -t Remove the user or group access to types in the repository --server, -s <server> The registered CEC server --help, -h Show help [boolean]

Examples:


12-38

cec unshare-repository Repo1 -u user1,user2 cec unshare-repository Repo1 -u user1,user2 -g group1,group2 cec unshare-repository Repo1 -u user1,user2 -s UAT cec unshare-repository Repo1 -u user1,user2 -t------------------------cec create-channel------------------------Usage: cec create-channel <name>

Creates a channel on CEC server. Specify the server with -s <server> or use the one specified in cec.properties file. Optionally specify -t <type> to set the channel type [public | secure], defaults to public. Optionally specify -p <publishpolicy> to set the publish policy [anythingPublished | onlyApproved], defaults to anythingPublished. Optionally specify -l <localizationpolicy> to set the localization policy.

Options: --description, -d The description for the channel --type, -t The channel type [public | secure] --publishpolicy, -p The publish policy [anythingPublished | onlyApproved] --localizationpolicy, -l The localization policy for the channel --server, -s The registered CEC server --help, -h Show help [boolean]

Examples: cec create-channel channel1 Create public channel channel1 and everything can be published cec create-channel channel1 -s UAT On registered server UAT, reate public channel channel1 and everything can be published cec create-channel channel1 -l en-fr Create public channel channel1 with localization policy en-fr and everything can be published cec create-channel channel1 -t secure -p onlyApproved Create secure channel channel1 and only approved items can be published------------------------cec create-localization-policy------------------------Usage: cec create-localization-policy <name>

Creates a localization policy on CEC server. Specify the server with -s <server> or use the one specified in cec.properties file. Specify -r <requiredlanguages> to set the required languages. Specify -l <defaultlanguage> to set the default language.Optionally specify -o <optionallanguages> to set the optional languages. Optionally specify -d <description> to set the description.

Options: --requiredlanguages, -r The comma separated list of required languages for the localization policy [required] --defaultlanguage, -l The default language [required] --optionallanguages, -o The comma separated list of optional languages for the localization policy --description, -d The description for the repository --server, -s The registered CEC server


12-39


Examples: cec create-localization-policy en-us -r en-US -l en-US cec create-localization-policy en-fr -r en-US,fr-FR -l en-US cec create-localization-policy multi -r en-US,fr-FR -l en-US -o zh-CN -d "Policy for Blog" -s UAT------------------------cec list-server-content-types------------------------Usage: cec list-server-content-types

Lists all content types from server.


Examples: cec list-server-content-types cec list-server-content-types -s UAT------------------------cec share-type------------------------Usage: cec share-type <name>

Shares type with users and groups on CEC server and assign a role. Specify the server with -s <server> or use the one specified in cec.properties file. The valid roles are

manager contributor viewer

Options: --users, -u The comma separated list of user names --groups, -g The comma separated list of group names --role, -r The role [manager | contributor | viewer] to assign to the users or groups [required] --server, -s <server> The registered CEC server --help, -h Show help [boolean]

Examples: cec share-type BlogType -u user1,user2 -r manager Share type BlogType with user user1 and user2 and assign Manager role to them cec share-type BlogType -u user1,user2 -g group1,group2 -r manager Share type BlogType with user user1 and user2 and group group1 and group2 and assign Manager role to them cec share-type BlogType -u user1,user2 -r manager -s UAT Share type BlogType with user user1 and user2 and assign Manager role to them on the registered server UAT------------------------cec unshare-type


12-40

------------------------Usage: cec unshare-type <name>

Deletes user or group access to a type on CEC server. Specify the server with -s <server> or use the one specified in cec.properties file.


Examples: cec unshare-type BlogType -u user1,user2 cec unshare-type BlogType -u user1,user2 -g group1,group2 cec unshare-type BlogType -u user1,user2 -s UAT------------------------cec create-contentlayout------------------------Usage: cec create-contentlayout <name>

Creates a content layout based on a content type from a local template or from CEC server. By default, an "overview" content layout is created. Optionally specify -s <style> to create in a different style.

Valid values for <style> are: detail overview

Options: --contenttype, -c <contenttype> Content layout is based on [required] --template, -t <template> Content type is from --server, -r The registered CEC server --style, -s <style> Content layout style: detail | overview --help, -h Show help [boolean]

Examples: cec create-contentlayout Blog-Post-Overview-Layout -c Blog-Post -t BlogTemplate cec create-contentlayout Blog-Post-Detail-Layout -c Blog-Post -t BlogTemplate -s detail cec create-contentlayout Blog-Post-Overview-Layout -c Blog-Post -r Use content type Blog-Post from the server specified in cec.properties file cec create-contentlayout Blog-Post-Overview-Layout -c Blog-Post -r UAT -s detail Use content type Blog-Post from the registered server UAT------------------------cec add-contentlayout-mapping------------------------Usage: cec add-contentlayout-mapping <contentlayout>

Creates content type and content layout mapping for a local template. By default, the mapping is set for "Default". Optionally specify -s <layoutstyle> to name the mapping. By default, the mapping is set for


12-41

desktop. Optionally specify -m to set the mapping for mobile.

Options: --contenttype, -c <contenttype> Content layout is based on [required] --template, -t <template> The mapping is for [required] --layoutstyle, -s <style> Content layout style --mobile, -m mobile mapping --help, -h Show help [boolean]

Examples: cec add-contentlayout-mapping Blog-Post-Detail-Layout -c Blog-Post -t BlogTemplate cec add-contentlayout-mapping Blog-Post-Detail-Layout -c Blog-Post -t BlogTemplate -m cec add-contentlayout-mapping Blog-Post-Detail-Layout -c Blog-Post -t BlogTemplate -s Details cec add-contentlayout-mapping Blog-Post-Overview-Layout -c Blog-Post -t BlogTemplate -s "Content List Default" cec add-contentlayout-mapping Blog-Post-Overview-Layout -c Blog-Post -t BlogTemplate -s Overview------------------------cec remove-contentlayout-mapping------------------------Usage: cec remove-contentlayout-mapping <contentlayout>

Removes a content layout mapping from a local template. By default, all mappings for the content layout are removed. Optionally specify -s <layoutstyle> to name the mapping and -m to indicate the mobile mapping.

Options: --template, -t <template> The mapping is from [required] --layoutstyle, -s <style> Content layout style --mobile, -m mobile mapping --help, -h Show help [boolean]

Examples: cec remove-contentlayout-mapping Blog-Post-Detail-Layout -t BlogTemplate cec remove-contentlayout-mapping Blog-Post-Detail-Layout -t BlogTemplate -m------------------------cec add-field-editor------------------------Usage: cec add-field-editor <name>

Adds a field editor to a field in a content type.

Options: --template, -t The template the content type is from [required] --contenttype, -c The content type [required] --field, -f The field the field editor is for [required] --contenttemplate, -n Flag to indicate the template is a content template --help, -h Show help [boolean]

Examples:


12-42

cec add-field-editor editor1 -t BlogTemplate -c BlogPost -f summary Use editor1 as the appearance for field summary in content type BlogPost from local template at src/templates/BlogTemplate cec add-field-editor editor1 -t BlogTemplateContent -n -c BlogPost -f summary Use editor1 as the appearance for field summary in content type BlogPost from local template at src/content/BlogTemplateContent------------------------cec remove-field-editor------------------------Usage: cec remove-field-editor <name>

Removes a field editor from a field in a content type.


Examples: cec remove-field-editor editor1 -t BlogTemplate -c BlogPost -f summary Remove editor1 as the appearance for field summary in content type BlogPost from local template at src/templates/BlogTemplate cec remove-field-editor editor1 -t BlogTemplateContent -n -c BlogPost -f summary Remove editor1 as the appearance for field summary in content type BlogPost from local template at src/content/BlogTemplateContent------------------------cec migrate-content------------------------Usage: cec migrate-content <name>

Migrates content from OCI IC server to EC server. Specify the IC server with -s <server> and the EC server with -d <destination>.

Options: --server, -s The registered IC server the content is from [required] --destination, -d The registered EC server to upload the content [required] --repository, -r The repository for the types and items [required] --channel, -c The channel to add the content --collection, -l The collection to add the content --help, -h Show help [boolean]

Examples: cec migrate-content collection1 -s ICServer -d ECServer -r Repo1 Migrates content from collection collection1 on ICServer to repository Repo1 on ECServer cec migrate-content collection1 -s ICServer -d ECServer -r Repo1 -l newCollection Migrates content from collection collection1 on ICServer to repository Repo1 and collection newCollection on ECServer cec migrate-content collection1 -s ICServer -d ECServer -r Repo1 -l newCollection -c channel1 Migrates content from collection collection1 on


12-43

ICServer to repository Repo1, collection newCollection and channel channel1 on ECServer------------------------cec list-translation-jobs------------------------Usage: cec list-translation-jobs

Lists translation jobs from local or from CEC server.


Examples: cec list-translation-jobs Lists local translation jobs cec list-translation-jobs -s Lists translation jobs on the server specified in cec.properties file cec list-translation-jobs -s UAT Lists translation jobs on the registered server UAT------------------------cec create-translation-job------------------------Usage: cec create-translation-job <name>

Creates a translation job <name> for a site on CEC server. Specify the server with -r <server> or use the one specified in cec.properties file. Specify -l <languages> to set the target languages, use "all" to select all languages from the translation policy. Optionally specify -c <connector> to set the translation connector. Optionally specify -t <type> to set the content type. The valid values for <type> are:

siteAll siteItems siteAssets

Options: --site, -s <site> Site [required] --languages, -l <languages> The comma separated list of languages used to create the translation job [required] --connector, -c The translation connector --type, -t The type of translation job contents --server, -r The registered CEC server --help, -h Show help [boolean]

Examples: cec create-translation-job job1 -s Site1 -l all cec create-translation-job job1 -s Site1 -l all -r UAT cec create-translation-job job1 -s Site1 -l de-DE,it-IT cec create-translation-job job1 -s Site1 -l de-DE,it-IT, -t siteItems cec create-translation-job job1 -s Site1 -l de-DE,it-IT -c Lingotek------------------------cec download-translation-job------------------------Usage: cec download-translation-job <name>


12-44

Downloads translation job <name> from CEC server. Specify the server with -s <server> or use the one specified in cec.properties file.


Examples: cec download-translation-job Site1Job cec download-translation-job Site1Job -s UAT------------------------cec submit-translation-job------------------------Usage: cec submit-translation-job <name>

Submits translation job <name> to translation connection <connection>.

Options: --connection, -c <connection> Connection [required] --help, -h Show help [boolean]

Examples: cec submit-translation-job Site1Job1 -c connector1-auto------------------------cec refresh-translation-job------------------------Usage: cec refresh-translation-job <name>

Refreshes translation job <name> from translation connection.


Examples: cec refresh-translation-job Site1Job1 cec refresh-translation-job Site1Job1 -s UAT Refresh translation job Site1Job1 on the registered server UAT------------------------cec ingest-translation-job------------------------Usage: cec ingest-translation-job <name>

Gets translated job <name> from translation connection and ingest.


Examples: cec ingest-translation-job Site1Job1 Ingest local translation job cec ingest-translation-job Site1Job1 -s DEV Ingest translation job Site1Job1 on the registered server DEV------------------------


12-45

cec upload-translation-job------------------------Usage: cec upload-translation-job <name>

Uploads translation <name> to CEC server, validate and then ingest the translations. Optionally specify -v to validate only. Optionally specify -f <folder> to set the folder to upload the translation zip file. Specify the server with -s <server> or use the one specified in cec.properties file.

Options: --folder, -f <folder> Folder to upload the translation zip file --validateonly, -v Validate translation job without import. --server, -s The registered CEC server --help, -h Show help [boolean]

Examples: cec upload-translation-job Site1Job File will be uploaded to the Home folder. cec upload-translation-job Site1Job -s UAT File will be uploaded to the Home folder on registered server UAT cec upload-translation-job Site1Job -f Import/TranslationJobs File will be uploaded to folder Import/TranslationJobs. cec upload-translation-job Site1Job -v Validate the translation job without import.------------------------cec create-translation-connector------------------------Usage: cec create-translation-connector <name>

Creates the translation connector <name>. By default, it creates a mockTranslationConnector. Optionally specify -f <source> to create from a different source.

Valid values for <source> are: mockTranslationConnector

Options: --from, -f <source> to create from --help, -h Show help [boolean]

Examples: cec create-translation-connector connector1------------------------cec start-translation-connector------------------------Usage: cec start-translation-connector <name>

Starts translation connector <name>. Optionally specify -p <port> to set the port, default port is 8084.

Options: --port, -p Set <port>. Defaults to 8084. --debug, -d Start the translation connector server with "--inspect"


12-46

option --help, -h Show help [boolean]

Examples: cec start-translation-connector connector1 cec start-translation-connector connector1 -p 7777 cec start-translation-connector connector1 -d Start the translation connector server with "--inspect" option to allow debugger to be attached.------------------------cec register-translation-connector------------------------Usage: cec register-translation-connector <name>

Registers a translation connector. Specify -c <connector> for the connector. Specify -s <server> for the connector server URL. Specify -u <user> and -p <password> for connecting to the server. Specify -f <fields> for custom fields.

Options: --connector, -c <connector> Connector name [required] --server, -s <server> Server URL [required] --user, -u <user> User name [required] --password, -p <password> password [required] --fields, -f <fields> translation connector custom fields --help, -h Show help [boolean]

Examples: cec register-translation-connector connector1-auto -c connector1 -s http://localhost:8084/connector/rest/api -u admin -p <password> -f "BearerToken:Bearer token1,WorkflowId:machine-workflow-id"------------------------cec create-group------------------------Usage: cec create-group <name>

Creates an OCE group on OCE server. Specify the server with -s <server>. Set the group type with -t <type>. The valid group types are

PUBLIC_OPEN PUBLIC_CLOSED PRIVATE_CLOSED

Options: --type, -t The group type [PUBLIC_OPEN | PUBLIC_CLOSED | PRIVATE_CLOSED] --server, -s <server> The registered CEC server --help, -h Show help [boolean]

Examples: cec create-group Group1 Create group Group1, people can add themselves to the group and share content with the group cec create-group Group1 -t PUBLIC_CLOSED Create group Group1, only group managers can add members but people can share content with the group


12-47

cec create-group Group1 -t PRIVATE_CLOSED Create group Group1, only group managers can add members and only members can share content with the group cec create-group Group1 -s DEV------------------------cec delete-group------------------------Usage: cec delete-group <name>

Deletes an OCE group on OCE server. Specify the server with -s <server>.

Options: --server, -s <server> The registered OCE server --help, -h Show help [boolean]

Examples: cec delete-group Group1 cec delete-group Group1 -s DEV------------------------cec add-member-to-group------------------------Usage: cec add-member-to-group <name>

Adds users and groups to an OCE group and assign a role on OCE server. Specify the server with -s <server>. The valid roles are

MANAGER MEMBER

Options: --users, -u The comma separated list of user names --groups, -g The comma separated list of group names --role, -r The role [MANAGER | MEMBER] to assign to the users or groups [required] --server, -s The registered OCE server --help, -h Show help [boolean]

Examples: cec add-member-to-group Group1 -u user1,user2 -g Group2,Group3 -r MEMBER cec add-member-to-group Group1 -u user1,user2 -g Group2,Group3 -r MEMBER -s DEV------------------------cec remove-member-from-group------------------------Usage: cec remove-member-from-group <name>

Removes users and groups from an OCE group on OCE server. Specify the server with -s <server>.

Options: --members, -m The comma separated list of user and group names [required] --server, -s The registered OCE server --help, -h Show help [boolean]


12-48

Examples: cec remove-member-from-group Group1 -m user1,user2,Group2,Group3 cec remove-member-from-group Group1 -m user1,user2,Group2,Group3 -s DEV------------------------cec create-encryption-key------------------------Usage: cec create-encryption-key <file>

Create an encryption key to encrypt/decrypt password for servers and save to <file>. Use NodeJS 10.12.0 or later.


Examples: cec create-encryption-key ~/.ceckey Create encryption key and save to file ~/.ceckey------------------------cec register-server------------------------Usage: cec register-server <name>

Registers a CEC server. Specify -e <endpoint> for the server URL. Specify -u <user> and -p <password> for connecting to the server. Optionally specify -k <key> to encrypt the password. Optionally specify -t <type> to set the server type. The valid values for <type> are:

pod_ec pod_ic dev_ec dev_osso

and the default value is pod_ec.

For pod_ec server, optionlly specify <idcsurl>, <clientid>, <clientsecret> and <scope> for headless commands.

Options: --endpoint, -e <endpoint> Server endpoint [required] --user, -u <user> User name [required] --password, -p <password> Password [required] --key, -k The key file used to encrypt the password --type, -t <type> Server type --idcsurl, -i <idcsurl> Oracle Identity Cloud Service Instance URL --clientid, -c <clientid> Client ID --clientsecret, -s <clientsecret> Client secret --scope, -o <clientsecret> Scope --timeout, -m Timeout in millisecond when try to login to the server. Defaults to 30000ms. --help, -h Show help [boolean]

Examples: cec register-server <server1> -e http://<server1>.com -u user1 -p <password> -i http://<idcs1>.com -c clientid -s clientsecret -o https://


12-49

primary-audience-and-scope The server is a tenant on Oracle Public cloud cec register-server <server1> -e http://<server1>.com -u user1 -p <password> The server is a tenant on Oracle Public cloud cec register-server <server1> -e http://<server1>.com -u user1 -p <password> -m 60000 The server is a tenant on Oracle Public cloud cec register-server <server1> -e http://<server1>.git.oraclecorp.com.com -u user1 -p <password> -t dev_ec The server is a standalone development instance cec register-server <server1> -e http://<server1>.com -u user1 -p <password> -k ~/.ceckey The password will be encrypted------------------------cec set-oauth-token------------------------Usage: cec set-oauth-token <token>

Set OAuth token for a registered server.

Options: --server, -s The registered CEC server [required] --help, -h Show help [boolean]

Examples: cec set-oauth-token token1 -s UAT Set OAuth token for server UAT, all CLI commands using UAT will be headless------------------------cec list------------------------Usage: cec list

Lists local or server resources such components and templates. Specify the server with -s <server> or use the one specified in cec.properties file. Optionally specify -t <types> to list specific types of resources on the CEC server.

Valid values for <types> on the server are:

channels components localizationpolicies recommendations repositories sites templates taxonomies translationconnectors

Options: --types, -t <types> The comma separated list of resource types


12-50

--server, -s <server> The registered CEC server --help, -h Show help [boolean]

Examples: cec list List all local resources cec list -s List resources on the server specified in cec.properties file cec list -t components,channels -s List components and channels on the server specified in cec.properties file cec list -t components,channels -s UAT List components and channels on the registered server UAT------------------------cec install------------------------Usage: cec install

Creates an initial source tree in the current directory.

With cec install, your source can be in a separate directory to the cec command install files, and you no longer need your source to be within a sites-toolkit directory.

The cec.properties file can be used to specify server settings. It will be picked up from the source directory, or can be specified with environment variable CEC_PROPERTIES

Use cec develop to start a dev/test server for your source. Different ports can be used for the server, to enable multiple source trees to exist.


Examples: cec install------------------------cec develop------------------------Usage: cec develop

Starts a test server in the current folder. Specify the server with -s <server> or use the one specified in cec.properties file. Optionally specify -p <port> to set the port, default port is 8085.

Options: --port, -p Set <port>. Defaults to 8085. --server, -s The registered CEC server --debug, -d Start the server with "--inspect" --help, -h Show help [boolean]

Examples: cec develop cec develop -p 7878 cec develop -p 7878 -s UAT------------------------cec sync-server


12-51

------------------------Usage: cec sync-server

Starts a sync server in the current folder to sync changes notified by web hook from <server> to <destination> server. Specify the source server with -s <server> and the destination server with -d <destination>. Optionally specify -p <port> to set the port, default port is 8086. To run the sync server over HTTPS, specify the key file with -k <key> and the certificate file with -c <certificate>. Set authorization option with -a and the valid values are

none basic header

Options: --server, -s The registered CEC server for sync source [required] --destination, -d The registered CEC server for sync destination [required] --authorization, -a The authorization method [none | basic | header] for the web hook event, defaults to basic --username, -u The username used to authenticate the web hook event when <authorization> is basic --password, -w The password used to authenticate the web hook event when <authorization> is basic --values, -v The comma separated list of name-value pairs used to authenticate the web hook event when <authorization> is header --port, -p Set port. Defaults to 8086. --key, -k The key file for HTTPS --certificate, -c The certificate file for HTTPS --help, -h Show help [boolean]

Examples: cec sync-server -s DEV -d UAT -u admin -w <password> Use Basic authorization cec sync-server -s DEV -d UAT -u admin -w <password> -p 7878 Use Basic authorization and port set to 7878 cec sync-server -s DEV -d UAT Use Basic authorization and the username and password will be prompted to enter cec sync-server -s DEV -d UAT -u admin Use Basic authorization and the password will be prompted to enter cec sync-server -s DEV -d UAT -a header -v key1:value1,key2:value2 Use Header authorization cec sync-server -s DEV -d UAT -a none No authorization cec sync-server -s DEV -d UAT -k ~/keys/key.pem -c ~/keys/cert.pem The sync server will start over HTTPS

Test with a Local Test HarnessRun your custom components, templates, and content layouts in a local test harnessbefore importing them to Content and Experience Cloud.


12-52

To start the local test harness:

1. Enter cd cec in a terminal window.

2. Enter cec develop & or cec develop --server <server-name> &

3. Open a browser at http://localhost:8085 to see your components, templates,and content layouts running in the local test harness.

4. You can find your components, templates, themes, and so on, in these directories:

• cec/src/main/components

• cec/src/main/templates

• cec/src/main/themes

Develop for Oracle Content and Experience with DeveloperCloud Service

OCE Toolkit, the Developer Cloud Service integration, helps you develop sitetemplates, themes, custom components, and content layouts for Oracle Content andExperience.

With OCE Toolkit, you can use asset repositories, files, and folders in Oracle Contentand Experience. OCE Toolkit has tools to create and develop custom components andsite templates, including themes and content layouts. It includes a Git repository aswell as a local test harness for quick, iterative development, and sample unit tests tostart with.

OCE Toolkit can help you do the following tasks:

• Set up your local development environment to use an Oracle Content andExperience instance for local development and testing of components, templates,themes, and content layouts

• Create components, site templates, and content layouts from samples, run them inthe test harness, explore them, and develop the components, templates, themes,and content layouts in a Developer Cloud Service environment

• Import components and site templates that were created in Oracle Content andExperience into a Developer Cloud Service environment for source managementand further development

• Export components, templates, and content layouts from a Developer CloudService environment for use in Oracle Content and Experience

• Copy an existing component, template, or content layout

• Write unit tests

• Optimize components

• Deploy your components and templates to Oracle Content and Experience

The following topics describe how to set up Developer Cloud Service for developingcustom components, site templates and themes, and content layouts:

1. About Using Developer Cloud Service

2. Sign In to the Developer Cloud Service Console for Oracle Content andExperience

Chapter 12Develop for Oracle Content and Experience with Developer Cloud Service

12-53

3. Create a Project in Developer Cloud Service

4. Add OCE Toolkit to the Project Code in the New Git Repository

5. Test Custom Components, Templates, and Content Layouts in a Local TestHarness

6. Merge Changes

The following topics provide information about using the Oracle Content andExperience OCE Toolkit:

• Use the cec Command-Line Utility

• Develop Custom Components with Developer Cloud Service

• Develop Templates with Developer Cloud Service

• Develop Content Layouts

About Using Developer Cloud ServiceOracle Developer Cloud Service is a cloud-based software development Platform as aService (PaaS) and a hosted environment for your application developmentinfrastructure. It provides an open source standards-based integration to develop,collaborate, and deploy applications within Oracle Cloud.

Developer Cloud Service is a collection of software and services hosted on OracleCloud to help you manage the application development life cycle effectively throughintegration with Git, Maven, issues, and wikis. Using Oracle Developer Cloud Service,you can commit your application source code to the Git repository on Oracle Cloud,track assigned issues and defects online, share information using wiki pages, peerreview the source code, and monitor project builds. After successful testing, you candeploy the project to Oracle Content and Experience.

Sign in to the Developer Cloud Service Console for Oracle Contentand Experience

Start developing your custom components for Oracle Content and Experience on theDeveloper Cloud Service console.

As an administrator for Oracle Cloud services, you can use My Service Administrationto create and manage your Cloud services. If you’re a service instance administratorfor Oracle Content and Experience and a service administrator for Standard DeveloperService, you can set them up and start using them:

1. Sign in to Oracle Cloud, using the information that was provided for your account.

2. Sign in to My Service Administration to create and manage your Oracle Contentand Experience instance and your Standard Developer Service.


12-54

3. Verify your Oracle Developer Cloud Service email, as requested.

4. Set up you Oracle Content and Experience instance, using the subscription detailsfor your service, and go to the Oracle Content and Experience URL for yourinstance.

5. Go to your URL for the Standard Developer Service.

6. Sign in to your Oracle Developer Cloud Service account.

Access the Developer Cloud Service URL and sign in to the console.

Create a Project in Developer Cloud ServiceYou can create a project in Developer Cloud Service using the "Content ExperienceCloud" project template.

Or you can create a project with an empty Git repository and import the OCE Toolkitfrom your Oracle Content and Experience instance.

Create a Developer Cloud Service Project with an Oracle Content andExperience Template

Create a project for developing custom components, templates, themes, and contentlayouts in Developer Cloud Service.

To create a project:

1. After you sign in to the Developer Cloud Service console, click New Project.


12-55

2. In the list of templates, choose Content and Experience Cloud, and then clickNext.

3. In the properties under Project Properties, choose CONFLUENCE in the WikiMarkup field.

Create a Project in Developer Cloud Service with an OCE Toolkit Downloadfrom Oracle Content and Experience

Create a project for developing custom components, templates, themes, and contentlayouts in Developer Cloud Service.

To create a project:

1. After you sign in to the Developer Cloud Service console, click New Project.


12-56

2. Name your project, enter or select other project details you want, and then clickNext.


12-57

3. In the list of templates, choose Initial Repository, and then click Next.

4. In the properties under Project Properties, choose Empty Repository for the InitialRepository. Click Finish.

Add OCE Toolkit to the Project Code in the New Git RepositoryYou can add OCE Toolkit to the new, empty Git repository for your project.

1. Under REPOSITORIES in your new project, copy the HTTP URL of the project Gitrepository.

2. Open a terminal window and enter this command: git clone <your-project>.git

a. When asked, enter your password for Developer Cloud Service.

b. If you see the error "git is not a command", install Git from https://git-scm.com/downloads, and then reenter the git clone command.

3. git clone [email protected]:oracle/content-and-experience-toolkit.git

Or you can download from here: https://github.com/oracle/content-and-experience-toolkit/archive/master.zip

4. cp -R content-and-experience-toolkit/sites/cec-components <your-project>

5. cd <your-project>

6. git add cec-components

7. git commit -a -m "<your comments>"

8. git push


12-58

Test Custom Components, Templates, and Content Layouts in a LocalTest Harness

Run your custom components, templates, and content layouts in a local test harnessbefore importing them to Oracle Content and Experience.

To start the local test harness:

1. Enter cd cec-components in a terminal window.

Enter npm start &

2. Open a browser at http://localhost:8085 to see your components, templates,and content layouts running in the local test harness.

When you test components on your local server, you can choose to use content from alocal template or from the Oracle Content and Experience server.

Merge ChangesAfter you create a component, template, or content layout or edit source code on yourlocal machine, you need to merge new and changed components and templates intoyour project’s Git repository.

To merge changes into your Git repository, enter the following commands, in order, ina terminal window.

cd cec-components git pull

git add .

git status

git commit -a -m "Your comments" git pull

git push

Propagate Changes from Test to Production with OCEToolkit

After you develop a site template, you can use the command-line interface (CLI) ofOCE Toolkit to propagate the template from development to test to production on yourOracle Content and Experience servers.

To propagate changes, you can use Toolkit commands to create sites and managetheir life cycles on development, test, and production servers. You can make changesto sites in a development environment and propagate those changes to test andproduction environments. You can also incorporate this set of command-line utilitiesinto your scripting environments to manage your deployments. With the CLI utilities,you can roll out new items, such as assets and components, as well as updates ofexisting content.

The following steps show how to use the OCE Toolkit CLI to propagate your changesfrom development to test to production:

1. Set up development, test, and production servers with the same repository andlocalization policy.

Chapter 12Propagate Changes from Test to Production with OCE Toolkit

12-59

To propagate changes from a development server to a test server and then to aproduction server, you need to set up a repository with the same name andlocalization policy on each of the three servers. The default localization policy forthe asset repository is en-US, but you can use a different one if it is the same in allthree servers.

See Set Up Asset Repositories in Creating Experiences with Oracle Content andExperience.

2. Register your development, test, and production servers with Oracle Content andExperience.

Before you propagate changes to a site, you need to register each of the servers.You can register a server with the cec register-server command provided byOCE Toolkit:

cec register-server <name>

Specify the following command options:

• -e <endpoint> for the server URL

• -u <user> and -p <password> for connecting to the server

• -t <type>, which is optional, to set the server type. The default value is pod_ec.

When connecting to an Oracle Content and Experience tenant on OraclePublic Cloud, use pod_ec only.

For example, the following command registers a server that is a tenant on OraclePublic cloud:

cec register-server DEV -e https://DEV.example.com -u user1 -p <password>

The next command registers a standalone development instance of OracleContent and Experience:

cec register-server DEV -e https://DEV.git.oraclecorp.example.com -u user1 -p <password>

After you register an Oracle Content and Experience server, you can list itscontents with the cec list Toolkit command.

The following command lists the contents of a development server:

cec-compontents> cec list -s DEV - Logged in to remote server: <host:port>Channels: Name Token StarterSite <site-id>

Components: Name Type Published FooterBar Component group StarterComponent Local component StarterFooter Component group


12-60

StarterNavMenu Local component

Localization policies: Name Required languages Optional Languages en-US en-US

Repositories: Name r

Sites: Theme Type Published Online Name StarterSiteTheme Enterprise

Templates: Name Theme Type StarterTemplate StarterTheme Standard

3. Upload a site template to your development server and create a site from thetemplate.

You can create a site template with the cec create-template command and thenupload the template to the development server. Then you can create a site fromthe template with the cec create-site command. The following commands createa template and upload the template:

- cec create-template blog -f BlogTemplate- cec upload-template blog -s DEV

The next command creates a site named blog from the uploaded template:

cec-components> cec create-site blog -t blog -r r -l "en-US" -d "en-US" --server DEV - Logged in to remote server: <https:<host:<port> - establish user session - get template - get repository - get localization policy - creating enterprise site . . . name blog template blog site prefix blog repository r localization policy en-US default language en-US - submit create site site - create site in process: percentage 95 - create site in process: percentage 95 - create site in process: percentage 95 - create site in process: percentage 95 - create site in process: percentage 95 - site created

4. Publish the site and bring it online on your development server.


12-61

After you create a site, you can use the cec control-site command to publishthe site and bring it online:

cec-components> cec control-siteUsage: cec contrl-site <action>Perform <action> on site in CEC server. Specify the site with -s <site> Specify the server with -r <server>.

publish unpublish bring-online take-offline

Options: --site, -s <site> Site --server, -r <server> The registered CEC server --help, -h Show help

Examples: cec control-site publish -s Site1 Publish site Site1 on the server cec control-site publish -s Site1 -r UAT Publish site Site1 on the registered server UAT cec control-site unpublish -s Site1 -r UAT Inpublish site Site1 on the registered server UAT cec control-site bring-online -s Site1 -r UAT Bring site Site1 online on the registered server UAT cec control-site take-offline -s Site1 -r UAT Take site Site1 offline on the registered server UAT

Not enough non-option arguments: got 0, need at least 1cec-components> cec control-site publish --site blog --server DEV - Logged in to the remote server: https://<host>:<port> - establish user session - get site: runtimeStatus: offline publishStatus: unpublished - submit publish site - publish in process: percentage 20 - publish in process: percentage 40 - publish in process: percentage 49 - publish in process: percentage 49 - publish in process: percentage 50 - publish in process: percentage 50

5. To move a site from DEV to UAT, you need to package up the site. The packagingmodel for moving sites between servers is the template. Create a new templatefrom the site you created on your development server and download the template.

The cec create-template-from-site command in the following example createsa site template named blog2 from blog.

cec create-template-from-site blog2 -s blog


12-62

Download the template you created from your development site with the cecdownload-template command:

cec-components: cec download-template blog2 --server DEV - Logged in to remote server: https://<host>:<port> - establish user session - export template - template download to /Users/<user-name>/devenv/git/webclient/developer/sites-toolkit/cec-components/dist/blog2.zip - the template will be at /Users/<user-name>/devenv/git/webclient/developer/sites-toolkit/cec-components/src/main/templates/blog2 - the theme for the template will be at /Users/<user-name>/devenv/git/webclient/developer/sites-toolkit/cec-components/src/main/themes/blogTheme - create link _scs_theme_root_ - create link _scs_design_name_ - override component /Users/<user-name>devenv/git/webclient/developer/sites-toolkit/cec-components/src/main/components/Starter-Blog-Author-Summary - override component /Users/<user-name>devenv/git/webclient/developer/sites-toolkit/cec-components/src/main/components/Starter-Blog-Post-Content - override component /Users/<user-name>devenv/git/webclient/developer/sites-toolkit/cec-components/src/main/components/Starter-Blog-Post-Header - override component /Users/<user-name>devenv/git/webclient/developer/sites-toolkit/cec-components/src/main/components/Starter-Blog-Post-Search-Result - override component /Users/<user-name>devenv/git/webclient/developer/sites-toolkit/cec-components/src/main/components/Starter-Blog-Post-Post-Sidebar - override component /Users/<user-name>devenv/git/webclient/developer/sites-toolkit/cec-components/src/main/components/Starter-Blog-Post-Summary - set themeName to blogTheme in siteinfo.json - unzip tmplate content file *** template is ready to test: https://localhost:8085/templates/blog2cec upload-template blog2 --server UAT

6. Upload the template to create the content types and content layout maps.

cec upload-template blog2 --server UAT

7. Upload the template but exclude the content items (content template) from thetemplate.

cec upload-template blog2 --server UAT -x

You want to do this to create a site with content that has the same GUIDs as theoriginal site. When you create a site from a template that contains content, all thecontent in the new site will have new GUIDs. Because we want to allow update ofcontent rather than creating new content, you need to exclude the content from thetemplate.


12-63

8. Create the site from the template.

cec create-site blog -t blog2 -r r -l "en-US" -d "end-US" --server UAT

9. Upload the content template to the site's channel and collection. You need to dothis because you excluded it from the template in step 7.

cec upload-content blog2 -t -r r -c blog -l "blog site" --server UAT

10. Publish the site and bring it online on your test server.

Use the cec control-site command to publish the site and bring it online:

cec-components> cec control-site publish --site blog --server UAT - Logged in to the remote server: https://<host>:<port> - establish user session - get site: runtimeStatus: offline publishStatus: unpublished - submit publish site - publish in process: percentage 20 - publish in process: percentage 40 - publish in process: percentage 49 - publish in process: percentage 49 - publish in process: percentage 50 - publish in process: percentage 50 - publish blob finished

11. If you then make changes to your site blog on the DEV server, you can propagatethe changes to the site you have already created on the UAT server.

12. Create another template from your site so the template will have your changes.

cec create-template-from-site blog3 -s blog --server DEV

13. Download the template.

cec download-template blog3 -s DEV


12-64

14. Upload the template and create a site from it to propagate the changes to your testenvironment.

cec upload-template blog3 -s UAT

This command creates or updates any components and themes that havechanged, but excludes the content.

15. Now use the update-site command to pick up the content and update the pages.

cec update-site blog -t blog3 - UAT

For example:

cec-components> cec update-site blog -t blog3 --server UATUpdating site: blog3 - Logged in to remote server: https://<host>:<port> - pages : updating file# 6 of 6 files - content : updating file# 3 of 3 files - System Files : updating file# 5 of 5 files - controller : no files in update, removing files on server - favicons : no files in update, removing files on server - misc : no files in update, removing files on server - seo : no files in update, removing files on server - system : no files in update, removing files on server - created content file /Users/<user-name>/devenv/git/webclient/developer/sites-toolkit/cec-compnents/dist/blog3_export.zip - upload content file - get CSRF token - submit import job, updating content - import job in progress. . . - import job in progress. . . - import job in progress. . . - content imported:Update Site Results: - Site Pages : completed with 0 errors. - Embedded Content : completed with 0 errors. - System Files : completed with 0 errors. - Settings Files : completed with 0 errors. - Content Update : completed with 0 errors.

16. Check the site to verify that the changes were propagated.

17. Do the same steps to move from the UAT server to the PROD server as you did tomove the site from DEV to UAT.

18. Create the site on your production server, bring it online, and verify the changes.


12-65

You can use the cec list command to view the contents of your production siteand make sure it includes the changes you made in the development environment.Also, you can check the site to verify that the changes have been propagated toproduction.

Encrypt a PasswordWhen you register a server with OCE Toolkit, you need to encrypt a password to makethe server available for local use.

1. Register an Oracle Content and Experience server with a cec register-servercommand that includes the password in plain text.

2. Encrypt the password with the cec create-encryption-key command.

cec create-encryption-key <file> [alias: cek] Create an encryption key to encrypt/decrypt password for servers.

3. Register the server again with the encryption key, which makes the serveravailable for local development and testing.

Encrypted passwords are stored in the server connection file. A password is decryptedwhen you connect to a registered server.

Register a ServerYou can register a server in OCE Toolkit.

Use the cec register-server command with an encryption key to register a Contentand Experience Server for local development and testing.

When you register the server, encrypting a password makes the server available foruse with OCE Toolkit. See Encrypt a Password.

Create a Usage and Permission Report for a SiteYou can create a report to validate and fix permissions of target server members fortest-to-production propagation for a site.

Use the cec create-asset-report and check it as follows:

1. Check the membership and channel assignment of all site artifacts:

• Theme


12-66

• Template

• Components

• Content type

2. Flag issues that you can address.

For example:

cec create-asset-report blog1 -s <registered-server> -o

cec create-asset-report trbcent -s <registered-server> -o

The report is generated in a JSON file, which you can check for problems with usageand permissions. The following commands are available for permission fixes:

• cec share-type: Share types with users in an Oracle Content and Experienceserver.

• cec unshare-type: Remove access to types for given users in an Oracle Contentand Experience server.

• cec share-repository: Share a repository (and the types used by the repository)in an Oracle Content and Experience server.

• cec unshare-repository: Remove user access to a repository in an OracleContent and Experience server.

• For example:

cec share-repository Repo1 -u <user-name1>,<user-name2> -r manager -t -s <registered-server>

Download and Upload Documents and FoldersYou can download and upload documents and folders to and from an Oracle Contentand Experience server.

The following commands are available for document and folder downloads anduploads:

cec download-folder <path> Downloads folder from CEC server. [alias: dlfd] cec upload-folder <path> Uploads folder to CEC server. [alias: ulfd] cec download-file <file> Downloads file <file> from CEC server. [alias: dlf] cec upload-file <file> Uploads file <file> to CEC server. [alias: ulf] cec-share-folder <name> cec-unshare-folder <name>

For cec-share-folder <name>, you can share a folder with users on an OracleContent and Experience server and assign users a role. Specify the server with -s<server>, or use the server specified in the cec.properties file. The valid roles follow:


12-67

• manager

• contributor

• downloader

• viewer

For downloads, you can specify a folder hierarchy.

Create a Site from a Template and Keep the Same GUIDsfor Content

As a developer, you can use an OCE Toolkit command to create an Oracle Contentand Experience site from a template, keeping the same GUIDs for content.

Use the following OCE Toolkit command:

update create-site-from-template --reuse-content

This command creates a site in an Oracle Content and Experience server andpreserves content IDs when creating the site. Preserving content IDs is necessary formultiple test to production runs to not end up with duplicate content items on a targetserver.

Import and Export TaxonomiesUse OCE Toolkit commands to import taxonomies from an Oracle Content andExperience server to your local machine or to export taxonomies from your localmachine to the server.

The cec download-taxonomy <name> command imports a taxonomy from OracleContent and Experience. It downloads a taxonomy from an Oracle Content andExperience server.

You can use the following options in this command:

• --status, -t [promoted | published] [required]: Specify the taxonomystatus.

• --id, -i: If another taxonomy has the same name, specify the taxonomy ID.

• --server, -s: Specify a registered Oracle Content and Experience server, or usethe one specified in the cec.properties file.

• --help, -h: Show help for the command.

Some examples of the download-taxonomy command follow:

cec download-taxonomy Taxonomy1 -t promoted

cec download-taxonomy Taxonomy1 -i 6A6DC736572C468B90F2A1C17B7CE5E4 -t promoted

cec download-taxonomy Taxonomy1 -t published -s UAT

Chapter 12Create a Site from a Template and Keep the Same GUIDs for Content

12-68

The cec upload-taxonomy <taxonomy> command exports a taxonomy to OracleContent and Experience. It uploads a taxonomy to an Oracle Content and Experienceserver.

You can use the following options in this command:

• --createnew, -c: Create new a taxonomy.

• --name, -n: Specify the name of the new taxonomy.

• --abbreviation, -a: Specify an abbreviation for the new taxonomy.

• --description, -d: Specify a description of the new taxonomy.

• --file, -f: Indicate whether the taxonomy is from a file.

• --server, -s: Specify a registered Oracle Content and Experience server, or usethe one specified in the cec.properties file.

• --help, -h: Show help for the command.

Some examples of the upload-taxonomy command follow:

cec upload-taxonomy Taxonomy1Create a new taxonomy or a draft of an existing taxonomy on upload

cec upload-taxonomy Taxonomy1 -s UAT Create a new taxonomy or a draft of an existing taxonomy on upload on the registered server UAT

cec upload-taxonomy Taxonomy1 -c Create a new taxonomy on upload

cec upload-taxonomy Taxonomy1 -c -n Taxonomy1_2 -a t12 -d Create a new taxonomy on upload with the given name, abbreviation

"Taxonomy1 copy" and description cec upload-taxonomy Create a new taxonomy or a draft of an existing taxonomy in <file-name>.json -f and upload the JSON file

Develop Custom Field EditorsOCE Toolkit provides support for developing components of the Field Appearancetype. Developers can create and manage custom field editors.

For a component of the Field Appearance type, you can do the following tasks:

• Open, copy, or delete the component

• Publish or unpublish the component

• Export or import the component

• Add or remove members on the component

• View properties

• Choose the component logo

You can filter a list of components by the Field Appearance type.

Chapter 12Develop Custom Field Editors

12-69

The following OCE Toolkit commands are available for developing custom fieldeditors:

cec add-field-editor <name> Adds a field editor to a field in a content type. [alias: afe] cec remove-field-editor <name> Removes a field editor from a field in a content type. [alias: rfe]

------------------------cec add-field-editor------------------------Usage: cec add-field-editor <name>

Adds a field editor to a field in a content type.


Examples: cec add-field-editor editor1 -t BlogTemplate -c BlogPost -f summary Use editor1 as the appearance for field summary in content type BlogPost from local template at src/templates/BlogTemplate cec add-field-editor editor1 -t BlogTemplateContent -n -c BlogPost -f summary Use editor1 as the appearance for field summary in content type BlogPost from local template at src/content/BlogTemplateContent------------------------cec remove-field-editor------------------------Usage: cec remove-field-editor <name>

Removes a field editor from a field in a content type.


Examples: cec remove-field-editor editor1 -t BlogTemplate -c BlogPost -f summary Remove editor1 as the appearance for field summary in content type BlogPost from local template at src/templates/BlogTemplate cec remove-field-editor editor1 -t BlogTemplateContent -n -c BlogPost -f summary Remove editor1 as the appearance for field summary in content type BlogPost from local template at src/content/BlogTemplateContent

These samples of Field Appearance components are included with OCE Toolkit:


12-70

• TextFieldEditor

• SliderFieldEditor

• MapFieldEditor

The following image shows OCE Toolkit commands you can use to develop thesample Field Appearance components.

You can create the out-of-the-box Field Appearance components on your local server,test them, and then upload them to your Oracle Content and Experience instance. Thefollowing image shows these components on localhost:8085.

You can test each component, such as slider, on the local server. There you canselect properties for the component and then save it.


12-71

For the map component, you can click around on the map to provide a location as theeditor value.

You can edit the HTML file for a component to change its settings, such asbackground color.


12-72

After you finish configuring and testing the custom field editors, you can upload themto your Oracle Content and Experience instance, using OCE Toolkit commands:

# upload editorscec ulcp editor1,slider -p -s Latest

# upload content

cec cr Repo5 -s

cec upload-content SimpleContent -r Rpo5 -s

When you upload the custom field editors, your components are imported into yourOracle Content and Experience instance.


12-73

If you have the same component locally, you can use OCE Toolkit commands to add afield editor to any field of a component in the Oracle Content and Experience instance:

cec add-field-editor editor1 -t SimpleContent -n -c SimpleType -f title

cec add-field-editor slider -t SimpleContent -n -c SimpleType -f value

Then you can upload the field editors and content to a repository in the Oracle Contentand Experience instance:

# upload editorscec ulcp editor1,slider -p -s

# upload content

cec upload-content SimpleContent -r Repo5 -s latest

Transfer or Update a Site from One Server to AnotherAs a developer, you can use an OCE Toolkit command to create or update a site andits content from server A to server B.

You can use the following command to update or transfer a site from test toproduction:

cec transfer-site site --from server --to server --repository r --localization-policy l

Index Site Pages with OCE ToolkitYou can use OCE Toolkit to create content items for text on site pages and to enablepage search for a site.

The following sections describe how to index site pages with OCE Toolkit:

1. Create the Content Type for Site Page Text

2. Create Page Index Content Items with OCE Toolkit

3. Add Content Search to a Site in Oracle Content and Experience

Create the Content Type for Site Page TextFor a content type, you specify a name, required field values, a default content layoutfor the type.

• Type name

Specify any valid content type name.

• Fields

The following fields are required.

Chapter 12Transfer or Update a Site from One Server to Another

12-74

Field Name Field Type Number of data fieldvalues

Description

site Text Single Site name

pageid Text Single Page ID

pagename Text Single Page name

pageurl Text Single Page URL

pagedescription Text Single Page description

keywords Text Multiple (no max) All text on the page and thevalues from all text fields ofcontent items on the page,obtained by the OCEToolkit index-sitecommand

{{#fields}}<div class="indextype"></div><div> <a href="{{pageFullURL}}" title="{{pagename}}">{{pagename}}</a></div>{{/fields}}

content.fields.pageFullURL = SCSRenderAPI.getSitePrefix() + content.fields.pageurl;

• Create a content layout for the type.

The content layout should display the site name and the URL to navigate to thepage. For example, in layout.html:

{{#fields}}<div class="indextype"></div><div> <a href="{{pageFullURL}}"title="{{pagename}}">{{pagename}}</a></div>{{/fields}}

• In render.js, generate the page full URL:

content.fields.pageFullURL =SCSRenderAPI.getSitePrefix() + content.fields.pageurl;

• Set the content layout as the default content layout for the type.

content.fields.pageFullURL = SCSRenderAPI.getSitePrefix() + content.fields.pageurl;

Create Page Index Content Items with OCE ToolkitYou can use an OCE Toolkit command to create page index content items.

Chapter 12Index Site Pages with OCE Toolkit

12-75

Prerequisites:

• OCE Toolkit has been installed and set up on your local machine.

• The site on Oracle Content and Experience has been published.

• The content items on the site page have been published to the site channel.

In a command-line interface, type the following OCE Toolkit command:

cec index-site site name -c content type name -p

In the command, site name is the name of the site, content type name is the contenttype created for the page text; and the option -p indicates to publish the page indexcontent items after creation.

Usage: cec index-site <site>

Create content item for each page with all text on the page. If the page index content item already exists for a page, updated it with latest text on the page. Specify -c<contenttype> to set the page index content type. Optionally specify -p to publish the page index items after creation or update.

Options: --contenttype, -c <contenttype> page index content type --publish, -p publish page index items --help, -h Show help [boolean]

Examples: cec index-site Site1 -c PageIndex cec index-site Site1 -c PageIndex -p

To see the usage, you can type cec index-site -h

Add Content Search to a Site in Oracle Content and ExperienceYou can add content search to an Oracle Content and Experience site with a searchpage and search field.

To add content search to a site:

1. Add a Search Page to the Site

2. Add a Search Field to the Theme

Add a Search Page to the SiteYou can add a search page to a site and a Content List component to the searchpage.

Add the search page:

1. Add a page to the site and set it as a search page.

Chapter 12Index Site Pages with OCE Toolkit

12-76

2. Add a Content List component to the search page.

3. Set Content Type to the page index content type created previously.

Add a Search Field to the ThemeTo make a search field show on every page of a site, you can add the search field tothe theme’s layout HTML page.

For example:

<div align="center"><input id="searchonpage" type="text" size="30" placeholder="Search on page. . ."/></div>

1. Add the input field :

<script> // Get the search field element const node = document.getElementById('searchonpage'); // Get the search string from the url if it exists var params = (new URL(document.location)).searchParams; var defaultStr = params && params.get('default'); if (defaultStr) { if (defaultStr.lastIndexOf('*') === defaultStr.length - 1) { defaultStr = defaultStr.substring(0, defaultStr.length - 1); } // Display the search string in the search field node.value = defaultStr; } // When enter from the search field, go to the site search page with the search string node.addEventListener('keydown', function onEvent(event) { if (event.key === "Enter") { var inputElem = event.srcElement || event.target; var siteSearchPageUrl = 'search.html'; var searchUrl = SCSRenderAPI.getSitePrefix() + siteSearchPageUrl + '?contentType=indextype&default=' + inputElem.value + '*'; window.location = searchUrl; } });</script>

2. Add the JavaScript at the end of the HTML body.

Index a Multilingual Site with OCE ToolkitYou can use OCE Toolkit to index multilingual (MLS) sites for translations and forsearching pages and content items.

Chapter 12Index a Multilingual Site with OCE Toolkit

12-77

You can build a multilingual site index and test it before publishing the site. Use theOCE Toolkit cec index-site command to index a multilingual site. Go to the cec-components directory and issue this command without any options to view the helpinformation for the command:

cec-components> cec index-siteUsage: cec index-site <site>

Create content item for each page with all text on the page. If the page index content item already exists for a pate, updated it with latesttext on the page. Specify -c <contenttype> to set the page index content type. Optionally specify -p to publish the page index items aftercreation or update.

Options: --contenttype, -c <contenttype> page index content type --publish, -p publish page index items --help, -h Show help [boolean]

Examples: cec index-site Site1 -c PageIndex cec index-site Site1 -c PageIndex -p

Page index items exist per page and per language. The page index content itemscreated for each language are created as translations of the default language pageindex items. When you do a query in the running site, the search and the content listpick up the language from the site URL. This filters the search automatically.

Before you can publish a multilingual site, you need to index and translate it, for whichyou will need a translation job. See Create a New Site or Asset Translation Job in theOracle Content and Experience Server.

The default language, English, is required. For each language supported (required andoptional), execute the index creation and create translations of index items. If you runthe index twice, it just does an update.

To index, translate, and publish a multilingual site using OCE Toolkit commands:

1. Crate a content type for the site and make it available in the repository. See Create the Content Type for Site Page Text.

2. Select a validation policy.

a. Click Assets in the left navigation menu.

b. Choose Localization Policies in the Assets menu.

c. Select a localization policy.

d. Modify the localization policy, if necessary, to include the languages you wantto use for indexing and translating the site. For example, if the policy has onlyEnglish, you can add French and Spanish.

All translations are done from from English.

3. Download a translation job. Before downloading, you can create You can translateonly the assets that are used in the site.


12-78

4. Use the cec index-site command to index and translate the site. Specify the -csearch_content_type option. This translates

You can also specify the -p option to publish the site. Then you can validate theindexing and translation before publishing the changes to the live site.

For example, the following cec index-site command builds a site index for a sitethat uses English, French, and Spanish. The languages supported by the site arefrom the assigned L10n policy, including the default language.

cec index-site Demo2 -c search_content_type -p - Logged in to remote server: server-URL - establish user session - get CSRF token - site: Demo2, default language: en-US, channel token: channel-token - site localization policy: search_localization_policy - query site repository - query content type search_content_type - query site structure - content types used in the site: search_blog - query page data - query content on the pages - will create 11 page index items - will update 0 page index items - will remove 1 page index items - create page index item for Blog - create page index item for Privacy Policy - create page index item for Search - create page index item for Components - create page index item for Navigtion - create page index item for Detail Page - create page index item for Pages - create page index item for Page Content - create page index item for Developing Templates - create page index item for Themes - add page index items to site channel - remove page index items for page Search from site channel - will create/update translate for fx-FR,es-ES - query site stucture with locale fr-FR - query page data (fr-FR) - query content on the pages (fr-FR) - will create 11 page index items (fr-FR) - will update 0 page index items (fr-FR) - will remove 1 page index items (fr-FR) - create page index item for Themes (fr-FR) - create page index item for Navigation (fr-FR) - create page index item for Pages (fr-FR) - create page index item for Detail Page (fr-FR) - create page index item for Search (fr-FR) - create page index item for Page Content (fr-FR) - create page index item for Components (fr-FR) - create page index item for Developing Templates (fr-FR) - create page index item for Blog (fr-FR) - create page index item for Home (fr-FR) - create page index item for Privacy Policy (fr-FR) - add page index items to site channel


12-79

- set page index items in fr-FR as translated - remove page index items for page Search from site channel - query site stucture with locale es-ES - query page data (es-ES) - query content on the pages (es-ES) - will create 11 page index items (es-ES) - will create 0 page index items (es-ES) - create page index item for Pages (en-ES) - create page index item for Home (en-ES) - create page index item for Themes (en-ES) - create page index item for Components (en-ES) - create page index item for Privacy Policy (en-ES) - create page index item for Detail Page (en-ES) - create page index item for Page Content (en-ES) - create page index item for Navigation (en-ES) - create page index item for Developing Templates (en-ES) - create page index item for Search (en-ES) - create page index item for Blog (en-ES) - add page index items to site channel - set page index items in es-ED as translated - publish job submitted - publish in proogress - publish in progress - publish page index items finished

5. Publish the site to include translations.

Create a Simplified Component for Easy ComponentDevelopment

Use OCE Toolkit to create a simplified component for easier development.

SimpleHTML, a simplified component, is available in OCE Toolkit to give you an easierstarting point for custom component development:

cec create-component -f SimpleHTML

A sample for JET component is also available for you to start with:

cec create-component MyComp -f JET-CCA-Demo-Card

Compile a Site to Improve Runtime Performance for SitePages

Compilation of a site in Oracle Content and Experience can improve the runtimeperformance and behavior of site pages. Compilation achieves this by creating a staticHTML file for each page in the site that will behave exactly as the original page.

Chapter 12Create a Simplified Component for Easy Component Development

12-80

Overview of Site CompilationThe metadata files that constitute a site "page" are combined during compilation,avoiding the server requests that are normally required at runtime. You're effectivelymoving the per-page-view render cost to a one-off compile-time cost.

Performance improvements are achieved by reducing the number of runtime requests.This can include avoiding all content queries because you can compile the results ofthese queries directly into the page.

Behavioral improvements are achieved because a page renders immediately.Therefore, you can avoid issues such as "flash of unstyled content" or havingcomponents appear on the page in an indeterminate order, such as where the footerappears immediately and then moves down the page as the other items on the pagerender.

To compile the pages within an Oracle Content and Experience site, you need toexport the site as a template and then use the OCE Toolkit to compile the templateand upload the static pages produced to the original site. The following steps walk youthrough the template compilation process and then how to use this model to compileyour sites.

Interaction with PrerenderPrerender is focused on returning results suitable to a search engine. The pagesproduced by prerender are not expected to run as the original page did, and noJavaScript is executed. It simply returns the browser-prerendered HTML to supportSEO text search.

The static pages created by site compilation are expected to run in the browser andbehave exactly as the original dynamic sites page. This includes running noncompiledcomponents dynamically and executing runtime queries where the user wantscompletely up-to-date data in the results rather than fixing the data at compile time.

When the prerender solution is enabled by the tenant administrator, static pages canalso be delivered through the prerender server. This lets indexers and crawlers handleportions of static pages that may still render dynamically, like content lists.

Content queries return content items that include rich text field values, so you don'tneed to fetch the values separately when content layouts are used for content lists.

Controller Site Page RenderingThe cec compile-template command enables site pages to render directly in thebrowser, without going through the Oracle Content and Experience site pagecontroller.

Without using the compiler to create static HTML pages, an Oracle Content andExperience site uses a controller model to render pages. This involves a number ofrequests to get information about the site, the page within the site, and templates usedto render the page before it can actually be displayed in the browser.

Chapter 12Compile a Site to Improve Runtime Performance for Site Pages

12-81

Note:

There are more requests involved, such as getting the controller.js file.This diagram simply provides an overview of the main phases.

Compiled Site Page RenderingThe cec compile-template command lets you compile all these steps into a staticHTML file and improves performance of runtime sites by reducing or eliminating theseserver requests. In addition, you can further reduce requests for resources that neednot change at runtime and have them compiled into the static pages.

The default compilation process does the work of the existing runtime controller,creating a physical HTML page for each page.json file in the site. These pages canthen be deployed to the site and will be published with the site and used when thecorresponding page URL is hit.

Template CompilationTo compile a site, you need to have access to the themes and components within thesite. A site template is the packaging model for a site. The template contains all therequired resources to migrate and run a site.

You can use a site template to export a site to the OCE Toolkit environment, where thesite within the template can be compiled. The following sections walk through acompilation of the site within BlogTemplate, which is seeded in OCE Toolkit.

SetupThe cec compile-template command is available through the OCE Toolkit and isinstalled when the toolkit is installed. Follow the standard instructions for installing theOCE Toolkit.

Once you have the OCE Toolkit installed, you can run cec commands to create atemplate.

1. Install an OCE Toolkit development directory:

mkdir cec-srccd ./cec-srccec install

# Start up the CEC Toolkit Development server for testingcec develop &

2. Create the template.The seeded BlogTemplate has been updated with custom compilers. Create atemplate from this source:

# create a new template (must be in the cec-src folder if not already there)


12-82

cd ./cec-srccec create-template BlogTemplate -f BlogTemplate

The seeded BlogTemplate extends the previous template with custom compilers:

• Content Layout Compilers

cec-src/src/components/Starter-Blog-Post-Summary/assets/compile.jscec-src/src/components/Starter-Blog-Author-Summary/assets/compile.jscec-src/src/components/Starter-Blog-Post-Content/assets/compile.jscec-src/src/components/Starter-Blog-Post-Header/assets/compile.jscec-src/src/components/Starter-Blog-Post-Sidebar/assets/compile.js

• Page Layout Compilers

cec-src/src/themes/BlogStarterTheme/layouts/post-detail-compile.jscec-src/src/themes/BlogStarterTheme/layouts/home-compile.jscec-src/src/themes/BlogStarterTheme/layouts/authors-compile.jscec-src/src/themes/BlogStarterTheme/layouts/common-compile.jscec-src/src/themes/BlogStarterTheme/layouts/about-compile.jscec-src/src/themes/BlogStarterTheme/layouts/index-compile.js

Compile Your TemplateWhen you compile your template, it creates a static HTML page for each of the pagesin the structure.json file for the site within the template.

The compilation step combines the page metadata (for example 100.json) with thepage layout (for example, about.html) so that you have an HTML page that willimmediately display without the need for a controller at runtime. The custom compilerslet you further reduce the runtime JavaScript execution by having previously dynamicitems, such as navigation and components, compiled into the page.

The cec compile-template command will take the following actions for each page inthe site:

• Read in the site and page metadata

• Read in the page layout and apply any page layout compiler

• For each slot on the page:

– Expand the slot with the grid defined in the page.json file

– For each component within the slot:

* Apply any component compiler

* Insert the generated component markup in the corresponding locationwithin the slot

• Expand any macros in the compiled markup and insert the SCS JavaScript objectthat is used by the Oracle Content and Experience renderer at runtime

• Save the compiled page markup under the src/templates/<template>/staticfolder


12-83

To compile your site, run:

> cec compile-template BlogTemplateCompile Template: compiling template BlogTemplateOracle Content and Experience Site Compiler

createPage: Processing pageId 100. Preview URL: http://localhost:8085/templates/BlogTemplate/index.html createPage: Processing pageId 105. Preview URL: http://localhost:8085/templates/BlogTemplate/post-detail.html createPage: Processing pageId 401. Preview URL: http://localhost:8085/templates/BlogTemplate/about.html createPage: Processing pageId 402. Preview URL: http://localhost:8085/templates/BlogTemplate/search.html createPage: Processing pageId 403. Preview URL: http://localhost:8085/templates/BlogTemplate/authors.html All page creation calls complete.

Creating detail pages: createPage: Processing detail pageId 105. Preview URL: http://localhost:8085/templates/BlogTemplate/post-detail/1481786063051-developing-content-layout-for-content-and-experience-cloudcreatePage: Processing detail pageId 105. Preview URL: http://localhost:8085/templates/BlogTemplate/post-detail/1481786063052-dynamic-dom-manipulation-in-content-layout createPage: Processing detail pageId 105. Preview URL: http://localhost:8085/templates/BlogTemplate/post-detail/1481786063045-getting-media-url-in-the-content-layout createPage: Processing detail pageId 105. Preview URL: http://localhost:8085/templates/BlogTemplate/post-detail/1481786063053-getting-reference-items-in-content-layout createPage: Processing detail pageId 105. Preview URL: http://localhost:8085/templates/BlogTemplate/post-detail/1481786063048-navigating-to-a-search-page-with-search-query createPage: Processing detail pageId 105. Preview URL: http://localhost:8085/templates/BlogTemplate/post-detail/1481786063050-alex-read createPage: Processing detail pageId 105. Preview URL: http://localhost:8085/templates/BlogTemplate/post-detail/1481786063047-jerrold-summers createPage: Processing detail pageId 105. Preview URL: http://localhost:8085/templates/BlogTemplate/post-detail/1481786063049-kelly-emerson createPage: Processing detail pageId 105. Preview URL: http://localhost:8085/templates/BlogTemplate/post-detail/1481786063043-samantha-howard createPage: Processing detail pageId 105. Preview URL: http://localhost:8085/templates/BlogTemplate/post-detail/1481786063046-raising-triggers-from-content-layout createPage: Processing detail pageId 105. Preview URL: http://localhost:8085/templates/BlogTemplate/post-detail/1481786063044-rendering-the-content-layout-using-mustache-template All detail page creation calls complete.

Compilation ErrorsDuring compile you will get three types of messages: Info, Warning, and Errors.


12-84

http://localhost:8085/templates/BlogTemplate/index.html

http://localhost:8085/templates/BlogTemplate/post-detail.html

http://localhost:8085/templates/BlogTemplate/about.html

http://localhost:8085/templates/BlogTemplate/search.html

http://localhost:8085/templates/BlogTemplate/authors.html

http://localhost:8085/templates/BlogTemplate/post-detail/1481786063051-developing-content-layout-for-content-and-experience-cloud


http://localhost:8085/templates/BlogTemplate/post-detail/1481786063052-dynamic-dom-manipulation-in-content-layout


http://localhost:8085/templates/BlogTemplate/post-detail/1481786063045-getting-media-url-in-the-content-layout


http://localhost:8085/templates/BlogTemplate/post-detail/1481786063053-getting-reference-items-in-content-layout


http://localhost:8085/templates/BlogTemplate/post-detail/1481786063048-navigating-to-a-search-page-with-search-query


http://localhost:8085/templates/BlogTemplate/post-detail/1481786063050-alex-read

http://localhost:8085/templates/BlogTemplate/post-detail/1481786063047-jerrold-summers

http://localhost:8085/templates/BlogTemplate/post-detail/1481786063049-kelly-emerson

http://localhost:8085/templates/BlogTemplate/post-detail/1481786063043-samantha-howard

http://localhost:8085/templates/BlogTemplate/post-detail/1481786063046-raising-triggers-from-content-layout


http://localhost:8085/templates/BlogTemplate/post-detail/1481786063044-rendering-the-content-layout-using-mustache-template


1. Info messages are items that you should be aware of, but these messages areprobably expected as part of compilation:

• Placeholder content items that will render at runtime.

• Missing page layout compilers. Page layouts might not have any dynamicelement and so aren't considered an issue if they are missing.

• Items marked as "render on access"; that is, the site developer wants thiscomponent to be dynamically rendered at runtime even though the page iscompiled.

2. Warning messages, which will likely affect the performance of the running site andshould be fixed where possible. Items in this category follow:

• Missing content layout or custom component compilers. Without these, thecomponents will render dynamically into the page as they did previously.

• Missing content layout maps. It's unlikely that you would want to use thesystem default content layout to render content items.

3. Error messages, which indicate a compilation failure. The pages will continue tocompile where possible, but the overall compilation will exit with an error.

• This is most likely caused by JavaScript errors in custom compilers, and anyerrors must be resolved.

Note:

To reduce repetitive messages, the same message will appear only once percompilation regardless of whether it occurs on multiple pages.

The preceding example has the following compilation exit status:

Compilation completed with 0 errors and 3 warnings. to display warnings, run with --verbose (-v) option.

If you rerun the compilation step with the "-v" option, you will see the following output:

> cec compile-template BlogTemplate --verboseCompile Template: compiling template BlogTemplate Oracle Content and Experience Site Compiler

createPage: Processing pageId 100. Preview URL: http://localhost:8085/templates/BlogTemplate/index.html createPage: Processing pageId 105. Preview URL: http://localhost:8085/templates/BlogTemplate/post-detail.htmlInfo: no content item specified for placeholder: a890a65c-c0fc-451b-966b-e606ca18a1f4 component will render at runtime. Info: no content item specified for placeholder: c90bbc10-c9d8-4a54-8dd4-7a8251e8efbb component will render at runtime. Info: no content item specified for placeholder: f12691e1-79ab-4d1f-a8b9-3af8c638dd26 component will render at runtime.


12-85



createPage: Processing pageId 401. Preview URL: http://localhost:8085/templates/BlogTemplate/about.html createPage: Processing pageId 402. Preview URL: http://localhost:8085/templates/BlogTemplate/search.htmlInfo: Component: "fdfd0392-e901-48f6-8044-36803c836aa1" of type "scs-contentlist" marked as "render on access", will not be compiled. Info: Component: "ba9f3711-4367-444e-ae38-71289fc10e73" of type "scs-contentlist" marked as "render on access", will not be compiled. createPage: Processing pageId 403. Preview URL: http://localhost:8085/templates/BlogTemplate/authors.html All page creation calls complete.

Creating detail pages: createPage: Processing detail pageId 105. Preview URL: http://localhost:8085/templates/BlogTemplate/post-detail/1481786063051-developing-content-layout-for-content-and-experience-cloud createPage: Processing detail pageId 105. Preview URL: http://localhost:8085/templates/BlogTemplate/post-detail/1481786063052-dynamic-dom-manipulation-in-content-layout createPage: Processing detail pageId 105. Preview URL: http://localhost:8085/templates/BlogTemplate/post-detail/1481786063045-getting-media-url-in-the-content-layout createPage: Processing detail pageId 105. Preview URL: http://localhost:8085/templates/BlogTemplate/post-detail/1481786063053-getting-reference-items-in-content-layout createPage: Processing detail pageId 105. Preview URL: http://localhost:8085/templates/BlogTemplate/post-detail/1481786063048-navigating-to-a-search-page-with-search-query createPage: Processing detail pageId 105. Preview URL: http://localhost:8085/templates/BlogTemplate/post-detail/1481786063050-alex-read Warning: failed to find content layout map entry for: Starter-Blog-Author:header. Will compile using the system default layout.Warning: failed to find content layout map entry for: Starter-Blog-Author:content. Will compile using the system default layout. Warning: failed to find content layout map entry for: Starter-Blog-Author:sidebar. Will compile using the system default layout. createPage: Processing detail pageId 105. Preview URL: http://localhost:8085/templates/BlogTemplate/post-detail/1481786063047-jerrold-summers createPage: Processing detail pageId 105. Preview URL: http://localhost:8085/templates/BlogTemplate/post-detail/1481786063049-kelly-emerson createPage: Processing detail pageId 105. Preview URL: http://localhost:8085/templates/BlogTemplate/post-detail/1481786063043-samantha-howard createPage: Processing detail pageId 105. Preview URL: http://localhost:8085/templates/BlogTemplate/post-detail/1481786063046-raising-triggers-from-content-layout createPage: Processing detail pageId 105. Preview URL: http://localhost:8085/templates/BlogTemplate/post-detail/1481786063044-rendering-the-content-layout-using-mustache-template All detail page creation calls complete.


12-86














http://localhost:8085/templates/BlogTemplate/post-detail/1481786063050-alex-read

http://localhost:8085/templates/BlogTemplate/post-detail/1481786063047-jerrold-summers

http://localhost:8085/templates/BlogTemplate/post-detail/1481786063049-kelly-emerson

http://localhost:8085/templates/BlogTemplate/post-detail/1481786063043-samantha-howard






Compilation completed with 0 errors and 3 warnings.

*** compiled template is ready to test *** to render non-compiled pages, remove compiled files from under: /private/tmp/cec-src/src/templates/BlogTemplate/static

Detail Page CompilationDetail page compilation collates all the content items it encounters during compilation.Then it recompiles the detail page for each content item it finds, using the slug value todefine the URL to the new detail page.

The preceding compilation output happens in two sections:

1. Page Compilation

2. Detail Page Compilation

In the preceding example, you'll see warnings about no content layout map entries forthe Starter-Blog-Author page. However, we don't want detail pages for Starter-Blog-Author. The detail page is only for Starter-Blog-Post content items. To remove theseerrors, we can exclude content items from detail page compilation if they don't have anexplicit detail page referenced in their settings, with the following option:

--noDefaultDetailPageLink, -o Do not generate compiled detail page for items/content lists that use the default detail page.

So, rerunning compilation, excluding detail page creation that uses the default detailpage, produces the following output:

> cec compile-template BlogTemplate --noDefaultDetailPageLink Compile Template: compiling template BlogTemplate Oracle Content and Experience Site Compiler

createPage: Processing pageId 100. Preview URL: http://localhost:8085/templates/BlogTemplate/index.html createPage: Processing pageId 105. Preview URL: http://localhost:8085/templates/BlogTemplate/post-detail.html createPage: Processing pageId 401. Preview URL: http://localhost:8085/templates/BlogTemplate/about.html createPage: Processing pageId 402. Preview URL: http://localhost:8085/templates/BlogTemplate/search.html createPage: Processing pageId 403. Preview URL: http://localhost:8085/templates/BlogTemplate/authors.html All page creation calls complete.

Creating detail pages: createPage: Processing detail pageId 105. Preview URL: http://localhost:8085/templates/BlogTemplate/post-detail/1481786063051-developing-content-layout-for-content-and-experience-cloudcreatePage: Processing detail pageId 105. Preview URL:


12-87






http://localhost:8085/templates/BlogTemplate/post-detail/1481786063052-dynamic-dom-manipulation-in-content-layoutcreatePage: Processing detail pageId 105. Preview URL: http://localhost:8085/templates/BlogTemplate/post-detail/1481786063045-getting-media-url-in-the-content-layoutcreatePage: Processing detail pageId 105. Preview URL: http://localhost:8085/templates/BlogTemplate/post-detail/1481786063053-getting-reference-items-in-content-layoutcreatePage: Processing detail pageId 105. Preview URL: http://localhost:8085/templates/BlogTemplate/post-detail/1481786063048-navigating-to-a-search-page-with-search-queryAll detail page creation calls complete.

Compilation completed with no errors.

*** compiled template is ready to test *** to render non-compiled pages, remove compiled files from under: /private/tmp/cec-src/src/templates/BlogTemplate/static

Compile Specific PagesYou need not compile all the pages in the template, and you can select which pages tocompile. This is useful if you are working on specific pages that you want to debug orupdate rather than having to continually recompile the entire site.

To compile specific pages, use the --pages (-p) option followed by the list of pagesyou're interested in compiling.

Note:

Note: If content items are on the pages in the list reference detail pages, thedetail pages will also be compiled even though they aren't explicitly included.

cec compile-template BlogTemplate --pages 401,402 Compile Template: compiling template BlogTemplate Oracle Content and Experience Site Compiler

createPage: Processing pageId 401. Preview URL: http://localhost:8085/templates/BlogTemplate/about.html createPage: Processing pageId 402. Preview URL: http://localhost:8085/templates/BlogTemplate/search.html All page creation calls complete.

Compilation completed with no errors. *** compiled template is ready to test *** to render non-compiled pages, remove compiled files from under: /private/tmp/cec- src/src/templates/BlogTemplate/static


12-88











Site CompilationThe preceding steps give you an overview of how to create and compile a localtemplate. In general, you will be compiling your actual Oracle Content and Experiencesites.

To compile an Oracle Content and Experience site, you need to export the site into atemplate and then compile the template. The template package will have the site aswell as any custom code required to compile the site in the themes and componentsthat are exported with the template.

Prerequisites for Site CompilationThe following steps assume that you've created a site called BlogSite in your OracleContent and Experience server. You can upload the preceding BlogTemplate andthen create this site from the template.

For example:

> cec upload-template BlogTemplate --sever UAT

> cec create-site BlogSite --template BlogTemplate --repository <yourRepository> --localizationPolicy <yourLocalizationPolicy> --defaultLanguage en-US --server UAT

Once you've selected or created your site, you can do the steps in the followingsections to compile your site.

Compile a SiteThe cec create-template-from-site command in the OCE Toolkit can create atemplate of your site, so you can compile the site.

cec create-template-from-site

Options:--site, -s <site> Site to create from [required]--includeunpublishedassets, -i flag to indicate to include unpublished content items and digital assets in your template--server, -r <server> The registered CEC server--help, -h Show help [boolean]

To compile a site:

1. Create a template from the site:

> cec create-template-from-site BlogTemplate --site BlogSite --includeunpublishedassets – server UAT


12-89

2. Download your template:

> cec download-template BlogTemplate --server UAT

3. Compile your template:

> cec compile-template BlogTemplate --noDefaultDetailPageLink --verbose --server UAT --channelToken e1bb88cdc1e025c8dd278f6b676877a3

Note:

You will need to get the channel token for youf site (--channelToken (-c) option) in the server for the site's publishing channel. This will then beused for all the queries within the site in your template.

4. Upload compiled site pages.Copy the compiled static files into the static folder for the site:

> cec upload-static-site src/templates/BlogTemplate/static --site BlogSite --server UAT

Revert to Noncompiled Behavior

To revert to noncompiled behavior, you need to remove the static files that youuploaded into the site:

> cec delete-static-site BlogSite --server UAT

And if the site is currently published, republish the site. This removes the "static" folderfrom the site; it doesn't remove the site.

Custom CompilersThe compilation process can be further enhanced with custom compilers. You can callcustom compilers to compile the page layout, section layout, custom component, orcontent layout into the page and avoid the need for the component to be addeddynamically at runtime.

If no custom compiler exists for a component or the component compiler returns nomarkup, then the component will be rendered at runtime as if it was never compiled.

Custom compilers are supported for the following components:

• Page layouts

• Section layouts

• Custom components

• Content layouts


12-90

The following samples show page layout and content layout compilers. Section layoutand custom components compilers follow the same model as the content layoutcompiler.

If no custom compiler exists, a component renders through the render.js file.

If a custom compiler does exist, it is called, and the resulting HTML is inserted into thepage. The custom compiler can also indicate that the component needs JavaScripthydration at runtime. If this is the case, the component's hydrate() function within therender.js file is called. If the component doesn't require hydration, then thecomponent's render.js file is never loaded.

Note:

Compilation is a runtime (published site) only feature. When a site is viewedin edit, navigate, or preview mode, the pages work as usual, and allcomponents will always be dynamically added to the page.

ConstraintsThe cec compile-template operation is a NodeJS application and runs outside of anybrowser. Because the page is not rendered in a browser, there is no DOM or windowobject, and client-side JavaScript libraries such as JQuery, VueJS, or KnockoutJS willnot work.

While it is possible to use a library such as JSDOM to create a DOM object and runthese client-side libraries, there is little advantage in doing so. For simple HTMLparsing, you can use a NodeJS HTML parser such as cheerio.

The HTML returned by the markup needs to be valid HTML. It will be passed through aparser, and only the parsed HTML will be added to the page. This is to confirm that thecompiled HTML doesn't have mismatched tags that could break slots.

Debug Custom CompilersWhen developing custom compilers, you will need to debug your code.

The cec compile-template command comes with a --debug (-d) option that willstart up the compiler with the --inspect-brk flag set so that a debugger can beattached to the process. You can then follow standard node debugging to check yourcode.

cec compile-template BlogTemplate --noDefaultDetailPageLink --debug

Debugger listening on ws://127.0.0.1:9229/8a8eba83-42d2-476b-adc1-b29ab4e92642For help see https://nodejs.org/en/docs/inspector

In addition, you can use the --pages (-p) option to limit the pages that will becompiled to a specific page.


12-91

Page Layout CompilersA page layout compiler is a NodeJS (CommonJS) JavaScript module that compiles thecorresponding page layout.

The page layout compiler for a specific page layout is defined by name associationwith a -compile.js extension:

• src

– themes

* <yourTheme>

* layouts

* <yourPageLayout>.html

* <yourPageLayout>-compile.js

If no -compile.js exists for a page layout, then no custom compilation is applied.

A page layout compiler needs to implement a compile() interface, which returns aPromise; for example, about-compile.js:

var mustache = require('mustache'); var PageCompiler = function () {}; PageCompiler.prototype.compile = function (args) { var self = this, layoutMarkup = args.layoutMarkup; self.SCSCompileAPI = args.SCSCompileAPI; return new Promise function (resolve, reject) { var compiledPage = layoutMarkup, id = self.SCSCompileAPI.navigationRoot; // page is compiled so there is no FOUC, can remove the opacityworkaround compiledPage = compiledPage.replace('opacity: 0;', 'opacity: 1;'); // remove the dynamic menu creation, we'll be compiling it here compiledPage = compiledPage.replace('<script src="_scs_theme_root_/assets/js/topnav.js"></script>', '');

// add link to Home page. . . var homePageURL = (self.SCSCompileAPI.getPageLinkData(id) || {}).href; if (homePageURL) { compiledPage = compiledPage.replace('class="navbar-brand" href="#"', 'class="navbar-brand" href="' + homePageURL + '"'); }

// build the menu and add it to the page var navMenu = self.createNavMenu();


12-92

compiledPage = compiledPage.replace('', navMenu);

// return the compiled page resolve(compiledPage); }); };

// Create the navigation menu that was previously dynamically generated on each page PageCompiler.prototype.createNavMenu = function () { . . .}

module.exports = new PageCompiler();

Component CompilersCustom Component Compilers all follow the same model as page compilers and canbe created for section layouts, custom components, and content layouts.

During compilation, the cec compile-template command will look for a compile.jsfile in the same location as the render.js file for the component:

• src

– components

* <yourComponent>

* assets

* render.js

* compile.js

If this file doesn't exist, the component is not compiled and will be rendered at runtime.

If the file does exist, it needs to implement a compile() interface, which returns aPromise. For example, the following Starter-Blog-Author-Summary is a customcontent layout compiler:

var fs = require('fs'),path = require('path'),mustache = require('mustache')

var ContentLayout = function (params) { this.contentClient = params.contentClient; this.contentItemData = params.contentItemData || {}; this.scsData = params.scsData;};

ContentLayout.prototype = { contentVersion: '>=1.0.0 <2.0.0',

compile: function () { var compiledContent = '', content = JSON.parse(JSON.stringify(this.contentItemData)),


12-93

contentClient = this.contentClient;

// Store the id content.fields.author_id = content.id;

if (this.scsData) { content.scsData = this.scsData; contentType = content.scsData.showPublishedContent === true ? 'published' : 'draft'; secureContent = content.scsData.secureContent; }

// calculate the hydrate data content.hydrateData = JSON.stringify({ contentId: content.id, authorName: content.fields['starter-blog-author_name'] });

try { // add in style - possible to add to <head> but inline for simplicity var templateStyle = fs.readFileSync(path.join(__dirname,'design.css'), 'utf8'); content.style = '<style>' + templateStyle + '</style>'; var templateHtml = fs.readFileSync(path.join(__dirname,'layout.html'), 'utf8'); compiledContent = mustache.render(templateHtml, content); } catch (e) { console.error(e.stack); }

return Promise.resolve({ content: compiledContent, hydrate: true // note that we want to hydrate this component using the render.js hydrate() function. This is required for when the user clicks on the author }); }};

module.exports = ContentLayout;

SCSCompileAPISimilar to the SCSRenderAPI, there is an SCSCompileAPI that is passed in to eachcompile function.

This contains the following properties and functions.

• Properties:

– navigationRoot: The ID of the node that is the root of the site.

– navigationCurr: The ID of the current page node.


12-94

– structureMap: All of the nodes of the site hierarchy and accessed by ID.

– siteInfo: All the site properties.

• Functions:

– getContentClient: Gets the contentClient instance for use in Content API calls.

Component HydrationHydration refers to the process of adding the JavaScript behavior back into thecompiled HTML in the page when the HTML renders in the browser.

For example, if you have two components on the page that you want to render asmaster/detail, then clicking an item in the master needs to update the detailcomponent. This is all handled by JavaScript that executes in the page. To make thiswork, you need to hydrate the HTML for the two components after they've renderedinto the page by adding an on click event handler to the elements in the mastercomponent and a listener on the detail component container to re-render when the onclick event occurs based on the payload passed in the event.

Component compilers insert HTML into the page. If your component needs additionalJavaScript to be executed at runtime to add in things like event handlers, then youhave a couple of options, inline JavaScript or the Hydrate function. Which solution youchoose depends on your requirements.

Inline JavaScript

You can insert a <script> tag directly into the returned compiled markup. The script willexecute as the page executes.

For example:

<script src="/_sitesclouddelivery/renderer/libs/scs-core/jssor-slider/js/jssor.slider.min.js" type="text/javascript"></script><div id="slider_container_c46b122d-978a-429d-aa25-9b5698428f6f" style="position: relative; top: 0px; left: 0px; height: 400px; width: 600px;background-color: rgb(68, 68, 68); visibility: visible;" data-jssor-slider="1">. . .</div><script> (function () { // get the required options var options = {"$FillMode":2,"$AutoPlay":false,"$AutoPlayInterval":3000,"$SlideDuration":500,"$ArrowKeyNavigation":true,"$HWA":false,"$BulletNavigatorOptions":{"$ChanceToShow":1,"$AutoCenter":1,"$SpacingX":5},"$ArrowNavigatorOptions":{"$ChanceToShow":1,"$AutoCenter":2,"$Steps":1},"$ThumbnailNavigatorOptions":{"$ChanceToShow":0,"$DisplayPieces":7,"$SpacingX":8,"$ParkingPosition":240}};


12-95

// select the JSSOR value options options.$BulletNavigatorOptions.$Class = $JssorBulletNavigator$; options.$ArrowNavigatorOptions.$Class = $JssorArrowNavigator$; options.$ThumbnailNavigatorOptions.$Class = $JssorThumbnailNavigator$;

// create the slider var slider = new $JssorSlider$("slider_container_c46b122d-978a-429d-aa25-9b5698428f6f", options); // resize, maintaining aspect ratio var container = slider.$Elmt.parentElement; if (container) { slider.$ScaleWidth(container.getBoundingClientRect().width); } })(); </script>

Hydrate FunctionInstead of inlining the JavaScript, you can include a hydrate function in your render.jsfile and note that the component requires hydration at runtime when you return thecompiled markup. This hydration avoids repetitious <script> tags and lets youleverage existing JavaScript code to manage events.

Even though the render.js file is loaded, the render() function is not called duringhydration. Only the hydrate() function is called.

Note:

If a compiled component does not say it needs hydration, then thecomponent's render.js file is never loaded.

For example, the custom content layout compiler would return with - { hydrate:true }.

return Promise.resolve({ content: compiledContent,

hydrate: true // note that we want to hydrate this component using the render.js hydrate() function. This is required for when the user clicks on the author});

In addition, if required, the custom compiler can add hydrate properties that it will lookfor at runtime. For example:

Compiler: // calculate the hydrate data content.hydrateData = JSON.stringify({


12-96

contentId: content.id, authorName: content.fields['starter-blog-author_name'] });. . .

Template: <div class="author-container" data-hydrate="{{hydrateData}}">

Finally, if a component notes that it needs hydration, then, at runtime, the component'srender.js file will be loaded and the hydrate() function called, passing in thecontainer <div> that contains the compiled markup.

For example, render.js - see hydrate() function:

function selectAuthor(parentObj, contentId, authorName) { var $parentObj = $(parentObj); $parentObj.find(".author-name").click($.proxy(function () { $(".author-name").removeClass('author-selected'); $(event.target).addClass('author-selected'); }, self)); if (window.location.href.indexOf("default=" + contentId) >= 0) { $(".author-name").each(function () { if (this.innerText === authorName) { $(this).addClass('author-selected'); } }); }}. . . hydrate: function (parentObj) { var $parentObj = $(parentObj), hydrateData = $parentObj.find('.author-container').attr('data-hydrate'); if (hydrateData) { var data = JSON.parse(hydrateData); selectAuthor(parentObj, data.contentId, data.authorName); } }, render: function (parentObj) { . . . try { // Mustache template = Mustache.render(templateHtml, content); if (template) { $(parentObj).append(template); } selectAuthor(parentObj, this.contentItemData.id, content.fields['starter-blog-author_name']); } catch (e) { console.error(e.stack);


12-97

} }

PublishingAfter compiled static pages have been generated and uploaded to the site's staticfolder, you need to publish or republish the site for the pages to become active.Similarly, to revert to noncompiled site delivery behavior, you need to publish orrepublish after removing the static files from the site.

During publishing the uploaded static pages are made available for delivery. Becausethese files are copied during the publishing process, the performance of the publishoperation may decrease proportionally to the number of files.

The publishing operation takes the current set of static files and makes them availablefor delivery. These files might or might not be in sync with any changes that havehappened in the dynamic site, and they might or might not mirror the dynamic site.Updating the static files collection at appropriate times is left to the site developer.

Static Site Delivery PrecedenceWhen a site has associated static files, those files are delivered for matching URLscoming into the server. If an incoming URL does not match a static file, then the site'scontroller.html file is returned for the request. This follows the existing dynamicmodel for site delivery.

Oracle Content and Experience sites can also define 301 and 302 redirects through anassociated JSON file. When redirects have been configured, the redirects take priorityover static files. If a URL matches both a redirect rule and a static file, the redirect willbe delivered from the server.

The URL evaluation for site delivery follows this flow:

1. Does the URL match a configured redirect?If so, issue a redirect response.

2. Does the URL correspond to a static file?If the mobile static user agents list is configured for the site and the request iscoming from a browser that matches the list, then deliver the mobile static file.

3. Otherwise, deliver the dynamic site controller.html file.

Note:

If mobile static files are associated with the site and the customer is using aCDN for delivery, then the CDN (usually Akamai) needs to be configured tocache mobile browser requests separately from standard desktop requests.

If the CDN is not configured with separate mobile/standard caching, thenmobile browsers may receive standard responses, and desktop browsersmay get responses intended for mobile browsers.


12-98

Caching HeadersHTTP Headers in the responses from web servers help determine how browsers willcache pages. Static pages are also delivered with caching headers to help facilitatebrowser caching.

For secure sites, the following headers will be sent with responses:

• Cache-Control: no-store

• Pragma: no-cache

For standard, nonsecure sites, the following headers will be sent:

• Cache-Control: max-age=300

• Edge-Control: !no-store,max-age=2592000,downstream-ttl=1800The Edge-Control header helps to facilitate CDN caching behavior

If you have customized the headers in one of these two areas, then the response willhave the custom headers instead of the standard ones listed here.

You can control these responses at the tenant level or at the site level.

Detail PagesDetail pages in Oracle Content and Experience sites allow a single page to showinformation for a number of content items.

For example, the same detail page can be used to handle a number of URL. Each ofthese URLs would display the same page structure but would show the content relatedto the content items whose slug values are item1.html, item2.html, and item3.html,respectively. For this situation the cec template compiler might create four files:

• /detail/item1.html



• /detail.html

The final file allows newly published material to be displayed in the web site withouthaving to recompile and republish the site. In this example, a content item with slugvalue item4.html is published after the site is online. The static /detail.html pageallows that new item to be displayed dynamically in the site. The URL /detail/item4.html would deliver the detail.html page but show content related to theitem4.html content item.

The cec compiler generates the detail.html page to display content items. For thisreason, relative URLs inside the compiled detail.html page will have extra parentsegments (../). So, if referenced directly, the detail.html page itself will not displayproperly. The detail.html page itself should not be referenced or added to pagenavigation for this reason.

Add Content Items to a ChannelYou can use the OCE Toolkit control-content command to add content items to achannel in an Oracle Content and Experience Server.


12-99

The control-content <action> command has an action, add, for adding contentitems to an Oracle Content and Experience channel:

cec control-content add -c Channel1 -r Repo1 -s UAT

This command add all items in the repository Repo1 to the channel Channel1 on theregistered server UAT.

You can specify the server with -s <server>or use the server specified in thecec.properties file.

The valid actions for the content-usage command follow:

• publish

• unpublish

• add

• remove

Options for the content-usage command follow:

• --channel, -c Channel [required]

• --repository, -r Repository [required when <action> is add]

• --server, -s The registered Oracle Content and Experience server

• --help, -h Show help [boolean]

Examples of the control-content command follow:

cec control-content publish -c Channel1

Publish all items in channel Channel1 on the server specified in the cec.properties file

cec control-content publish -c Channel1 -s UAT

Publish all items in channel Channel1 on the registered server UAT

cec control-content unpublish -c Channel1 -s UAT

Unpublish all items in channel Channel1 on the registered server UAT

cec control-content add -c Channel1 -r Repo1 -s UAT

Add all items in repository Repo1 to channel Channel1 on the registered server UAT.

cec control-content remove -c Channel1 -s UAT

Remove all items in channel Channel1 on the registered server UAT


12-100

Compile a Site for Mobile DevicesYou can use the OCE Toolkit to compile a mobile layout for a site web page. Themobile layout can be different from the desktop page layout for the same content. Orthe mobile and desktop layouts can be the same.

In the site editor, you can choose the same page layout for mobile devices as thedesktop layout, or you can specify a different page layout. With OCE Toolkit, you cancompile the static layout for mobile devices separately.

You can view the site page differently on a mobile device. A page rendered on amobile device might not have a banner like the page does in a desktop layout. Forexample, the following web page has a mobile page layout.


12-101

In OCE Toolkit, the help page for cec compile-template shows the targetDeviceoption for targeting a particular device when you compile a site template:

When you compile your site, you can specify whether you want to compile for desktopor for mobile. Desktop files are placed under static/_files. Mobile files are placedunder static/_mobilefiles.


12-102

After you compile a template for mobile devices, the OCE Toolkit command upload-static-site-files will support the mobile files.

Site Lifecycle and Compiled PagesWhen you create a template from a site, compiled pages are not included in thetemplate. This is to avoid the issue where the static pages are being delivered whenthe site developer expected the dynamic pages to be delivered.

If you subsequently create a site from the template, you will need to compile the sitepages and upload them to the new site.

Create a New Site or Asset Translation Job in the OracleContent and Experience Server

Use OCE Toolkit to create a translation job for a site or an asset in Oracle Content andExperience.

Before you can index a multilingual site, you need a translation job. To create atranslation job:

1. Click Translate on the top menu of the Sites page.

2. Enter a name for the job in the Create Translation Job dialog, and choose thedefault source language, the target languages, and the translation job contents.

Chapter 12Create a New Site or Asset Translation Job in the Oracle Content and Experience Server

12-103

You can choose to have your translation package include all site content andtargeted assets, only site content, or only assets targeted to the site's publishingchannel.

Exclude from the translation any content items that are configured with the Do nottranslate text setting. For example, product names typically are not translated.

3. Click Create to create the translation job.


12-104

4. Use an OCE Toolkit command to list the available jobs:

cec components> cec list-translation-jobsAsset translation jobs:Name Status Source Language Target Languages Pending Languages

Site translation jbs:Name Status Source Language Target Languages Pending Languages

demo1 READY en-US fr-FR,es-ES fr-FR,es-ES

searchdemo1 TRANSLATED en-US fr-FR,es-ES

5. Download your translation job:

cec components> cec download-translation-job demo1 - translation job downloaded to /Users/<user-name>/Dev/webclient/developers/sites-toolkit/cec-components/demo.zip - update the translation job status to INPROGRESS.cec components> cec translate dmo1.zip -l all -t demo1-xlate.zip - target languages: fr-FR,ex-ES - translation finished: /Users/<user-name>/Dev/webclient/developers/sites-toolkit/cec-components/demo1-xlate.zip

6. Open the translation bundle and build the folders of resources for languages thatyou're translating to:

Unzip demo1-xlate.zipARchive: emo1-xlate.zipreplace assets/job.json? [n]o, [A]ll, [N]one, [r]ename: A inflating assets/job.json inflating site/job.json inflating assets/es-ES/CORE47653001483240C1AAF180C435F189AB-search_siteSearch202.json inflating assets/es-ES/COREA570227E12194356BAA16A80A78A2670-entry1.json inflating assets/es-ES/CORED977BC199A3B494596F0D467CAADF7FA-entry2-json inflating assets/fr-FR/CORE47653001483240C1AAF18DC435F1B9A8-search_siteSearch202.json inflating assets/fr-FR/COREA570227E12194356BAA16A80A78A2670-entry1.json inflating assets/fr-FR/CORED977BC199A3B494596F0D467CA4DF7FA-entry2.json inflating assets/root/CORE476530014B3240C1AAF18DC435F1B948-search_siteSearch202.json inflating assets/root/COREA570227E12194356BAA16A80A7842870-entry1.json inflating assets/root/CORED977BC199A38494596F0D467CA4DF7FA-entry2.json inflating site/es-ES/10.json


12-105

inflating site/es-ES/100.json inflating site/es-ES/110.json inflating site/es-ES/120.json inflating site/es-ES/130.json inflating site/es-ES/140.json inflating site/es-ES/150.json inflating site/es-ES/200.json inflating site/es-ES/201.json inflating site/es-ES/202.json inflating site/es-ES/203.json inflating site/es-ES/siteinfo.json inflating site/es-ES/structure.json inflating site/fr-FR/10.json inflating site/fr-FR/100.json inflating site/fr-FR/110.json inflating site/fr-FR/120.json inflating site/fr-FR/130.json inflating site/fr-FR/140.json inflating site/fr-FR/150.json inflating site/fr-FR/200.json inflating site/fr-FR/201.json inflating site/fr-FR/202.json inflating site/fr-FR/203.json inflating site/fr-FR/siteinfo.json inflating site/fr-FR/structure.json inflating site/root/10.json inflating site/root/100.json inflating site/root/110.json inflating site/root/120.json inflating site/root/130.json inflating site/root/140.json inflating site/root/150.json inflating site/root/200.json inflating site/root/201.json inflating site/root/202.json inflating site/root/203.json inflating site/root/siteinfo.json inflating site/root/structure.json inflating inflating inflating inflating inflating inflating inflating inflating

7. Import the translation job:

cec-components> cec import-translation-job demo1-xlate.zip - Logged in to remote server: <server url> - file demo1-xlate.zip uploaded to home folder, version 1 - importing: percentage 5


12-106

- importing: percentage 60 - import demo1 finished

Translate a Site with a Language Service ProviderYou can manage translations of a site for multiple languages with the OCE Toolkitcommand-line interface and a Language Service Provider (LSP).

The localization policy for a site specifies a default language, such as English (UnitedStates) (en-US), and one or more alternate languages for the site, such as Germanand French. The text strings for a site can be translated into the specified alternatelanguages. If you change the language for the site before translation, the text stringswill still appear in the default language.

OCE Toolkit provides the following translation options in the command-line interface:

Translation cec list-translation-jobs Lists translation jobs. [alias: ltj] cec create-translation-job <name> Creates a translation job <name> for a site on CEC server. [alias: ctj] cec download-translation-job <name> Downloads translation job <name> from CEC server. [alias: dtj] cec submit-translation-job <name> Submits translation job <name> to translation connection <connection>. [alias: stj] cec ingest-translation-job <name> Gets translated job <name> from translation connection and ingest. [alias: itj] cec upload-translation-job <name> Uploads translation job <name> to CEC server. [alias: utj] cec create-translation-connector <name> Creates translation connector <name>. [alias: ctc] cec start-translation-connector <name> Starts translation connector <name>. [alias: stc] cec register-translation-connector <name> Registers a translation connector. [alias: rtc]

You can use the cec list-translation-jobs command to list the translation jobs thatare already on the server. For example:

cec ltj -sServer: <server-name>Asset translation jobs:Name Status Source Language Target Languages Pending LanguagestestHash INPROGRESS en-US fr-FR,de-DE fr-FR,de-DESite translation jobs:Name Status Source Language Target Languages Pending LanguagesdemoTest TRANSLATED en-US de-DE,fr-FR

Chapter 12Translate a Site with a Language Service Provider

12-107

Typing any cec command without parameters or with -h provides help for thecommand. See Use the cec Command-Line Utility.

The following sections provide information about translating a site with an LSP:

1. Create a Translation Job with OCE Toolkit

2. List Translation Jobs

3. Create a Translation Connector

4. Generate a Site Map for a Multilingual Site

5. Submit a Translation Job to a Language Service Provider

6. Upload a Translation Job to the Server

Create a Translation Job with OCE ToolkitYou can use an OCE Toolkit command to create a site translation job on your localsystem.

To create a new translation job for a site, use the cec create-translation-jobcommand. This command finds all the assets for the site and creates a zip file foreverything that needs to be translated from that site.

cec create-translation-job FridayDemo -s Take2 -l all - Logged in to remote server: <server-name> - establish user session - site: Take2, default language: en-US - query channel - site localization policy: MyLP - target languages: de-DE, fr-FR - create translation job submitted - creating: percentage 50 - translation job FridyDemo created

For translation options, see Create a New Site or Asset Translation Job in the OracleContent and Experience Server.

List Translation JobsYou can list translation jobs on the server to verify that your job was created and isready to work with.

cec list-translation-jobs -sServer: <server-name>Asset translation jobs:Name Status Source Language Target Languages Pending LanguagestestHash INPROGRESS en-US fr-FR,de-DE fr-FR,de-DESite translation jobs:Name Status Source Language Target Languages Pending LanguagesdemoTest TRANSLATED en-US de-DE,fr-FR


12-108

FridayDemo READY en-US de-DE,fr-FR de-DE,fr-FR

Notice that the FridayDemo job is in a READY state.

Create a Translation ConnectorA Language Service Provider (LSP) can help you translate a site. With a translationconnector to the LSP, you can submit and ingest translation jobs.

Before you submit a translation job, you need to create a translation connector. Totranslate a site without an LSP, you can create a mock translation connector to runagainst. Use the cec create-translation-connector command to create atranslation connector and the cec start-translation-connector command tostart it:

cec create-translation-connector connector1 - translation connector connector1 created at <sites-toolkit folder>/cec-components/src/main/connectors/connector1 - install connector. . .Start the connector: cec start-translation-connector connector1 [-p <port>]cec start-translation-connector connector1 -p 7777NodeJS running. . .:Site page: http://localhost:7777

Use the OCE Toolkit to test the translation connector by running it through theexpected APIs:

1. Register the connector with OCE Toolkit.

>cec register-translation-connector

2. Open up the toolkit and go to the "Translation Connections" page.

>http://localhost:8085/public/translationconnections.html

3. Run through the steps on the translation connector validation page. These stepsuse the translationBundle.zip file in the /data folder in your connectorenvironment to validate your connector.

You can use the Translation Connector SDK to develop a translation connector forOracle Content and Experience. This SDK is a sample NodeJS implementation of theTranslation connector API. The sample accepts an Oracle Content and Experiencetranslation job zip file, translates all the resource in the file, and returns a new zip filecontaining all the translations.

The SDK requires the user to have access to an LSP to do the actual stringtranslations. A mock LSP server is included in the SDK to mimic the responses froman LSP by simply prepending the targeted locales to the strings.

The Translation Connector SDK consist of three main modules.

• Connector: The translation connector that implements the required OracleContent and Experience Translation Connector API.


12-109

• Job Manager: A file system-based sample job manager that maintains the state ofthe connector jobs while they are translated by the Language Service Provider.

• Provider: The implementation of the specific set of APIs required by your LSP tosubmit documents for translation and retrieve the translated documents.

You can copy the mock translation Provider JS and implement all the methods insideit.

Generate a Site Map for a Multilingual SiteUse OCE Toolkit to generate a site map for a multilingual site and publish the map tothe site.

You can use the cec create-site map <site> command to create a site map for amultilingual site on an Oracle Content and Experience server. For example:

cec create-site-map Site1 -u http://www.example.com/site1

This command traverses the a site structure, produces a site map hierarchy thatmatches the site page hierarchy, and creates a site map at the specified site URL onthe Oracle Content and Experience server.

Command options follow:

--url, -u <url> Site URL [required] --changefreq, -c How frequently the page is likely to change --file, -f Name of the generated site map file --publish, -p Upload the site map to CEC server after creation --help, -h Show help [boolean]

Valid values for the <changefreq> option follow:

• always

• hourly

• daily

• weekly

• monthly

• yearly

• never

• auto

Examples of the cec create-site-map command follow:

cec create-site-map Site1 -u http://www.example.com/site1

cec create-site-map Site1 -u http://www.example.com/site1 -f sitemap.xml

cec create-site-map Site1 -u http://www.example.com/site1 -p


12-110

cec create-site-map Site1 -u http://www.example.com/site1 -c weekly -p

To publish a site map, a site update is created, the site map is updated, and then theupdate is committed.

Submit a Translation Job to a Language Service ProviderOCE Toolkit provides a zip file that you can send to a Language Service Provider tostart work on a translation job.

You can submit the translation job to the LSP through your translation connector. Thesubmission takes awhile because the connector needs to unzip the file and submit allof the individual files to the LSP. Then the LSP can create a project for your translationjob. Once the files have been imported into the project, you can start selecting files fortranslations. Then the LSP starts monitoring the status of the translations.

To check the status, list your translation jobs locally, using the cec list-translation-jobs command with no options. When the status of your job is READYTO INGEST, you can download a zip file from the LSP to ingest the translation job. Thetranslation connector has submitted your zip file to the LSP, the LSP has translatedthe list of files, and the connector has retrieved the files back from the LSP, in a zip filethat you can download and ingest.

cec list-translation-jobsLocal translation jobs:Name Status Source Language Target Languages FridayDemo READY TO INGEST en-US de-DE,fr-FRdemoTest READY TO INGEST en-US de-DE,fr-FR

Ingesting the zip file pulls the translation job back from the connector, into your OCEToolkit.

cec ingest-translation-job FridayDemo - use connection <lsp name> - query translation connection to get job status - get translation - translation saved to <sites-toolkit folder>/cec-components/dist/FridayDemo-translated.zip - validate translation file - translation job ingested to <sites-toolkit folder>/cec-components/src/main/translationJobs/FridayDemo

After you ingest the zip file, when you list translation jobs locally, the status of yourtranslation job is TRANSLATED.

cec list-translation-jobsLocal translation jobs:Name Status Source Language Target Languages


12-111

FridayDemo TRANSLATED en-US de-DE,fr-FRdemoTest READY TO INGEST en-US de-DE,fr-FR

You can upload the translated job to the Oracle Content and Experience server.Normally the job will go through an initial quick translation, which is sent back to youfor review. Translation of a site can take a few weeks to finish, with ingestion of atranslation job returned by the LSP, corrections to the translations, and resubmissionsof the translation job.

Upload a Translation Job to the ServerAfter you ingest a translation job, you can upload it to the Oracle Content andExperience server and then check the translation on your site.

Use the cec upload-translation-job command to upload your translation zipfile to the server.

cec upload-translation-job FridayDemo - created translation job zip file <sites-toolkit folder>cec-components/dist/FridayDemo.zip - Logged in to remote server: <server-name> - file FridayDemo.zip uploaded to home folder, version 1 - importing: percentage 5 - importing: percentage 60 - importing: percentage 60 - import FridayDemo finished

After you upload your translation job, the status of the job on the server is INPROGRESS:

cec list-translation-jobs -sServer: <server-name>Asset translation jobs:Name Status Source Language Target Languages Pending LanguagestestHash INPROGRESS en-US fr-FR,de-DE fr-FR,de-DESite translation jobs:Name Status Source Language Target Languages Pending LanguagesdemoTest TRANSLATED en-US de-DE,fr-FR FridayDemo INPROGRESS en-US de-DE,fr-FR

To verify the translation, you can check the text strings in the assets on the site beingtranslated.


12-112

13Develop Translation Connectors forLanguage Service Providers

Oracle Content and Experience provides a connector framework for developers todevelop their custom translation connectors. The connector framework is extensible,and a developer or partner can build a translation connector to work against anyLanguage Service Provider (LSP).

For translation by an LSP, Oracle Content and Experience converts a translation zipfile into the format expected by the vendor and then packages up the response fromthe vendor into a zip file that Oracle Content and Experience can consume.

A custom translation connector needs to implement the following artifacts:

• REST interfaces for defining configuration, providing authorization, and translatingcontent.

• Logic to create and manage a translation job, accept a translation job zip file, andreturn a translated version of the translation zip file

Oracle Content and Experience provides a sample translation connectorimplementation that runs against an included mock server to get you started.

Oracle Content and Experience provides the following tools for site and assettranslations:

• A translation connector framework, a translation SDK, and command-line interface(CLI) utilities in OCE Toolkit

• An administration web interface for creating a custom translation connector

• A translation job web interface that lets contributors submit assets or sites fortranslation by an LSP and import translations into Oracle Content and Experience

Note:

This chapter does not provide details on how to deploy or manage yourconnector. The model you choose for deployment will depend on thetechnology you use to implement the connector and the server you choose todeploy the connector.

The following topics describe how to develop custom translation connectors for OracleContent and Experience and to translate OCE sites and assets using LSPs:

• Overview of the Translation Connector Framework

• Request a Lingotek Trial Connector for Content Translation

• Enable a Lingotek LSP Translation Connector

• Build a New Translation Connector

13-1

• Configure and Register a Translation Connector

• Translation Connector Execution Flow

• Sample Translation Connector Implementation

• Understand the Sample Translation Connector Source Code

Overview of the Translation Connector FrameworkThe Oracle Content and Experience translation framework enables you to translatesites and assets using external Language Service Providers.

To help you build a new translation connector, Oracle Content and Experienceprovides the Translation Connector SDK.

The connector framework abstracts the functionality that is provided and implementedby end connectors. It does so by providing the REST API interface for configuring atranslation connector and for calling translation connector functionality to downloadtranslation jobs from sites and upload the resulting translations back into OracleContent and Experience.

Translation Connector SDKThe Translation Connector SDK for Oracle Content and Experience is a sampleNodeJS implementation of the Translation Connector REST APIs. The sample acceptsa translation job zip file, transates all the resources in the file, and then returns a newzip file containing all the translations.

The Translation Connector SDK is part of the OCE Toolkit, which is available fromGitHub. To help you build a new translation connector, this SDK contains a sampletranslation connector:

• JSDoc for the sample translation connector

• A NodeJS sample translation connector implementation of the REST interfaces

• A NodeJS mock Language Server Provider that the sample runs against

Note:

The Translation Connector SDK requires the user to have access to alanguage service provider (LSP) to do the actual string translations. A mockLSP server is included in the SDK to mimic the responses from the LSP bysimply prepending the targeted locales onto the strings.

This SDK consists of three main modules:

• SampleConnector: A sample translation connector that implements the requiredOracle Content and Experience Translation Connector API.

• SampleJobManager: A file-system based sample job manager that maintains thestate of the connector jobs while they are translated.

Chapter 13Overview of the Translation Connector Framework

13-2

• TranslationProviderInterface: A set of APIs used to call the Language ServiceProvider to submit documents for translation and retrieve the translateddocuments.

The Sample Translation Connector code is split up into three areas:

• /translation-connector:

– /connector: Implements the required Oracle Content and Experience CloudTranslation Connector APIs.

– /job-manager: This sample implementation of a file-based persistence storeunzips the translation job, translates it, and then zips up the translations.

– /provider: Implements the Language Service Provider APIs to upload,translate, and download documents.

In addition, you can use the mock LSP for testing:

• /mockserver: A mock LSP, which simply adds the requested translation locale toall the strings.

Translation connectors are deployable packages that use Restful services for theremote stores implementing the REST interfaces (SPIs/SDK) defined by OracleContent and Experience. They internally use cloud store native SDKs to connect toremote systems.

Translation Connector REST APIsYou can deploy and run translation connectors anywhere and implement them withany technology stack, as long as they can be called from Oracle Content andExperience through REST APIs.

The Translation Connector SDK includes the following API classes:

• ConnectorApi

• MockTranslationProvider

• PersistenceStoreInterface

• SampleBasicAuth

• SampleConnector

• SampleConnectorRouter

• SampleFileDownloader

• SampleFileImporter

• SampleFilePersistenceStore

• SampleFileTranslator

• SampleJobManager

• TranslationFilter

• TranslationProviderInterface

Your translation connector needs to support the translation connector REST APIs.

The following table describes the REST APIs for Oracle Content and Experiencetranslation connectors.

Chapter 13Overview of the Translation Connector Framework

13-3

API Description

GET http://host:port/connector/rest/api Returns the versions of theTranslation Connector REST APIthat the connector supports; forexample: ["v1"]


Returns the connector configurationinformation; for example, requiredparameters that the user needs topass to the connector.

POST http://host:port/connector/rest/api/v1/job

Creates a new job in the connectorand returns a unique translated job.

GET http://host:port/connector/rest/api/v1/job/{id}

Returns status information about thespecified job.

POST http://host:port/connector/rest/api/v1/job/{id}/translate

Sends an Oracle Content andExperience translation zip file for thejob to be translated.

GET http://host:port/connector/rest/api/v1/job/{id}/translation

Returns the translated job in theOracle Content and Experiencetranslated zip file format

DELETE http://host:port/connector/rest/api/v1/job/{id}

Deletes the job from the connector(and from the LSP if required)

Request a Lingotek Trial Connector for Content TranslationYou can open a trial account with the Lingotek language service provider from theOracle Content and Experience administration web interface.

To request a Lingotek trial account for content translation:

1. Sign in to the Oracle Content and Experience web interface as an administrator.


3. In the Integrations drop-down menu, choose Translation Connectors.

4. On the Translation Connectors page, click Lingotek to open the connectorconfiguration.

5. Click Custom Fields.On the Lingotek Custom Fields page, the fields are filled with all the input datayou need to configure your Lingotek trial account.

6. Under the Bearer Token field, click authorize a trial Lingotek account.

Chapter 13Request a Lingotek Trial Connector for Content Translation

13-4

The Lingotek Request Account page opens.

7. Replace the values on this page with your data:

• Replace Company with Oracle.

• Replace First Name, Last name, and Email with yours. The Email address willbe used as your Lingotek user name.

• Choose your country, such as United States, from the drop-down field.

• Enter a new password and confirm it.

8. Click Conditions of Use to view the policy, and then select the check box toagree with it.

9. Click the Request Account button.You will be redirected to the Lingotek sign-in page. Enter your Lingotek user name(email address) and password, and then click SIGN IN.

10. Select your organization (Oracle), and then click ALLOW to authorize theaccount.

11. The Lingotek Credentials page opens, with credentials for you to copy and pasteinto custom fields for your trial account.

Chapter 13Request a Lingotek Trial Connector for Content Translation

13-5

Use the credentials on this page to configure a Lingotek translation connector inOracle Content and Experience. The credentials include Bearer Token andWorkflow Id values for Oracle Content and Experience translation connectors aswell as your Oracle Community Id.

Copy the Bearer Token value from the Lingotek Credentials page and paste it inthe Bearer Token field on the Lingotek Custom Fields page. This populates therest of the custom fields on the page.

12. After you click Save, you can use your Lingotek trial account.

Enable a Lingotek LSP Translation ConnectorThe Lingotek language service provider (LSP) translation connector is pregistered.After you authorize Oracle on your Lingotek LSP account and enable the Lingotek LSPconnector in the Oracle Content and Experience web interface, you can use theconnector for translations.

To enable the Lingotek LSP translation connector:



3. In the Integrations menu, choose Translation Connectors.

Chapter 13Enable a Lingotek LSP Translation Connector

13-6

4. Click Enable next to the Lingotek connector.

After you enable the Lingotek LSP connector, it becomes available in the LanguageService Provider menu item of the Oracle Content and Experience CreateTranslation Job web interface.

Register Multiple Lingotek ConnectorsYou can register and enable multiple Lingotek language service provider (LSP)translation connectors in an Oracle Content and Experience instance.

Configuration of a Lingotek translation connector requires values for three customfields:

• Bearer Token: The sign-in for your Lingotek account. You can use the samebearer token for all of your Lingotek connectors or specify a different one for aconnector.

• Community: The community to use for your translation projects. The default isOracle.

• Workflow: The workflow profile to use for your Lingotek translation projects. Thedefault is Machine Translation.

You can change any of these values.

To create a translation job for an asset, you can select the asset in a repository andthen choose Translate from the drop-down menu to open the Create Translation Jobdialog.

Chapter 13Register Multiple Lingotek Connectors

13-7

The Workflows page shows workflows that you can use for your translation jobs.

You can specify a workflow for a connector on the Custom Fields page when youcreate the connector.

Chapter 13Register Multiple Lingotek Connectors

13-8

The Translation Jobs page, under Assets, shows the status of jobs you have runningon your Lingotek translation connectors.

If the workflow is different than Machine Translation, a translator edits or finishes thejob, and you will need to approve each of the translator's changes before the job is100% complete.

Build a New Translation ConnectorTo build a new translation connector as a Restful service, a Developer needs toimplement the Restful interfaces provided by the connector framework.

The Oracle Content and Experience Cloud (OCE) connector framework has thefollowing interfaces:

• APIResource Interface: This interface is the starting point of the translationconnector. You simply return the version that's supported.

• ServerResource Interface: When an Administrator or Developer registers atranslation connector in the OCE server, OCE calls this service to get the basicdetails about the connector server, such as the authorization type and customfields and properties for the translation connector:

– Authorization type:

* OAUTH: If the translation connector supports 3-legged OAuthauthentication

* BASIC_AUTH: If the translation connector supports Basic authentication

* NO_AUTH: If the translation connector doesn’t require any authentication

– Custom fields and properties: You can also use this interface to definecustom fields for the translation connector. Custom properties are specific to aconnector, so the connector framework can’t provide such a properties list byitself. Every translation connector has its own requirements to connect to a

Chapter 13Build a New Translation Connector

13-9

remote store; for example, one tanslation connector might need just ClientIDand ClientSecret, while another might require ClientID, ClientSecret,AppID, and so on. Each translation connector can provide a custom propertieslist to the Oracle Content and Experience server by ServerResource. If any ofthese properties need to be filled in by an administrator during configuration,the connector framework can surface them in the Administration web interfaceand pass them through as header parameters on each request to thetranslation connector.

This service will be called only once, at the time of registration.

• AuthorizationResource Interface: The basic authorization parameters can beentered when registering the connector so they will be passed to the connector onthe request.

• This interface has support for both OAuth and Basic authentication protocols.

– 3-legged OAuth authentication

* In the OAuth flow, the Oracle Content and Experience web interface,based on the custom property value provided by the translation connector,supports OAuth authentication. It triggers an OAuth flow by calling theconnector framework, which in turn calls the /authorization/authorization URL's service on the translation connector to get theauthorization URL.

* The Oracle Content and Experience web interface renders theauthorization URL in a browser, where the user authorizes the applicationand gives Oracle Content and Experience permission to access the tokenfor further communications. To complete the authorization and get theOAuth token, the Oracle Content and Experience server will call the /authorization/completedAuthorizations service on the translationconnector. To complete 3-legged OAuth, the Oracle Content andExperience server also provides the redirect callback servlet, which theremote store can call to complete the authorization process.

– Basic authentication: In case the translation connector supports Basicauthentication, the Oracle Content and Experience web interface will promptthe user to enter a user name and password, which it will pass to the OracleContent and Experience server (connector framework). The connectorframework will call the /authorization/basicAuthorization service to passthe credentials and will expect the translation connector to validate with theremote store if the credentials are correct.

• TranslationResource Interface: The connector framework uses this service tosubmit an Oracle Content and Experience translation job to the translationconnector. The translation connector then calls the Language Service Provider totranslate ,the zip file provided for the job and returns the translated zip.

Each of these interfaces is described in more detail, with examples of REST payloads,in the following sections:

• REST Interfaces for Configuration and Authorization

• REST Interfaces for Creating Translation Jobs and Returning Translated Content

• Authorization for Translation Connectors


13-10

REST Interfaces for Configuration and AuthorizationA translation connector needs to implement the following REST APIs for defining theconnector configuration and setting up authorization.

/rest/apiImplements intradoc.connectorcommon.server.APIResourceHere you return the latest version supported by the content connector.

GET http://host:port/connector/rest/api

[ "v1"]

/rest/api/v1/serverImplements intradoc.connectorcommon.server.ServerResource

This returns information about the translation connector configuration, like theauthentication type and custom fields it exposes.


{ "name": "", "nameLocalizations": [{ "locale": "en_US", "localizedString": "Sample Connector" }], "version": "(1,0,0)", "about": "This is a sample connector.Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved.", "aboutLocalizations": [{ "locale": "en_US", "localizedString": "This is a sample connector.Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved." }], "authenticationType": "NO_AUTH", "pickerType": "", "enableMultiUserCopyBack": false, "maxUploadSize": 1073741824, "fields": [{ "ID": "ProxyHost", "datatype": "STRING", "siteSettable": true, "userSettable": false, "connectorSettable": false, "authorizationURLParameter": false, "label": "HTTP Proxy Hostname", "labelLocalizations": [{ "locale": "en", "localizedString": "HTTP Proxy Hostname" }], "description": "The HTTP proxy hostname, leave blank to disable.",


13-11

"descriptionLocalizations": [{ "locale": "en", "localizedString": "The HTTP proxy hostname, leave blank to disable." }], "required": false }, { "ID": "ProxyPort", "datatype": "STRING", "siteSettable": true, "userSettable": false, "connectorSettable": false, "authorizationURLParameter": false, "label": "HTTP Proxy Port", "labelLocalizations": [{ "locale": "en", "localizedString": "HTTP Proxy Port" }], "description": "The HTTP proxy port number, leave blank to default to port 80.", "descriptionLocalizations": [{ "locale": "en", "localizedString": "The HTTP proxy port number, leave blank to default to port 80." }], "required": false }, { "ID": "ProxyScheme", "datatype": "STRING", "siteSettable": true, "userSettable": false, "connectorSettable": false, "authorizationURLParameter": false, "label": "HTTP Proxy Scheme", "labelLocalizations": [{ "locale": "en", "localizedString": "HTTP Proxy Scheme" }], "description": "The HTTP proxy scheme, leave blank to default to http.", "descriptionLocalizations": [{ "locale": "en", "localizedString": "The HTTP proxy scheme, leave blank to default to http." }], "required": false }, { "ID": "BearerToken", "datatype": "STRING", "siteSettable": true, "userSettable": false, "connectorSettable": false, "authorizationURLParameter": false, "label": "Bearer Token", "labelLocalizations": [{


13-12

"locale": "en", "localizedString": "Bearer Token" }], "description": null, "descriptionLocalizations": [], "required": true }, { "ID": "WorkflowId", "datatype": "STRING", "siteSettable": true, "userSettable": false, "connectorSettable": false, "authorizationURLParameter": false, "label": "Workflow Id", "labelLocalizations": [{ "locale": "en", "localizedString": "Bearer Token" }], "description": null, "descriptionLocalizations": [], "required": true }], "supportedConnectorTypes": [], "proprietorName": "", "serviceProviderName": "Sample APIs INC.", "nativeAppInfos": null}

/rest/api/v1/authorization/authorizationURLsImplements intradoc.connectorcommon.server.AuthorizationResource

This is required only if the translation connector supports OAuth. It returns theauthorization URL to which the browser will redirect to invoke the Oauth flow wherethe user provides credentials and authorizes the access. The redirect URL passed inthe payload is what the OAuth provider will redirect to with temporary code.

POST http://host:port/connector/rest/api/v1/authorization/authorizationURLs

HeadersContent-Type:application/jsonX-CEC-ClientID:client-idX-CEC-ClientSecret:client-secretX-CEC-ProxyHost:proxy-hostX-CEC-ProxyPort:80X-CEC-ProxyScheme:http Payload{"redirectURL":"http://host:port/documents/web/AR_COMPLETE_AUTHORIZATION"} Response{ "authorizationURL": "https://domain/oauth/authorize?response_type=code&client_id=id://host:port/documents/web/AR_COMPLETE_AUTHORIZATION",


13-13

"fieldValueMap": null}

/rest/api/v1/authorization/completedAuthorizationsImplements intradoc.connectorcommon.server.AuthorizationResource

This is required only if the translation connector supports OAuth.This is called tocomplete the second part of the OAuth flow, where the code obtained from the OAuthprovider in the previous step is passed along with the client ID and secret to obtain theaccess token and refresh token along with expiry times. This information is thenreturned to Oracle Content and Experience, which stores it securely against thesigned-in user.

POST http://host:port/connector/rest/api/v1/authorization/completedAuthorizations

HeadersContent-Type:application/jsonX-CEC-ClientID:client-idX-CEC-ClientSecret:client-secretX-CEC-code:codeX-CEC-ProxyHost:proxy-hostX-CEC-ProxyPort:80X-CEC-ProxyScheme:httpContent-Type:application/json Payload{"redirectURL":"http://host:port/documents/web/AR_COMPLETE_AUTHORIZATION"} Response{ "authorized": true, "authorizedUserDisplayName": null, "authorizedUserEmailAddress": null, "authorizedUserPictureURL": null, "fieldValueMap": { "RefreshToken": "refresh-token", "AccessToken": "access-token" }}

/rest/api/v1/authorization/basicAuthorizationImplements intradoc.connectorcommon.server.AuthorizationResourceThis is required only if the translation connector supports BASIC authorization. Here the sign in credentials are passed in the headers where the password field is base64 encoded. It is always recommended that a content connector be deployed on an SSL endpoint.


HeadersContent-Type:application/jsonX-CEC-UserName:user


13-14

X-CEC-UserPwd:passwordX-CEC-ProxyHost:proxy-hostX-CEC-ProxyPort:80X-CEC-ProxyScheme:http ResponseTrue

REST Interfaces for Creating Translation Jobs and ReturningTranslated Content

A translation connector needs to implement he following REST APIs for creatingtranslation jobs, providing status about the connector translation jobs, and returningthe translation results for each job.

/rest/api/v1/jobImplements intradoc.connectorcommon.server.TranslationJobResourceGiven an OCE Translation Job ID, create and return a connector project ID for the translation job.POST http://host:port/connector/rest/api/v1/job

Request HeadersX-CEC-ClientID:client-idX-CEC-ProxyHost:proxy-hostX-CEC-ProxyPort:80X-CEC-ProxyScheme:httpX-CEC-TranslationJob:translation-job-name

Request Body{Zipfilecontent}

Response Headerscontent-type application/zipcontent-length {zip file size} Response Body { "properties": { "status": "IMPORTING", "id": "{{connectorJobId}}" } }

/rest/api/v1/job/{id}/translationImplements intradoc.connectorcommon.server.TranslationJobResourceGiven a connector job id, return the translated zip file. GET http://host:port/connector/rest/api/v1/job/{id}/translation

Request HeadersX-CEC-ClientID:client-idX-CEC-ProxyHost:proxy-hostX-CEC-ProxyPort:80X-CEC-ProxyScheme:http


13-15

X-CEC-TranslationConnectorJobId:connector-job-id

Request Body

Response Headerscontent-type application/zipcontent-size {zip file size} Response Body {streamed zip file}

/rest/api/v1/job/{id}Implements intradoc.connectorcommon.server.TranslationJobResourceGiven a connector job id, delete the connector job from the connector. DELETE http://host:port/connector/rest/api/v1/job/{id}

Request HeadersX-CEC-ClientID:client-idX-CEC-ProxyHost:proxy-hostX-CEC-ProxyPort:80X-CEC-ProxyScheme:httpX-CEC-TranslationConnectorJobId:connector-job-id

Request Body

Response Headerscontent-type application/json Response Body {Message noting successful deletion}

Authorization for Translation ConnectorsA translation connector can support one of the following authorization models.

• No Auth

• OAuth

• Basic

No AuthNo Auth is used when the translation connector does not require any authorization. Inthis case, the connector accepts any requests to translate the job through theLanguage Service Provider.



13-16

serverInfo.authenticationType = AuthenticationType.NO_AUTH

OAuthOAuth is used when a translation connector supports OAuth. In this case, OCEensures that the OAuth flow is invoked to fetch the access token. For subsequentaccess, the already fetched token is used until it expires.

serverResource Implementation

serverInfo.authenticationType = AuthenticationType.OAUTH

The content connector also needs to define the required custom fields used in theOAuth flow.


{ FieldInfo field = new FieldInfo(); field.ID = UnsplashAdapter.FIELD_ID_REFRESH_TOKEN; field.label = ResourceBundleUtil.getDefaultLocalizedString("cds.unsplash.adapter.field.refreshtoken.label"); field.labelLocalizations = ResourceBundleUtil.getLocalizedData("cds.unsplash.adapter.field.refreshtoken.label"); field.datatype = FieldDatatype.STRING; field.userSettable = false; field.siteSettable = false; field.connectorSettable = true; field.authorizationURLParameter = false; serverInfo.fields.add(field);} { FieldInfo field = new FieldInfo(); field.ID = UnsplashAdapter.FIELD_ID_ACCESS_TOKEN; field.label = ResourceBundleUtil.getDefaultLocalizedString("cds.unsplash.adapter.field.accesstoken.label"); field.labelLocalizations = ResourceBundleUtil.getLocalizedData("cds.unsplash.adapter.field.accesstoken.label"); field.datatype = FieldDatatype.STRING; field.userSettable = false; field.siteSettable = false; field.connectorSettable = true;


13-17

field.authorizationURLParameter = false; serverInfo.fields.add(field);} { FieldInfo field = new FieldInfo(); field.ID = UnsplashAdapter.FIELD_ID_AUTHORIZATION_URL_PARAMETER_CODE; field.label = ResourceBundleUtil.getDefaultLocalizedString("cds.unsplash.adapter.field.authurl.code.label"); field.labelLocalizations = ResourceBundleUtil.getLocalizedData("cds.unsplash.adapter.field.authurl.code.label"); field.datatype = FieldDatatype.STRING; field.userSettable = false; field.siteSettable = false; field.connectorSettable = false; field.authorizationURLParameter = true; serverInfo.fields.add(field);} { FieldInfo field = new FieldInfo(); field.ID = UnsplashAdapter.FIELD_ID_AUTHORIZATION_URL_PARAMETER_ERROR; field.label = ResourceBundleUtil.getDefaultLocalizedString("cds.unsplash.adapter.field.authurl.error.label"); field.labelLocalizations = ResourceBundleUtil.getLocalizedData("cds.unsplash.adapter.field.authurl.error.label"); field.datatype = FieldDatatype.STRING; field.userSettable = false; field.siteSettable = false; field.connectorSettable = false; field.authorizationURLParameter = true; serverInfo.fields.add(field);

Also implement the following interfaces documented in the preceding text:

1. /rest/api/v1/authorization/authorizationURLs

2. /rest/api/v1/authorization/completedAuthorizations


13-18

BasicBasic is used when translation connector requires sign-in credentials.


serverInfo.authenticationType = AuthenticationType.BASIC

You also need to define all the sign-in fields in the server implementation.

// custom field for User Name{ FieldInfo field = new FieldInfo(); field.ID = "UserName"; field.label = ResourceBundleUtil.getDefaultLocalizedString("cds.unsplash.adapter.field.username.label"); field.labelLocalizations = ResourceBundleUtil.getLocalizedData("cds.unsplash.adapter.field.username.label"); field.description = ResourceBundleUtil.getDefaultLocalizedString("cds.unsplash.adapter.field.username.desc"); field.descriptionLocalizations = ResourceBundleUtil.getLocalizedData("cds.unsplash.adapter.field.username.desc"); field.datatype = FieldDatatype.STRING; field.userSettable = true; field.siteSettable = false; field.connectorSettable = false; field.authorizationURLParameter = false; field.required = true; serverInfo.fields.add(field);} // custom field for password{ FieldInfo field = new FieldInfo(); field.ID = "UserPwd"; field.label = ResourceBundleUtil.getDefaultLocalizedString("cds.unsplash.adapter.field.password.label"); field.labelLocalizations = ResourceBundleUtil.getLocalizedData("cds.unsplash.adapter.field.password.label"); field.description = ResourceBundleUtil.getDefaultLocalizedString("cds.unsplash.adapter.field.password.desc"); field.descriptionLocalizations = ResourceBundleUtil.getLocalizedData("cds.unsplash.adapter.field.password.desc");


13-19

field.datatype = FieldDatatype.PASSWORD; field.userSettable = true; field.siteSettable = false; field.connectorSettable = false; field.authorizationURLParameter = false; field.required = true; serverInfo.fields.add(field);}

Besides this, the translation connector needs to implement the following interface, asdescribed in the preceding text.

/rest/api/v1/authorization/basicAuthorizationSubsequently the user credentials (password base64 encoded) will be passed via headers for other calls, like create connector translation job and translate connector job.

Configure and Register a Translation ConnectorOnce you have built your translation connector, you need to register it through theOracle Content and Experience administration interface.

The minimum properties you are required to add to a translation connector follow:

• Translation connector name

• Translation connector service URL

• User name and password, if the preceding URL access requires it

• Whether or not to accept a self-signed certificate

Once a translation connector gets registered successfully and the translationconnector service URL is reachable, the Oracle Content and Experience server willcall a server service on the translation connector to get the custom properties andshow those in the Administration web interface. An administrator or developer canadd values for those properties (for example, clientid and clientsecret for OAuthflows or the user name and password for a Basic authorization central account).

Clicking Save saves all these properties with the connector framework.

You need to select the registered connector in the repository before you can use it inthe rest of the UI. Once you select the connector in the repository, then any asset inthat repository can use this connector to translate.

After you enable it, the translation connector becomes available in the LanguageService Provider menu item of the Oracle Content and Experience CreateTranslation Job web interface.

Translation Connector Execution FlowFrom the Oracle Content and Experience web interface Assets page of the Sitespage, you can click translate and choose a translation connector as an option fromthe Create Translation Job web interface.

Chapter 13Configure and Register a Translation Connector

13-20

During creation of the translation job, the connector framework makes REST API callsto the remote translation connector to create a corresponding job in the connector. Thezip file for the translation job is then submitted to the connector. Once the connectorsuccessfully receives the translation zip file, the job creation process is complete.

The user can now see the status of the job within the connector when viewing the listof translation jobs, or on the job detail page. Once the status moves to 100%, the usercan ask Oracle Content and Experience to ingest the translated zip. Oracle Contentand Experience will call the connector to retrieve the translated zip and ingest it.

Whenever a translation job is deleted that is using a translation connector, thetranslation connector is also told to delete the associated job in the connector.

Since a lot of the calls to the translation connector occur as a background process, theweb interface will indicate only the percent complete or failure of the connector job.Refer to the diagnostic logs for any failures.

Sample Translation Connector ImplementationYou can use the OCE Toolkit to create the Sample Translation Connector, whichprovides a working connector that runs against a mock server.

You can use this sample implementation of a translation connector to help build yourown custom translation connectors. The sample translation connector works with amock Language Service Provider to simply add "##{locale}##" to each string torepresent the "translation" of the string that an actual Language Service Providerwould do.

The sample translation connector is built using the Connector Framework JS SDKprovided by Oracle Content and Experience as part of the OCE Toolkit.

To install the OCE Toolkit, follow the directions listed here: https://docs.oracle.com/en/cloud/paas/content-cloud/developer/set-oracle-content-and-experience-toolkit-your-local-machine.html

The following sections describe how to develop a sample translation connector:

1. Create the Sample Translation Connector with OCE Toolkit

2. Register the Sample Translation Connector

3. Test the Sample Translation Connector

Create the Sample Translation Connector with OCE ToolkitThe create-translation-connector and start-translation-connector commandswill create a named connector and install the required file to run the connector.

The connector contains a NodeJS server.js that you can use to run the SampleTranslation Connector.

Register the Sample Translation ConnectorNow that you've created the Sample Translation Connector, you can register it.

Chapter 13Sample Translation Connector Implementation

13-21

https://docs.oracle.com/en/cloud/paas/content-cloud/developer/set-oracle-content-and-experience-toolkit-your-local-machine.html



The registration of the connector can point to any Oracle Content and Experienceserver, such as the sample server:

> cec register-translation-connector connector1-auto -c connector1 -s http://localhost:8084/connector/rest/api -u admin -p <password> -f "BearerToken:Bearertoken1,WorkflowId:machine-workflow-id"

To register the translation connector through the Oracle Content and ExperienceAdministration web interface:

1. Sign in to your Oracle Content and Experience Cloud (OCE) instance as anadministrator or developer.

2. Go to Administration > Integration > Translation Connectors and click Create.

3. Enter the details to register your sample translation content connector.

a. Name: Sample Connector – Machine Translation

b. Description: Connector to translate OCE assets and sites

c. Connector Service URL: http://host:port/sample-connector/rest/api (a URLtested previously)

d. Check Accept Self-Signed Certificate (if required).

4. Click Verify Settings and then Save.

5. Click the Custom Fields section:

a. BearerToken: Bearer token1

b. WorkflowId: machine-workflow-id

6. Check Enable for End Users.

The default timeout values for the translation connector are set in the following twoproperties:

ConnectorConnectionTimeout=20000ConnectorReadTimeout=30000

If you want to change the values of these properties, you can add the properties toyour config.cfg file and then modify either or both values.

Test the Sample Translation ConnectorAfter you create and test a translation connector in OCE Toolkit, you can register,enabling, and test it in the Administration web interface.

To test the translation connector:

1. Sign in to Oracle Content and Experience as an Administrator or Developer.

2. In the navigation menu for the Administration web interface, click Assets on thetop left, and then click an asset to select it.

3. Click Translate in the context menu.

4. In the create dialog, choose < Sample Connector – Machine Translation > inthe drop-down menu.

Chapter 13Sample Translation Connector Implementation

13-22

5. Complete the create dialog.

6. Navigate to the Translation Jobs page.When you view the translation job, it will now show you the % complete for the job.

7. Refresh the page until it shows 100% complete.

8. Import the translations from the connector.Upon successful import, your asset will be translated into your selected languageor languages.

The OCE Toolkit also provides a framework to test your Sample TranslationConnector. The Sample Translation Connector itself comes with a sample OracleContent and Experience translation job file under data/translationBundle.zip,which you can use for testing.

To run your Sample Translation Connector, bring up the OCE Toolkit develop pages,select the connector, and then click through each of the steps:

> cec develop &> open http://localhost:8085/public/translationconnections.html

Select the Sample Translation Connector you registered, and it will lead you to a pagethat lists the following steps to test the connector:

1. Get Server Config returns information about your connector that will be used toregister the connector with Oracle Content and Experience.

2. Create a job creates a unique ID for the job. The sample connector creates anout folder with the same name as the job ID in the connector.

3. Send zipfile to job submits data/translationBundle.zip to the job fortranslation. The sample connector saves this file in the out/{jobid} folder,extracts the files, and then submits them for translation.

4. Get the details of the job asks for the status of the job.

5. Get the translated zip returns the created OCE Translation Job TranslatedZip File, with the translation, once the job has moved to TRANSLATED.

6. Delete the job removes the out/{jobid} folder.

Understand the Sample Translation Connector Source CodeThe source code of the sample translation connector contains REST APIs and a jobmanager to handle creation and persistence of the connector jobs.

The sample translation connector contains a set of REST APIs implemented using theOracle Content and Experience connector interfaces. This is implemented as per theJAX-RS specification.

The job manager uses persistenceApi to store the following resources:

• Metadata about the job in the connector and the project created in the LanguageService Provider

• Contents of the translation zip file from Oracle Content and Experience

• Metadata about each file and the corresponding document in the LanguageService Provider

Chapter 13Understand the Sample Translation Connector Source Code

13-23

• Combination of the translations with the original files

• Creation of the translated zip file for the connector

The persistenceApi included in the sample simply uses the files system to managethese resources. A full translation connector implementation will need to make surethat the persistence layer will continue to work during failover and upgrade as well asprovide secure access to the resources stored.

The job manager also maintains information in the connector job metadata file aboutthe status of a translation job in the Language Service Provider by querying theinformation back either via polling or via a callback.

Code Structure:

connector:

• SampleConnectorRouter.js

– Authenticates the request

– Extracts parameters from the request URL

– Maps the request URL to the corresponding SampleConnector function:

� GET: /api/connector/v1/server => getServer() – metadata about the connector� POST: /api/connector/v1/job => createJob()� GET: /api/connector/v1/job/:id => getJob()� POST: /api/connector/v1/job/:id/translate => translateJob() – accepts a zipfile� GET: /api/connector/v1/job/:id/translation => getTranslation – get translated zip� DELETE: /api/connector/v1/job/:id => deleteJob()

• SampleConnector.js

– Validates the request parameters

– Calls the appropriate connector code

– Formats the response

• SampleBasicAuth.js

connector/job-manager:

• sampleJobManager.js

– Expand the zip file and then, for each file:

* Filter the file to include only translatable fields

* Submit the translatable fields to the LSP

* Wait for the translations to come back (either by polling or by callbacks)

* Recombine the translatable fields with the original files

* Create a zip file of all the translations

– Also restarts any running jobs on startup to support failover

• sampleFileImporter.js

– Imports the filtered document into the LSP specifying the source language


13-24

• sampleFileTranslator.js

– Asks the LSP to translate the documents into the target languages

• sampleFileDownloader.js

– Downloads translations for a document

connector/apis:

• persistenceApi.js

– Basic implementation using the filesystem to:

* Unpack the zip file and maintaining the source

* Accept translated files and creates the expected zip structure

* Zip up and return the translated files

• filterApi.js

– Extracts translatable strings from the source files based on file type

– Recombines the translated strings with the source file

• connectorApi.js

– Constructs the requests to the LSP

• httpApi.js

– Makes the actual GET/POST requests to the LSP

MockServer:

• mockLSPServer.js

• mockBearerAuth.js

– A mock LSP server

– It expects the following headers:

* BearerToken – can be any Bearer #### value

* WorkflowId – supports only machine-workflow-id

Translation Job Original Zip File FormatThe connector is responsible for extracting the files to be translated from thetranslation zip file, filtering them, and sending them to the LSP. To do this, theconnnector needs to understand the format of the zip file.

There are two types of translation jobs in Oracle Content and Experience, so there aretwo file structures possible in the zip file:

• Asset Translation

– Zip file format

* "job.json" - Contains details on the source & target languages.

* "root"

* <asset files to be translated>

• Site Translation


13-25

– Zip file format

* "site"

* "job.json" - Contains details on the source and target languages.

* "root"

* <site files to be translated>

* "assets"

* "job.json" - Contains details on the source and target languages.

* "root"

* <asset files in the site to be translated>

Translation Job Translated Zip File FormatOn successful translation, the connector must recombine the translations with theoriginal files and create a zip file in the following format, which is based on the originalformat.

• Asset Translation

– Zip file format:

* "job.json"

* "de-DE"

* <asset files>

* "fr-FR"

* <asset files>

* "it-IT"

* <asset files>

* "root" (Original files can optionally be included)

* <asset files>

• Site Translation

– Zip file format:

* "site"

* "job.json"

* "de-DE"

* <site files>

* "fr-FR"

* <site files>

* "it-IT"

* <site files>

* "root" (Original files can optionally be included.)

* <site files>


13-26

* "assets"

* "job.json"

* "de-DE"

* <asset files>

* "fr-FR"

* <asset files>

* "it-IT"

* <asset files>

* "root" (Original files can optionally be included)

* <asset files>


13-27

14Use Site Redirects or URL Mapping

When you restructure or move a web site, you can redirect user requests from oldURLs to their current ones. Specifying 30x redirects for URLs can maintain bookmarksor published links across site redesigns.

Pages that have high reputation rankings in search engines could move to differentURLs when you move to Content and Experience hosted sites from otherinfrastructure technologies. Redirects help reorganize the URL structure of a site andpreserve the search engine rankings.

• Plan for Redirects

• Add Site Redirects

• Specify Redirect Rules in a JSON File

• Upload a Redirect Rules File to a Site

• Map a Site URL

Plan for RedirectsYou can specify redirects that send HTTP 30x responses for designated URLs. If arequest does not match one of the nominated redirects, then regular processing of theURL happens, and the page is returned in the normal way.

You can create a JSON file specifying redirects and upload that file to the server. Theserver will use the JSON file as it process incoming request URLs.

Two kinds of redirect rules let you redirect incoming URLs to new locations:

• Simple String-to-String Matching

• Simplified Wildcard Matching

Add Site RedirectsIf the site URL changes, a redirect forwards one URL (source) to another URL (target).This helps to preserve user bookmarks and search engine rankings.

Two types of redirects can be used:

• A permanent redirect, which uses a 301 HTTP service response code

• A temporary redirect, which uses a 302 HTTP service response code

To upload a redirect.json file:

1. Open a site for editing.

2. Click in the sidebar and then click Redirects.

14-1

3. Click Select file to upload and navigate to the file you want to use, select it, thenclick OK.

4. When you publish the update, the changes are published and put into use.

Specify Redirect Rules in a JSON FileYou can specify redirect rules for URLs in a JSON file.

Use the following format in a JSON file to specify redirect rules for URLs.

{ "redirectRules": [ { "type": "string", "comment": "this rule is applied first", "expression": "/index.htm", "location": "/home.html" }, { "type": "wildcard", "expression": "/items/*?page=*", "location": "/<$page$>?item=<$wildcard(1)$>", "code": 302 } ]}

The outer containing structure in the JSON file is an array. The array contains ruleinstances.

The "string" rules will be evaluated first, followed by the "wildcard" rules, in order.Once one of the rules matches, the evaluation of subsequent rules is abandoned, andthe corresponding redirect is generated.

Each rule has the following properties:

• The "comment" property is an optional string that has no impact upon theevaluation of the rules. It includes notes or commentary.

• The "expression" property is a required string that matches against the incomingcandidate URL. In a wildcard rule, the asterisk (*) token matches zero or morecharacters.

• The "location" property is a required string that indicates the location ordestination of the redirect. The redirect can be a full or relative URL.

• The "code" property is an optional integer that provides the HTTP response codeto use when issuing the redirect. The value must be one of the following integers:

– 301: Indicates that the resource moved permanently. This is the default valueif the "code" property is omitted.

– 302: Indicates that the resource moved temporarily.

• The "type” property is an optional string that indicates the type of redirect rule. Thevalue must be one of the following strings:

Chapter 14Specify Redirect Rules in a JSON File

14-2

– "string" specifies a faster rule whose expression matches the entire inputURL exactly.

– 1. "wildcard" specifies a wildcard rule that can match a number of URLs.This is the default value if the property is omitted.

Location Tokens

You can use location tokens to help manufacture a redirect location. Each of thefollowing location tokens can help specify a redirect:

• <$urlPath$>: The path portion of the matching URL.

• <$urlQueryString$>: The entire URL query string from the matching URL.

• <$urlQueryStringExcept(name1,name2)$>: The entire URL query string from thematching URL minus the named parameters.

• <$wildcard(N)$>: The one-based index of the matching wildcard in the matchingURL. (This is analogous to \1..\9 in regular expressions.)

• <$name$>: The value of the named query string parameter. For example, if youhave the query string msmith: ?page=42 on the input, then you can use <$page$>in the location to put '42' into the location.

Restrictions

The following restrictions apply to the redirects.json file as a whole and to the rulesit contains.:

• The maximum overall file size accepted by Oracle Content and Experience is 250KB.

• The maximum number of rules in the redirects.json file is 1,000.

• The maximum "expression" length for a rule is 1,000 characters.

• The maximum "location" length for a rule is 2,000 characters.

• The maximum number of '*' tokens in a wildcard rule expression is 10.

String Matching Example

Rule:

{ "type": "string", "expression": "/old/page.jsp?id=material&type=glass", "location": "/new/<$id$>.htm" }

The following URL would match the rule:

/old/page.jsp?id=material&type=glass

• The resulting location would be: /new/material.htm

• The entire URL matches, including the query string.


14-3

• Although <$id$> is used in the location, it is not necessary for this examplebecause only one possible query string could match. The location could have beenwritten as /new/material.htm.

The following URLs would not match the rule:

• /old/page.jsp

(The rule’s expression gives a query string that must match.)

• /old/page.jsp?id=material&type=glass&index=2

(The extra &index=2 in the candidate URL does not exactly match the ruleexpression.)

• /old/page.jsp?type=glass&id=material

(The ordering of query string parameters must match in a “string” rule.)

Wildcard Matching Example

Rule:

{ "type": "wildcard", "expression": "/old/*/pages/*?id=*&item=sheet-*", "location": "/new/<$id$>/<$wildcard(4)$>.html" }

The following URLs would match the rule:

• /old/phones/android/pages/info.asp?id=XT1045&item=sheet-specs

– The resulting location would be: /new/XT1045/specs.html

– The path portion of the URL matches, so the query string is also examined formatching conditions.

– The parameters in this example happen to match the ordering of theparameters in the rule expression, but this is not required.

• /old/phones/android/pages/info.asp?item=sheet-specs&id=XT1045


– The path portion of the URL matches the rule expression before the questionmark (?), so the parameters are also checked for a match.

– Although the parameters are listed in a different order in the rule expression,the parameters are matched individually.

• /old/phones/android/pages/info.asp?id=XT1045&item=sheet-specs&unrelated=thing


– The path portion of the URL matches, so the query string is also examined formatching conditions.

– The candidate URL has an extra &unrelated=thing parameter, but since thenamed query parameters in the rule expression match, the rule is deemed tomatch.


14-4

– The unrelated parameter would be available in the location as a token, as<$unrelated$>, and would have the value thing, even though it did notcontribute to the match of the rule.

The following URLs would not match:

• /old/pages/info.jsp

(The path portion of the URL does not match the path portion of the ruleexpression.)

• /old/phones/android/pages/info.asp

(The path portion of the URL matches the path portion of the rule expression, butthe query parameters in the rule expression do not match.)

• /old/phones/android/pages/info.asp?id=cellular

(The path portion of the URL matches the path portion of the rule expression, butnot all of the query parameters in the rule expression match.)

Upload a Redirect Rules File to a SiteYou can upload a redirect rules to a site in Oracle Content and Experience.

To upload a redirect.json file to a site:

1. Open the site for editing.

2. Click in the sidebar and then click .

3. Click Select file to upload and navigate to the file you want to use, select it, thenclick OK.

4. When you publish the update, the changes are published and put into use.

Map a Site URLOnce a site is created and published using Oracle Content and Experience, you canconfigure the Domain Name System (DNS) so that this site is accessible with aregistered domain name, such as www.mysite.com

A Domain Name System (DNS) specifies where someone can find your web pages bymapping your domain name to your site’s location, or canonical name (CNAME).

To map your domain name, you’ll need the following:

• The URL of your Oracle Content and Experience instance. It’s typically of thefollowing form:service-tenant.documents.datacenter.oraclecloud.com

• The domain name as registered by your domain name registrar.For example, www.example.com. It could also be a sub-domain, such aswww.example.com/subdomain.

• An account with a content delivery network (CDN) provider. Oracle Content andExperience provides integration with Akamai. Contact Oracle Support to haveAkamai configured for your instance.

If you want to use your own CDN, rather than the Oracle Content and Experience-provided Akamai, perform the steps below.

Chapter 14Upload a Redirect Rules File to a Site

14-5

Different Domain Name System providers have different web interfaces and differentsteps for updating a CNAME record. The steps below provide the information you’llneed and the general steps to follow.

To map the site URL to a domain name:

1. Request a secure sockets layer (SSL) certificate from your content deliverynetwork provider for the domain. For example, https://www.mysite.com.

2. Configure the content delivery network so that:

a. The content delivery network accepts all incoming requests to the domain andforwards them using secure protocol (https).

b. The origin points to the domain from Oracle Content and Experience Cloud:

service-tenant.documents.datacenter.oraclecloud.com

3. Change the DNS server zone file to map the domain name to the edge serverprovided by the content delivery network provider:

domain CNAME CDN Server

4. Wait for the update to propagate. Depending on your DNS service, this can takeanywhere from 2 to 48 hours.

After the change is propagated, you can access the site using your domain name.For example:

https://www.mysite.com/site_name

By default, the endpoint for the Oracle Cloud REST API for Content Management isavailable if you use the standard URL provided for the site. Folder and file listcomponents, for example, use the REST API to perform folder and file operations. Ifyou use a custom URL, verify that you have access to the endpoint with your domainname. For example:

https://www.mysite.com/documents

Chapter 14Map a Site URL

14-6

15Improve Site Performance

You can improve the performance of content delivery and rendering in the browser byleveraging the browser cache. Above the fold (ATF) rendering can also improvewebsite rendering.

• Leverage Caching to Improve Performance

• Above the Fold (ATF) Rendering

Leverage Caching to Improve PerformanceDelivery of content items, digital assets, and sites should take full advantage of avisitor’s browser cache to improve performance of content delivery and rendering inthe browser.

Sites, themes, content items, and digital assets are cached for an amount of time inthe visitor’s browser cache. After a site, theme, content item, or digital asset isupdated, a cache-buster key in the URL is changed so that the browser has to fetch adifferent URL and get the new item.

The cache key helps to manage usage of the browser cache by referencing onlycurrent resources. Although the cache key is included in the URL, it is a logicalelement, not a physical location (folder) as is often the case. A change in the cachekey does not point to a different physical location to find the resource; it simply notifiesthe server to fetch the current version of the resource.

Resources can be static, like CSS, JS, and image files, or dynamic, like page data,site data, and content item data. There are five categories of resources for building awebsite:

• Product resources – Resources that are part of the product that gets updatedwhenever a new version of the product is released or patched.

• Site Resources – Resources that are part of the site, like structure.json, pagedata, and images. These are updated when the site is published. The controller isdescribed in the following text.

• Theme resources – Resources that are part of the themes, like layouts, CSS, andimages. These are updated when the theme is published.

• Component resources – Resources that are part of custom components. Theseinclude HTML, JS, and CSS, and image files that make up the component. Theseare updated when a component is published. If one component changes and isrepublished, then the cache key changes for all components because it’s a singlekey for all components.

• CaaS resources – Resources that serve content items and digital items. These areupdated when content items are published or republished or the collection target ischanged.

The following topics describe caching for the Oracle Content and Experience runtimeand Site Builder:

15-1

• Runtime Caching

• Site Builder Caching

Runtime CachingFor runtime, the Oracle Content and Experience Cache-Control header is set to 15days. A cache key is added to the URL for all resources.

As long as the URL is the same, the browser will serve the resource from its localcache if available. When the resource is updated, the cache key is updated in theURL, which forces the browser to make a new request to the server and update thelocal cache.

The controller, which contains the cache keys, is also cached for 1 minute. Because ofthis, any updated cache keys will not be seen for up to 1 minute.

At runtime the server returns controller.html with the latest cache keys for product,site, theme, components, and CaaS resources. A script with keys is added tocontroller.html; for example:

<script type="text/javascript"> var SCSCacheKeys = { product: '123', site: '456', theme: '789', component: '012', caas: '345'

};

</script>

These keys are used by controller.js to construct URLs like the ones in thefollowing table.

Type of Resources Examples

Product Resources/sitePrefix/productCacheKey/_sitesclouddelivery/...

/mySite/_cache_947d/_sitesclouddelivery/

Theme Resources/sitePrefix/themeCacheKey/_themesdelivery/themeName/...

Component Resources/sitePrefix/compCacheKey/_compdelivery/compName/...

Chapter 15Leverage Caching to Improve Performance

15-2

Type of Resources Examples

Site Resources/sitePrefix/siteCacheKey/content/.../sitePrefix/siteCacheKey/structure.json/sitePrefix/siteCacheKey/pages/100.json

CaaS ResourcesRegularCaaSUrl?cacheKey=caasCacheKey

By inserting the cache key into the URLs like this, Oracle Content and Experience canforce the browser to load updated resources by effectively changing the URL so thebrowser thinks it’s actually a new resource.

Note:

For secure sites, only the product, theme, and component resources arecached, not the site or CaaS content.

Site Builder CachingIn Site Builder, static resources are cached for 15 days.

When you use Site Builder, caching happens for product, theme, and componentresources. (It does not happen for site and CaaS resources.) Theme and componentcache keys are regenerated when Site Builder is launched or refreshed.

If you make a change to a theme or component and want that change to appear in SiteBuilder, you need to refresh Site Builder (F5).

Above the Fold (ATF) RenderingATF rendering gives the appearance of a website loading faster than it actually does.The goal is to render first all the parts of a page that are visible and then, before theuser scrolls down, render the rest of the page that is not initially visible.

A slot can have an "above the fold" designation, which displays an icon on the tab.

For a slot to be rendered in this new way, it must be marked with scs-atf, as follows:

<div class="scs-slot scs-atf" id="headline"></div>

A component needs to notify the renderer when it is done rendering. Out-of-the-boxcomponents do this by default. A custom component can make additional calls andneeds to do the following:

Chapter 15Above the Fold (ATF) Rendering

15-3

1. Notify the renderer that it wants the renderer to wait until it is completed rendering.

2. Notify the renderer when it has completed.

For #1, against the custom component's appinfo.json file, add in the followingproperty:

"initialData": { . . . "customRenderComplete": true, . . .

For #2, in the component's render.js file, make sure that you let the renderer knowwhen you're done by calling:

SitesSDK.setProperty('renderComplete', true);

If not all components in an ATF slot report back that they are done in a timely manner,then the renderer will wait for 2 seconds before continuing with the rest of the page. Ifyou know this will not be long enough, you can extend the time by declaring thefollowing global variable in a page template:

var SCSAtfPassTimeout = 3000;

Note:

The time is in milliseconds so this example set the timeout to 3 seconds.

An API provides diagnostic data for the ATF process. You can call the followingmethod in the debug console, or you can access it from a page if needed:

SCSRenderAPI.getRenderMetrics();

For example:

{currentTime: 16243.400000000001, renderStartTime: 264.36, atfPassEndTime: 306.535, mainPassStartTime: 316.475, mainPassEndTime: 331.38500000000005, …}

1. atfComponentCount:13

2. atfPassEndTime:306.535

3. completionCount:23

4. completionRecords:Array(23)

1. 0:{atf: true, componentId: "a7afdd33-3fbb-4329-bc1b-6be60056a995", time: 280.065}

2. 1:{atf: true, componentId: "edfcfcb4-b0d3-422f-aa59-5c925bbbebee",


15-4

time: 283.54}

3. 2:{atf: true, componentId: "c1c3aec8-e52f-406c-8c29-ab69c05877ed", time: 283.56000000000006}

4. 3:{atf: true, componentId: "b3a31dc6-62a1-44d9-9c80-bdb2c5bedaaa", time: 284.13000000000005}

5. 4:{atf: true, componentId: "c05aa1a2-c11c-4ef5-9051-4799c5bee24a", time: 284.15500000000003}

6. 5:{atf: true, componentId: "bafd4047-06ec-4739-9b23-9db74f573f30", time: 294.665}

7. 6:{atf: true, componentId: "e7d49528-0357-4b45-801e-b3a2716a086c", time: 297.995}

8. 7:{atf: true, componentId: "a5f33674-4022-4138-8cc5-fef00c02a557", time: 299.78000000000003}

9. 8:{atf: true, componentId: "ccfedc98-1dbd-440e-b867-5e683cea2ec5", time: 301.19500000000005}

10. 9:{atf: true, componentId: "d691bc44-fed9-474a-9806-2191f46a5e2e", time: 302.46}

11. 10:{atf: true, componentId: "cf613054-05d8-40dd-83a0-718760d7bc73", time: 303.79}

12. 11:{atf: true, componentId: "b4a6ef98-ffc8-48c7-987c-63346ee97bcc", time: 305.115}

13. 12:{atf: true, componentId: "de1fa2ce-66ba-419b-b517-2cb4a7601c3b", time: 306.535}

14. 13:{atf: false, componentId: "ba3f8ed4-31d4-4347-b6f0-f1019783a57c", time: 318.665}

15. 14:{atf: false, componentId: "ae8af486-76b3-47cd-9989-db4212eefebb", time: 320.45500000000004}

16. 15:{atf: false, componentId: "a48b5abb-49b2-4456-90bd-a3de998150c8", time: 320.48}

17. 16:{atf: false, componentId: "a9650e6d-7e7e-42a2-b758-58f2aeab18a2", time: 322.61500000000007}

18. 17:{atf: false, componentId: "aca9836a-f955-4aa7-8db2-fd3cf1189dea", time: 324.23500000000007}

19. 18:{atf: false, componentId: "e3d7941c-fbc7-4da9-963b-e3810b6467d4", time: 325.85}

20. 19:{atf: false, componentId: "eecde809-da54-4066-9326-73f9d9c35fe4", time: 327.315}


15-5

21. 20:{atf: false, componentId: "e8f4fb16-4e15-4570-b7de-304e99e449a7", time: 328.74}

22. 21:{atf: false, componentId: "a7baa06e-7f30-42c7-94f4-e171ab2edcd6", time: 330.09000000000003}

23. 22:{atf: false, componentId: "fd603b96-2beb-4e87-a54f-12d0e264cd0a", time: 331.38500000000005}

24. length:23

25. __proto__:Array(0)

5. componentCount:23

6. currentTime:16243.400000000001

7. mainPassEndTime:331.38500000000005

8. mainPassStartTime:316.475

9. renderStartTime:264.36

10. __proto__:Object


15-6

16Tutorial: Develop Components withKnockout

This tutorial takes you through working with the set of JavaScript objects, whichleverage the standard Knockout ViewModel and Template functionality, to create acomponent which is stored in the Oracle Content and Experience Component Catalog.

• Introduction and Prerequisites for Component Development with Knockout

• Step 1: Create a Component

• Step 2: Review the Structure of Your Local Component Rendering

• Step 3: Review the Structure of Local Component Settings

• Step 4: Display the New Property in the Component

• Step 5: Register Triggers

• Step 6: Raise Triggers

• Step 7: Register Actions

• Step 8: Execute Actions

• Step 9: Create a Distinct Title for Each Instance of the Component

• Step 10: Use Nested Components with In-Line Editing

• Step 11: Support Different Layouts

• Step 12: Define Custom Styles

• Step 13: Render a Component in an Inline Frame

• Step 14: Use Custom Styles When the Component Is Rendered in an Inline Frame

• Step 15: Integration with the Page Undo and Redo Behavior

• Step 16: Asset Management

• Tutorial Review

Introduction and Prerequisites for Component Developmentwith Knockout

This tutorial presents steps and verification procedures to create a sample componentusing JavaScript objects, which leverage the standard Knockout JS ViewModel andTemplate functionality.

You should be able to take the code referenced in these steps (provided in files thatare seeded when you create a component) and update only the .html template andJavaScript viewModel with your own code.

16-1

Note:

While Oracle Content and Experience does not dictate the JavaScripttechnology you use to create components, typically the factory JavaScriptfunction is the same for each implementation of a component in whicheverJavaScript framework is chosen.

Prerequisites

This tutorial only focuses on the implementation of a component. For a more generalinformation about components, see Develop Components.

To complete the steps in this tutorial, you must meet the following requirements:

• You must have access to an Oracle Content and Experience instance withpermissions to create sites and components.

• The Oracle Content and Experience instance server has been synced to your localcomputer using the Oracle Content and Experience desktop or using a customcomponent. See Develop Custom Components with Developer Cloud Service.

In addition, you should be familiar with these JavaScript concepts and frameworks:

• JavaScript browser debugging

• JavaScript Closure

• JavaScript Asynchronous Module Definition (AMD) development

• RequireJS and KnockoutJS frameworks

Continue to Step 1: Create a Component.

Step 1: Create a ComponentThis step explains how to create your custom component in Oracle Content andExperience.

When you create a custom component, it must be registered to be usable by OracleContent and Experience. To inform Oracle Content and Experience about yourcomponent, you use the Components page in Site Builder to register the component.

There are two types of components to register.

• Local component:

– This is a component whose files are stored on the Oracle Content andExperience instance server.

– The main advantage is that you don’t have to worry about cross-domain orcross-protocol issues because the files are located with your site.

– The disadvantage is that you can’t execute any middle-tier logic in the OracleContent and Experience server, so you must use REST APIs to remoteservers that support CORS.

– This type of component may be embedded into the page directly, or you canchoose to use an inline frame to render the component on the page.

• Remote component:

Chapter 16Step 1: Create a Component

16-2

– A component where the files are stored on a remote server and you onlyregister the URLs to the Render and Settings panel for the component.

– The advantage is if you have server-side logic that must execute whencreating the content for your component.

– The disadvantage is that you must ensure that any cross-domain and securityissues are resolved for accessing those URLs.

– Remote components always use an inline frame to render on the page.

To create and register a local component:

1. On the Oracle Content and Experience home page, click Developer.

The Developer page is displayed.

2. Click Components.

3. From the menu, choose Create Local Component.

4. Enter a name for the component; for example, A_Local_Component.

5. Enter an optional description.

6. Click OK.

After you have done this you’ll see a component named A_Local_Component inyour list of components.

Check the Results for Step 1

Now that you’ve successfully created a component, you should see the component inthe Component palette for any site you create. Use these steps to validate yourcomponent creation:

1. Create a site named localComponentTest.

2. Create an update for the site and give it a name and, optionally, a description.

3. Place the site into Edit mode and select a page on the site.

4. Click in the side palette and select Custom to display the list of customcomponents.

5. Select A_Local_Component from the Custom component list and drag and drop itonto the page.

You should now see a default rendering for the local component you created.

6. Select in the banner for the component you just dropped onto the page.

7. Select Settings.

8. Change the alignment and set the style for the component.

9. Close the Settings panel.

The following steps explain how the custom component is built and how to modify it foryour own purposes. Continue to Step 2: Review the Structure of Your LocalComponent.

Chapter 16Step 1: Create a Component

16-3

Step 2: Review the Structure of Your Local ComponentRendering

In this step we review the structure of the default files created for a local component.

For a simple Hello World example, four JavaScript objects and the number of lines ofcode may seem like too much, but this is to provide you with the basis for buildingmore complex components, as well as dealing with interaction with the Oracle CloudSites Service page lifecycle.

To review the structure of your local component:

1. Using the Oracle Content and Experience desktop sync client, locate yourcomponent and sync it with the file system.

If you don’t have the desktop client, you can select the component in theComponents tab of the Oracle Content and Experience interface and drill down tosee the files.

2. If you list the files under the component, you will see these files:

assets render.js settings.htmlappinfo.json_folder_icon.jpg

3. Open the render.js file under the /assets directory.

The main points of the render.js file are:

• It is structured as a JavaScript AMD module so that it can be “required” intothe page.

• It also includes references to KnockoutJS and JQuery that are already loadedas part of the Oracle Content and Experience page.

Consider the structure of the render.js file.

In the contents of the render.js file there are two JavaScript objects that implementthe required Oracle Content and Experience component APIs:sampleComponentFactory and SampleComponentImpl. These objects are an exampleof an implementation for creating any KnockoutJS based components. Theimplementation of these objects will change based on the technology you use.

• sampleComponentFactory

– This object is returned by the render.js AMD module.

– This is a very simple Factory object and implements the singlecreateComponent() interface.

– More complex implementations may use the args value passed to returndifferent implementations of the component based on the viewMode parameter.This enables you to have a significantly lighter-weight implementation of thecomponent for runtime versus Site Builder.

• SampleComponentImpl

Chapter 16Step 2: Review the Structure of Your Local Component Rendering

16-4

– The main function within this object is the render function, which is used torender the component onto the page.

To render the Knockout component into the page, the render functiondynamically adds the template to the page, then applies the viewModelbindings to the template.

– The rest of the implementation deals with initialization of the viewModelparameter and template, and with handling the messaging between the pageand the component.

The last two objects in the render.js file, sampleComponentTemplate andSampleComponentViewModel, provide a custom implementation for the component. Theimplementation of these will differ based on your requirements.

• sampleComponentTemplate

– This object provides the KnockoutJS template creation. It waits until thecomponent has all the data initialized before attempting to display anything.

• SampleComponentViewModel

– The viewModel retrieves the information stored by Oracle Content andExperience on behalf of the component, then selects how to appropriately layout the component based on that data

– General Knockout observables used by the template to handle access to themetadata stored on the component’s behalf:

self.imageWidth = ko.observable('200px');self.alignImage = ko.observable();self.layout = ko.observable();self.showTopLayout = ko.observable();self.showStoryLayout = ko.observable();

– Triggers and actions integration:

Trigger: A function to raise an Oracle Content and Experience trigger from thecomponent that can be bound to actions of other components on the page.

self.imageClicked = function (data, event) { self.raiseTrigger("imageClicked"); // matches appinfo.json };

Action: A function to handle the callback for when the component is told toexecute an action with a given payload.

self.executeActionsListener = function (args) { // get action and payload var payload = args.payload, action = args.action;

// handle 'setImageWidth' actions if (action && action.actionName === 'setImageWidth') { $.each(payload, function(index, data) { if (data.name === 'imageWidth') { self.imageWidth(data.value); }


16-5

}); } };

Callback to execute any registered actions on demand.

SitesSDK.subscribe(SitesSDK.MESSAGE_TYPES.EXECUTE_ACTION, $.proxy(self.executeActionsListener, self));

– Subscriptions to component life cycle:

* Component initialization: Make sure the component doesn’t render until alldata has been fetched. This is handled through Knockout observables.

self.componentLayoutInitialized = ko.observable(false);self.customSettingsDataInitialized = ko.observable(false);

Get the initial values for any required properties. This is handled bycallbacks to retrieve the data.

SitesSDK.getProperty('componentLayout', self.updateComponentLayout);SitesSDK.getProperty('customSettingsData', self.updateCustomSettingsData);

* Metadata updates: Callback whenever component metadata stored on thecomponent’s behalf is changed; for example, when the user invokes theSettings panel and updates the data.

SitesSDK.subscribe(SitesSDK.MESSAGE_TYPES.SETTINGS_UPDATED, $.proxy(self.updateSettings, self));

Note:

Because the Oracle Content and Experience server always sets the mime-type for .html files, you cannot upload a .html file and use the "text!"require plug-in to load it. Therefore, for templates, you either need to use adifferent extension to load it using "text!" or in-line the template in theJavaScript directly as shown in the seeded data.


You should now have an overview of how the structure of a custom componentrenderer is created. To validate that it works:

1. Update the sampleComponentTemplate object in the render.js file to change thefollowing line. Change this code:

''+


16-6

Use this code instead:

''+ '<div data-bind="text:\'image width is: \' + imageWidth()"></div>' +

2. Sync or upload the component to the Oracle Content and Experience instanceserver.

3. Edit a page within the site and drop in the A_Local_Component custom componentonto the page.

At this point you should see image width is: 260px in the component.

4. Bring up the Settings panel and click the Custom Settings button.

5. Change the image Width field to 300px.

6. At this point two things will happen in the component:

a. The default image will expand from 260px to 300px in size.

b. The text you added will update to image width is 300px.

Continue to Step 3: Review the Structure of Local Component Settings.

Step 3: Review the Structure of Local Component SettingsIn this step we review the structure of the settings specified for a local component.

Similar to the render.js file in the /assets directory, there is a pre-createdsettings.html file in the same directory. The settings.html file renders anycustom settings data for your component. In the default implementation, there is asingle property imageWidth in the custom settings data.

To review the structure of your local component:

1. Using the Oracle Content and Experience desktop sync client, locate yourcomponent and sync it with the file system.

If you don’t have the desktop sync client, you can select the component on theComponents tab of the Oracle Content and Experience web interface and drilldown to see the files.

2. If you list the files under the component, you’ll see these files:

assets render.js settings.htmlappinfo.json_folder_icon.jpg

Open the settings.html file under the /assets directory and review the content.Unlike the render.js file, the settings.html file uses an inline frame in theSettings panel in Site Builder, which is why it also needs access to the supporting filesto render correctly within the inline frame. Site Builder is needed to manage your siteso any errors in your JavaScript code can be isolated from Site Builder, which is whythe settings.html file uses an inline frame.

These are the main areas of the settings.html file:

Chapter 16Step 3: Review the Structure of Local Component Settings

16-7

• Knockout Template to render the Settings panel.

<div class="scs-component-settings"> <div>  <label id="widthLabel" for="width" class="settings-heading" data-bind="text: 'Image Width'"></label> <input id="width" data-bind="value: width" placeholder="example: 200px or 33%" class="settings-text-box"> </div></div><div data-bind="setSettingsHeight: true"></div>

• Custom Binding Handler to adjust the height of the inline frame once the Settingspanel has been rendered.

ko.bindingHandlers.scsCompComponentImpl

• A Knockout ViewModel to apply to the Knockout Template.

SettingsViewModel

These are the main elements of SettingsViewModel :

• Subscriptions to component lifecycle.

• Component initialization:

– Make sure the component doesn't render until all data has been fetched. Thisis handled through Knockout observables.

self.initialized = ko.observable(false);

– Make sure we don't attempt to update the data until we're ready.

self.saveData = false;

– Get the initial values for any required properties. This is handled by callbacksto retrieve the data.

SitesSDK.getProperty('customSettingsData', function (data) { //update observable self.width(data.width);

// note that viewModel is initialized and can start saving data self.initialized(true); self.saveData = true; });


16-8

• Save any property changes to the custom settings data.

self.save = ko.computed(function () { var saveconfig = { 'width': isNaN(self.width()) ? self.width() : self.width() + 'px' };

// save data in page if (self.saveData) { SitesSDK.setProperty('customSettingsData', saveconfig); } }, self);

To add another property that you want to capture, several steps are required:

1. Update the user interface to display the new value.

2. Initialize the value to the current value stored against the component.

3. Save any changes to the value back to the component.

To add another property to your custom component, make these changes to thesettings.html file:

1. Add another observable to handle the new property. Change this code:

self.width = ko.observable();


self.width = ko.observable();self.imageBannerText = ko.observable();

2. Get any current value for the new property when the settings panel is firstdisplayed. Change this code:

self.width(data.width);


self.width(data.width);self.imageBannerText(data.imageBannerText);

3. Save any change to this new property. Change this code:

'width': isNaN(self.width()) ? self.width() : self.width() + 'px'


'width': isNaN(self.width()) ? self.width() : self.width() + 'px','imageBannerText': self.imageBannerText()


16-9

4. Add a user interface to display the new field. Change this code:

<label id="widthLabel" for="width" class="settings-heading" data-bind="text: 'Image Width'"></label><input id="width" data-bind="value: width" placeholder="example: 200px or 33%" class="settings-text-box">


<label id="widthLabel" for="width" class="settings-heading" data-bind="text: 'Image Width'"></label><input id="width" data-bind="value: width" placeholder="example: 200px or 33%" class="settings-text-box">

<label id="imageBannerTextLabel" for="imageBannerText" class="settings-heading" data-bind="text: 'Image Banner'"></label><input id="imageBannerText" data-bind="value: imageBannerText" placeholder="Text to display above an image" class="settings-text-box">

5. Sync or upload the settings.html file.

If you were to run this now, the field would display. However, the size of the Settingspanel doesn’t change automatically. Because you increased the size of the panel, youalso must update the components.json registration entry to the new size.

1. Download the appinfo.json file, which is at the same level as the assets/directory for you component, and update the size of the settings panel. Changethis code:

"settingsHeight": 90,


"settingsHeight": 160,

2. Sync or upload the appinfo.json file.


You should now be able to see and enter the new property you added to the Settingspanel.

1. Refresh your page in your site so Site Builder can pick up changes to thecomponent.

2. Take the page into Edit mode.

3. Drag and drop your component onto the page.

4. Bring up the Settings panel against your component.

5. Click the Custom Settings button.

You will see two fields displayed for each of the properties you have in yoursettings.html file.

Continue to Step 4: Display the New Property in the Component.


16-10

Step 4: Display the New Property in the ComponentAt the end of this section, you will be able to enter a value for a new property in theSettings panel and see the custom component change to reflect the new value.Updates to the property will also automatically be saved for you with the page.

In the render.js file, you must update two JavaScript objects in the component:

• SampleComponentViewModel

• sampleComponentTemplate

Edit render.js and update the SampleComponentViewModel component to includethe new property. Change this property:

self.showStoryLayout = ko.observable();

Use this instead:

self.showStoryLayout = ko.observable();self.imageBannerText = ko.observable();

Update SampleComponentViewModel to get any change in values. Change thisproperty:

self.imageWidth(customData && customData.width);

Use this instead:

self.imageWidth(customData && customData.width);self.imageBannerText(customData && customData.imageBannerText);

Change sampleComponentTemplate to display the new property. Change this property:

'<div data-bind="text: \'image width is: \' + imageWidth()"></div>' +

Use this instead:

'<div data-bind="text: imageBannerText"></div>' +

Sync or upload the component to the Oracle Content and Experience server.

You've now altered the component to display the new property. Unlike the Settingspanel that is embedded in an inline frame on the page, because the component isinserted directly into the page, as it grows in size the area available to it willautomatically increase.


To see the new property displayed:

Chapter 16Step 4: Display the New Property in the Component

16-11

1. Refresh your page in your site to Site Builder can pick up changes to thecomponent.





6. Change Image Banner to Workspace.

You will see the component update on the page to Worksapce appear above theimage.

Continue to Step 5: Register Triggers.

Step 5: Register TriggersIn this step, you will review how an Oracle Content and Experience trigger can beenregistered, which you can select using the Trigger Actions option under the Link tab inthe Settings panel for your component.

Triggers are part of Oracle Content and Experience intercomponent communication.Any component can raise any number of triggers. The component can provide apayload for a trigger, which is then passed to any action that is executed when thetrigger is raised. Users can select what actions should be executed for each trigger.Finally, components that are built to work together can automatically raise triggers toexecute actions on the other component without the user needing to define theinteraction between the components.

For components you add, triggers are registered as part of the registration data for thecomponent. To add a trigger, update the "triggers" property array with each triggerthe component supports. You also must specify the payload the trigger supports sothat the user interface can be created to allow the user to map values within thepayload to properties supported by the action.

Open the appinfo.json file and review the "triggers":[], entry.

"triggers": [{ "triggerName": "imageClicked", "triggerDescription": "Image clicked", "triggerPayload": [{ "name": "payloadData", "displayName": "Trigger Payload Data" }]}],

In this entry, you’ll see the following:

• A triggerName, "imageClicked", which should be a unique value, and will betypically namespaced by your custom component ID.

• A triggerDescription, "Image clicked", which is used by the user interface dialogto display your trigger.

• A single value triggerPayload, "payloadData", for your trigger. Users will be ableto select entries in this payload and map them to fields in the action.

Chapter 16Step 5: Register Triggers

16-12


You can see and select your trigger when you go to the Link tab in the Settings panelfor your component:





5. Select the Link tab at the top of the Settings panel.

6. Click Trigger Actions as the Link Type.

7. Click the Image clicked trigger that you registered.

8. In the dialog, drag the Show Alert action from within the Page Actions section.(Page Actions are built-in actions supplied by Oracle Content and Experience.)

9. In the Message field, select the Trigger Payload Data value, which is the name ofthe entry in the payload you saw when you registered the trigger. You can changethis to any name you want.

Now you’re able to register a trigger and map the trigger to a built-in action, passingthrough a value. In the next step we’ll review how the trigger is raised to execute theaction.

Continue to Step 6: Raise Triggers.

Step 6: Raise TriggersIn this step, we’ll show you how the trigger you saw registered is raised.

Triggers can be raised at any point by a component. Typically it is raised by a userinteraction, by clicking a button or selecting a row in a table. However, the componentcan raise the trigger based on any criteria; for example, when data changes becauseof a REST call.

For this sample, when you click the image it will raise a trigger passing through thecurrent value of the whoAreYou property.

Review the render.js file and look at the SampleComponentViewModel object.

To raise a trigger:

1. Review the function in the SampleComponentViewModel object that calls the SitesSDK to raise the trigger.

self.raiseTrigger = function (triggerName) { SitesSDK.publish(SitesSDK.MESSAGE_TYPES.TRIGGER_ACTIONS, { 'triggerName': triggerName, 'triggerPayload': { 'payloadData': 'some data here' } });};

Chapter 16Step 6: Raise Triggers

16-13

2. Now you need something in the user interface to call the function to raise thetrigger. Review the render.js file and update the sampleComponentTemplateobject to have this entry:

'<div data-bind="attr: {style: imageStyle, \'data-layout\': alignImage()}, click: imageClicked">' +

In the SampleComponentViewModel object, you see the JavaScript function that is calledwhen the image is clicked. This function calls the Sites SDK to tell it to trigger all theactions defined for the trigger "imageClicked", which is the value passed in from theclick binding in step 2. It also passes through a triggerPayload that has a singlefield:payloadData and passes through a static value 'some data here'. These valuesimageClicked and whoAreYou match those in the appinfo.json file where the triggeris registered (in the previous step).

In the sample code, the trigger is raised by a data-bind of the click binding andpasses in the trigger name imageClicked. There are currently three renderings of the<scs-image> component based on the layout the user chooses. To ensure that thetrigger is raised for each of the layouts, edit the render.js file to make the followingchanges.

• Raise triggers from different layouts. Find the two entries of this code:

'<div data-bind="attr: {style: imageStyle, \'data-layout\': alignImage()}">' +

Change the code to this:

'<div data-bind="attr: {style: imageStyle, \'data-layout\': alignImage()}, click: imageClicked">' +

• Specify the payload to pass to the triggers. Change this code:

self.raiseTrigger = function (triggerName) { SitesSDK.publish(SitesSDK.MESSAGE_TYPES.TRIGGER_ACTIONS, { 'triggerName': triggerName, 'triggerPayload': { 'payloadData': 'some data here' } }); };


self.raiseTrigger = function (triggerName) { SitesSDK.publish(SitesSDK.MESSAGE_TYPES.TRIGGER_ACTIONS, { 'triggerName': triggerName, 'triggerPayload': { 'payloadData': self.imageBannerText() // pass banner text as payload } }); };


16-14

• Sync or upload the render.js file to the Oracle Content and Experience instanceserver.

Now that you've reviewed the required code, you can hook up the trigger so that yourcustom component will raise it when the button is clicked.


You should now be able to register an action to execute against your trigger and alsohave the action execute when the trigger is raised:






6. Select Trigger Actions as the Link Type.

7. Click the imageClicked trigger that you saw registered.

8. In the dialog, drag the Show Alert action from with the Page Actions section.

9. In the Message field, select the payloadData value, which is the payload youentered when you registered the trigger.

10. Close the Settings panel and switch Site Builder to Preview mode.

11. Click the image in the component.

An alert will appear showing no message defined because you haven’t specifiedthe imageBannerText value.

12. Take the page into Edit mode and bring up the Settings panel again for thecomponent.

13. Click Custom Settings and enter Workplace.

14. Close the Settings panel and switch the page to Preview mode.

15. Click the image in the component.

Now it should show the updated payload Workplace, which is invoked from thechange you made to the click binding.

You can execute any number of actions when a trigger is raised.

Note:

There is no pre-defined order to when an action is executed. Although eachaction will be called in the order it is listed, there is no wait for it to completebefore the next action is called. If an action makes an asynchronous call, itmay not complete before the next action is executed.

Continue to Step 7: Register Actions.


16-15

Step 7: Register ActionsOracle Content and Experience actions are called on components when triggers areraised.

A component can register any number of actions and also define the payload theaction supports. When a user selects an action, they can populate the payload to bepassed to the action.

As with registering triggers, you can register actions that your component supports inthe appinfo.json file registration data. To review the registration of the sampleaction in your component, open the appinfo.json file and find the "actions" code.

"actions": [{ "actionName": "setImageWidth", "actionDescription": "Update the image width", "actionPayload": [{ "name": "imageWidth", "description": "Image Width in pixels", "type": { "ojComponent": { "component": "ojInputText" } }, "value": "" }]}]

This registered action will be visible in the Action dialog that’s invoked when you clicka trigger in the Link tab in the Settings panel for the component.


1. Refresh your page in your site so Site Builder can pick up the changes to thecomponent.



4. Drop a Button component onto the page.

5. Bring up the Settings panel against the Button component.

6. On the General tab, change the label of the button to Click me!

.

7. Select the Link tab on the Settings panel.


9. Click the Click on Button trigger against the Button component.

10. In the dialog, expand the A_Local_Component component in the left side palette.

11. Drag and drop the Update the image width action from the A_Local_Componentcomponent onto the page.

Chapter 16Step 7: Register Actions

16-16

12. Enter 300px in the Image width in pixels field.

You've now seen how you can register an action and how that action will show up inthe user interface. In the next step you will learn how to handle an action within yourcomponent when it is called.

Continue to Step 8: Execute Actions.

Step 8: Execute ActionsAt the end of this topic, you'll be able to drop components on the page that executeactions within your component. This leverages the action registration you created inthe previous step.

For a component to execute an action, it must listen for the EXECUTE_ACTION message.This message also includes the payload passed to the action from which you willextract the expected values.

To listen for the EXECUTE_ACTION message, edit the render.js file and update theSampleComponentViewModel object with the following entry:

SitesSDK.subscribe('EXECUTE_ACTION', $.proxy(self.executeActionsListener, self));

When the EXECUTE_ACTION message is received, the associated callback function isexecuted:

self.executeActionsListener = function (args) { // get action and payload var payload = args.payload, action = args.action;

// handle 'setImageWidth' actions if (action && action.actionName === 'setImageWidth') { $.each(payload, function(index, data) { if (data.name === 'imageWidth') { self.imageWidth(data.value); } }); } }

This creates a JavaScript function to execute the action, then uses the Sites SDK tocall the function whenever the EXECUTE_ACTION message is raised.

The component will be called whenever an EXECUTE_ACTION message is raised, and itis up to the component to only handle actions it is designed to handle. To do this, youmust check the name of the action to ensure it is one the component can handle.

The payload for the action is an array of values. Typically, you will need to find thepayload values you care about from the array.

Chapter 16Step 8: Execute Actions

16-17

Note:

Because the action listener is a callback, you should use JavaScript Closureor appropriately bind the function to ensure you have access to yourviewModel when the function is executed.





4. Drag and drop a Button component onto the page.

5. Bring up the Settings panel against the Button component.

6. On the General tab, change the Label of the button to Click me!



9. Click the Click on Button trigger against the Button component.

10. In the dialog, expand the A_Local_Component component in the left side.

11. Drag and drop the Update the image width action from the A_Local_Componentcomponent onto the right side.

12. Enter 300px in the Image Width in pixels field.

13. Switch the page to Preview mode.

14. Click the Click me! button.

At this point the size of your image will increase to 300px.

Note:

Triggers and actions are designed to support inter-componentcommunication. They are not designed to create or manage state. If yourefresh the page, the page will revert to its original state as if no triggers wereraised or actions executed.

Continue to Step 9: Create a Distinct Title for Each Instance of the Component.

Step 9: Create a Distinct Title for Each Instance of theComponent

This step explains how to create distinct titles for different instances of yourcomponent.

When you drop your component onto the page, you will have noticed the banner foryour component reads: A_Local_Component. While this is fine if the user only drops

Chapter 16Step 9: Create a Distinct Title for Each Instance of the Component

16-18

one of your components onto the page, you may want to create distinct titles so theuser can distinguish between different instances of your component.

You can use the Sites SDK to update the title for the component. In this step, you willupdate it based on the "imageBannerText" property.

To update the title, edit the render.js file and add this code to yourSampleComponentViewModel object:

self.updateDescription = ko.computed(function () { SitesSDK.setProperty('description', self.imageBannerText());});

This Knockout computation will update the description for your component wheneverthe imageBannerText observable changes.




3. Drop your component onto the page.



6. Change the Image Banner to Workplace.

7. Close the Settings panel and hover your cursor over your component to show thebanner.

You should now see A_Local_Component Workplace displayed.

Continue to Step 10: Use Nested Components with In-Line Editing.

Step 10: Use Nested Components with In-Line EditingOracle Content and Experience components are implemented using KnockoutJScomponent architecture. This means that if you are using KnockoutJS to implementyour components, you can include Oracle Content and Experience built-in componentsdirectly into your template.

Note:

Because Oracle Content and Experience built-in components can only run inthe Oracle Content and Experience page, you can't use nested componentsif your component is rendered in an inline frame.

To leverage nested components:

1. Implement your component using KnockoutJS.

2. Use RequireJS to include your component and use the same Knockout "ko"instance variable that is created by Oracle Content and Experience.

Chapter 16Step 10: Use Nested Components with In-Line Editing

16-19

This is required because Oracle Content and Experience extends Knockout withcomponents and these components won’t be available if you use your owninstance of KnockoutJS.

In this step you will review how the Oracle Content and Experience Image, Paragraph,and Title components are rendered in your custom component. A user will be able toedit it directly within the page and access the Settings panel for the nested component.

To see how these components are included in your template, edit the render.js fileand look at the sampleComponentTemplate object. The default section that is renderedis shown here:

'' +'<div style="display:flex;">' +'<div data-bind="attr: {style: imageStyle, \'data-layout\': alignImage()}, click: imageClicked">' +'<scs-image params="{ scsComponent: { \'renderMode\': mode, \'parentId\': id, \'id\': \'imageId\', \'data\': imageData } }"></scs-image>' +'</div>' +'<div data-bind="attr: {style: paragraphStyle}">' +'<scs-title params="{ scsComponent: { \'renderMode\': mode, \'parentId\': id, \'id\': \'titleId\', \'data\': titleData } }"></scs-title>' +'<scs-paragraph params="{ scsComponent: { \'renderMode\': mode, \'parentId\': id, \'id\': \'paragraphId\', \'data\': paragraphData } }"></scs-paragraph>' +'</div>' +'</div>' +'' +

Looking at the <scs-image> nested component, you will see the following entry:

'<scs-image params="{ scsComponent: { \'renderMode\': mode, \'parentId\': id, \'id\': \'imageId\', \'data\': imageData }}"></scs-image>' +

The scsComponent data passed to the params template binding includes the following:

• renderMode: This refers to the mode Site Builder is in. You can use this to enableand disable features. For example, when used by the <scs-title> component, itadds the rich text editor when running in edit mode.

• parentId: This is required so the Oracle Content and Experience componentknows that it is rendering as a nested component. All changes to the nestedcomponent will be saved in the data for the custom component.

• id: A unique ID for the nested component. This will be further namespaced by theID for the custom component.

• data: Initial data for the nested component. If the component isn't further modified,it will render with this initial data.

Chapter 16Step 10: Use Nested Components with In-Line Editing

16-20

The referenced id and mode values are passed in to your custom component in theSampleComponentViewModel object, so you don't need to modify the object to get thesevalues:

// Store the argsself.mode = args.viewMode;self.id = args.id;

The syntax for all the other supported nested components follows the same pattern asfor <scs-paragraph>; for example: <scs-image>, <scs-title>, <scs-button>.





4. Click the As a page author, you can edit. . . text in your component andupdate the description using the rich text editor.

5. Switch to Preview mode to see your update.

6. Switch back to Edit mode.


8. Click the Components link that now appears, because it found your nestedcomponent.

9. Click Paragraph, which is the nested component it found.

You can now update the properties against the Paragraph component within yourcomponent.

Note:

Until the component has been instantiated, Oracle Content and Experiencedoes not know about any nested components that may exist in the template.To tell Oracle Content and Experience about hidden nested components,you can use the SitesSDK.setProperty('visibleNestedComponents',[]); API. To have hidden nested components show-up by default, you mustupdate the "nestedComponents": [] array in the component registration.

Continue to Step 11: Support Different Layouts.

Step 11: Support Different LayoutsIn this step we will review layouts that allow the user to alter how the componentdisplays.

A custom component can support any number of layouts that you want to allow theuser to choose. Each of these layouts will alter how the custom component displays.Layouts are another extension to the registration data.

Chapter 16Step 11: Support Different Layouts

16-21

To review the three layouts supported in the sample code, review the"componentLayouts" entry in the appinfo.json file

"componentLayouts": [ { "name": "default", "displayName": "IMAGE_LEFT_LAYOUT" }, { "name": "right", "displayName": "IMAGE_RIGHT_LAYOUT" }, { "name": "top", "displayName": "IMAGE_TOP_LAYOUT" } ],

If you bring up the Settings panel against the custom component, you will see anoption to switch between layouts. To enable your component to react to the change inselection, the render.js file has code to get the currently selected value and listen forchanges to this value.

Edit the render.js file and look at the SampleComponentViewModel object.

• There is a layout observable, which is referenced in the template:

self.layout = ko.observable();

• There is an update function to handle whenever this value changes:

self.updateComponentLayout = $.proxy(function (componentLayout) { var layout = componentLayout ? componentLayout : 'default'; self.layout(layout); self.alignImage(layout === 'right' ? 'right' : 'left'); self.showTopLayout(layout === 'top'); self.showStoryLayout(layout === 'default' || layout === 'right');

self.componentLayoutInitialized(true); }, self);

• The initialization code gets the original value for the layout and calls the updatefunction:

SitesSDK.getProperty('componentLayout', self.updateComponentLayout);

The property change listener checks for any changes to this property and calls theupdate function:

self.updateSettings = function (settings) { if (settings.property === 'componentLayout') { self.updateComponentLayout(settings.value); } else if (settings.property === 'customSettingsData') { self.updateCustomSettingsData(settings.value);

Chapter 16Step 11: Support Different Layouts

16-22

}};

SitesSDK.subscribe(SitesSDK.MESSAGE_TYPES.SETTINGS_UPDATED, $.proxy(self.updateSettings, self));

Finally the sampleComponentTemplate template object has code to reflect changesin this value:

'' +

Together, these changes allow you to select your layout in the Settings panel andhave the component update.






5. Select Image Right from the Layout property.

At this point the component will update to show the "<scs-image>" component.

Continue to Step 12: Define Custom Styles.

Step 12: Define Custom StylesComponents you create are treated like any other component in the design.jsonand design.css files in the theme used for your site.

To add your own style for your custom component, confirm the id value you usedwhen you registered your component. In the appinfo.json file; this was "id":"hello-world".

Using that value, edit the theme's design.json file and add in the new styles youwant to support against that id. For example, edit the /designs/default/design.json file in your theme and add this code:

"hello-world": { "styles": [{ "name": "Plain", "class": "hello-world-default-style" }, { "name": "Gothic", "class": "hello-world-gothic-style" }]},

If you bring up the Settings panel against your component, you should now see Plain(default) and Gothic as the two options listed in the Style tab. However, switching

Chapter 16Step 12: Define Custom Styles

16-23

between these options will not do anything until you actually define the style classeslisted in the design.css file.

Edit the theme’s design.css file and add in the cascading style sheet (CSS) classesof your style. For example, edit the /designs/default/design.css file in yourtheme and add this code:

.hello-world-default-style .scs-component-content { font-family: "Helvetica Neue", "Helvetica", "Arial", sans-serif; font-size: 24px; font-weight: normal; }

.hello-world-gothic-style .scs-component-content { font-family: "Century Gothic","CenturyGothic","AppleGothic",sans-serif; font-size: 32px; font-weight: bold; }

Save and sync your files to the Oracle Content and Experience instance server.


1. Refresh your page in your site so Site Builder can pick up the changes to thecomponent.




5. Go to the Style tab.

6. Switch between the Gothic and Plain styles that were defined in yourdesign.json file.

You’ll notice that the font size within your component adjusts to reflect the changesas it switches between the applied CSS class for each selection.

Continue to Step 13: Render a Component in an Inline Frame.

Step 13: Render a Component in an Inline FrameThe sample so far has shown a local component rendered in-line in the page. You canalso choose to render a component in an inline frame.

For example, you may choose to render a component in an inline frame if yourcomponent does non-omnipotent updates to the page, which requires you to re-createthe page whenever properties change. In addition, remote components are alwaysrendered in an inline frame.

The samples in this section are taken from the files created for you when you choosethe Create a component that renders in an iframe option when creating a localcomponent. You can, however, take these set of files and host them on your remoteserver so they apply equally to remote components.

Similarities Between Inline Frame and Non-Inline Frame Components

Settings Panel

Chapter 16Step 13: Render a Component in an Inline Frame

16-24

Because the Settings panel is always placed into the page in an inline frame, the codefor the Settings panel doesn't change regardless of whether the component uses aninline frame or not. You’ll create the same Settings panel code for both use cases.

Sites SDK API

The SDK API is the same for both use cases. You’ll use the same code to raisetriggers, listen for actions, and get and set property values. While certain propertiesmay not be applicable in both cases (for example, you can't set the "height" propertyfor a component that doesn’t use an inline frame) the API remains the same.Therefore, you can copy the code between both of these types of components and theexample code discussed in this tutorial will work for both cases.

Differences Between Inline Frame and Non-Inline Frame Components

File Structure and Dependencies

When you select Create a component that renders in an iframe when creating alocal component, you will see the following files created for you:

<component name> assets css app-styles.css js jquery.mn.js knockout.mn.js sites.min.js render.html settings.html appinfo.json _folder_icon.jpg

These files are created to allow you to immediately run your component in an inlineframe on the page. The main differences between this structure and that of a standardlocal component are:

• JavaScript dependencies:

– You are getting a complete copy of these files so your component will run.These files are required for the sample inline frame component to run. Youcan add and remove the content of this directory based on your requirements.

– Because everything under the assets directory for your component is pushedto a public site when the component is published, everything in the jsdirectory will be available both in Site Builder and at runtime.

– Note: These files are created for ease of use. You should look at consolidatingthese files in the theme or in another public location rather than createseparate versions of these files for each of your inline frame components.

• render.html:

– This is a full HTML document as opposed to the render.js file for standardcomponents, which is an AMD module.

Component "Height" Management


16-25

One of the issues in using an inline frame is the height management of the inline frameitself. If you get this wrong, you will see scroll bars appearing for the component on thepage, which you may or may not want.

In order to manage the height of the inline frame, the component must tell the pagehow tall it wants the inline frame to be. With remote components, you may be dealingwith cross-domain issues, so you must use Sites SDK messaging to ask the page toset the inline frame to the required height after the component has rendered on thepage. This is done by using the SitesSDK.setProperty('height', {value}) API.(See Oracle Content and Experience Sites SDK Reference.)

For example, create the setHeight function and a custom binding handler to call itwhen the component has rendered on the page.

• Update height function:

// set the height of the iFrame for this Appself.setHeight = function () {// use the default calculation or supply your own height value as a second parameterSitesSDK.setProperty('height');};

• Knockout custom binding handler to call setHeight whenever the component isrendered on the page or a property changes:

ko.bindingHandlers.sampleAppSetAppHeight = { update: function (element, valueAccessor, allBindings, viewModel, bindingContext) { // create dependencies on any observables so this handler is called whenever it changes var imageWidth = viewModel.imageWidth(), imageUrl = viewModel.imageUrl(), titleText = viewModel.titleText(), userText = viewModel.userText();

// re-size the iFrame in the Sites page now the template has rendered // Note: If you still see scrollbars in the iframe after this, it is likely that CSS styling in your app is the issue viewModel.setHeight(); }};

• Template update to call binding handler:

<div data-bind="sampleAppSetAppHeight: true"></div>

Trigger and Action Registration

While the trigger/action registration for components that are not in inline frames islocated in the appinfo.json file, for inline frame components, the component itself isresponsible for providing this information. This is done using these two APIs:

SitesSDK.subscribe('GET_ACTIONS', self.getAppActions);SitesSDK.subscribe('GET_TRIGGERS', self.getAppTriggers);


16-26

Here’s an example of using these APIs.

// Register TRIGGERS meta-data SampleAppViewModel.prototype.getAppTriggers = function (args) { var triggers = [{ "triggerName": "imageClicked", "triggerDescription": "Image clicked", "triggerPayload": [{ "name": "payloadData", "displayName": "Trigger Payload Data" }] }];

return triggers; };

// Register ACTIONS meta-data SampleAppViewModel.prototype.getAppActions = function (args) { var actions = [{ "actionName": "setImageWidth", "actionDescription": "Update the image width", "actionPayload": [{ "name": "imageWidth", "description": "Image Width in pixels", "type": { "ojComponent": { "component": "ojInputText" } }, "value": "" }] }];

return actions; };

Access to Theme Styles

Because the component is rendered in an inline frame, it doesn't have access to thestyles available in the theme. The Sites SDK provides an API to retrieve these stylesso they can be applied to elements within the inline frame.

This topic is explored more in Step 14: Use Custom Styles When the Component isRendered in an Inline Frame.

Mixed HTTPS Versus HTTP Protocol

Because Oracle Content and Experience uses the HTTPS protocol, all resourcesreferenced within the page also must use HTTPS. Resources include the base .htmlfile that will be rendered in the inline frame along with all the files that it references.

This resource requirement applies mostly to remote components, however, you mustbe aware of this constraint. Resources for local components using inline frames areprovided by the Oracle Content and Experience server, so these components alreadyuse a matching protocol.


16-27

Continue to Step 14: Use Custom Styles When the Component is Rendered in anInline Frame.

Step 14: Use Custom Styles When the Component IsRendered in an Inline Frame

Components rendered in an inline frame don't have direct access to the design.cssfile. Instead there is an additional step to get the URL for the design.css in yourcomponent and add it to the page. You then must update your component to reflectthe user-selected style.

To include and use the design.css file in your component requires changes in therender.html file:

1. Locate and include the URL to the design.css file

2. Get the value of the select style class whenever it changes

3. Update the template to reflect the styleClass selected

4. Reflect changes to the selected style class in your component

5. Make sure the inline frame resizes when the style changes

Here are the detailed instructions for editing the render.html file:

1. Locate and include the URL to the design.css file.

Dynamically add the design.css file to the <head> section of the page. After ithas been loaded, set the height of the inline frame because it may have beenaltered by applying the styles.

Add the following code into the viewModel object:

// Dynamically add any theme design URL to the <head> of the pageself.loadStyleSheet = function (url) { var $style, styleSheetDeferred = new $.Deferred(), attempts = 100, numAttempts = 0, interval = 50, pollFunction = function () { // try to locate the style sheet for (var i = 0; i < document.styleSheets.length; i++) { try { // locate the @import sheet that has an href based on our expected URL var sheet = document.styleSheets[i], rules = sheet && sheet.cssRules, rule = rules && rules[0]; // check whether style sheet has been loaded if (rule && (rule.href === url)) { styleSheetDeferred.resolve(); return; } } catch (e) {} }

Chapter 16Step 14: Use Custom Styles When the Component Is Rendered in an Inline Frame

16-28

if (numAttempts < attempts) { numAttempts++; setTimeout(pollFunction, interval); } else { // didn't find style sheet so complete anyway styleSheetDeferred.resolve(); } }; // add the themeDesign stylesheet to <head> // use @import to avoid cross domain security issues when determining when the stylesheet is loaded $style = $('<style type="text/css">@import url("' + url + '")</style>'); $style.appendTo('head'); // kickoff the polling pollFunction(); // return the promise return styleSheetDeferred.promise();}; // update with the design.css from the Sites PageSitesSDK.getSiteProperty('themeDesign', function (data) { if (data && data.themeDesign && typeof data.themeDesign === 'string') { // load the style sheet and then set the height self.loadStyleSheet(data.themeDesign).done(self.setHeight); }});

2. Get the value of the select style class whenever it changes.

Create an observable to track when the value of the styleClass propertychanges. :

self.selectedStyleClass = ko.observable();

Note that we can’t render until we have the style class. Change this code:

self.customSettingsDataInitialized = ko.observable(false);self.initialized = ko.computed(function () { return self.customSettingsDataInitialized();}, self);


self.customSettingsDataInitialized = ko.observable(false);self.styleClassInitialized = ko.observable(false);self.initialized = ko.computed(function () { return self.customSettingsDataInitialized() &&


16-29

self.styleClassInitialized();}, self);

Get the initial value for the selected style class by adding:

self.updateStyleClass = function (styleClass) { self.selectedStyleClass((typeof styleClass === 'string') ? styleClass : 'hello-world-default-style'); // note that this 'hello-world' prefix is based on the app name self.styleClassInitialized(true);};SitesSDK.getProperty('styleClass', self.updateStyleClass);

3. Update the template to reflect the styleClass . Change this code:

<p data-bind="attr: {id: 'titleId'}, text: titleText"></p>


<p data-bind="attr: {id: 'titleId'}, text: titleText, css: selectedStyleClass"></p>

4. Reflect changes to the selected style class in your component. Change this code:

if (settings.property === 'customSettingsData') { self.updateCustomSettingsData(settings.value);}


if (settings.property === 'customSettingsData') { self.updateCustomSettingsData(settings.value);}if (settings.property === 'styleClass') { self.updateStyleClass(settings.value);}

5. Make sure the inline frame re-sizes when the style changes. Change this code:

// create dependencies on any observables so this handler is called whenever it changesvar imageWidth = viewModel.imageWidth(), imageUrl = viewModel.imageUrl(), titleText = viewModel.titleText(), userText = viewModel.userText();


// create dependencies on any observables so this handler is called whenever it changesvar imageWidth = viewModel.imageWidth(), imageUrl = viewModel.imageUrl(),


16-30

titleText = viewModel.titleText(), userText = viewModel.userText(), selectedStyleClass = viewModel.selectedStyleClass();

6. Save and sync your files to the Oracle Content and Experience instance server.






5. Go to the Style tab.

6. Switch between Gothic and Plain styles defined in your design.json file.

You’ll notice the font size changes within your component it switches between theapplied CSS class for each selection. The inline frame also re-sizes as you choosea different style.

Continue to Step 15: Integration with the Page Undo and Redo Behavior.

Step 15: Integration with the Page Undo and Redo BehaviorBecause Oracle Content and Experience stores properties on behalf of the customcomponent, changes to those properties are automatically part of the page's Undoand Redo behavior.

To ensure that it is clear what is happening when a user clicks Undo or Redo, these"undo events" should only happen when a user has actually done something to thepage. For example, bringing up the custom component Settings panel should notupdate the properties within the page until the user actually makes a change to theproperty. Simply initializing the properties in the Settings panel should not cause anupdate event.

If care is not taken to ensure this behavior, then unexpected behavior may occur. Thepage will still run, but to the detriment of the user experience. For example, thesebehaviors may occur:

• The Save button will become active simply by bringing up the Settings panel.

• The user must click Undo multiple times before any effect is visible.

• The Redo stack is removed because the component wrote back an unexpectedchange and updated the Redo stack with the new value.

The sample code provided in this tutorial for the Settings panel gives an example ofhow to ensure you are only writing back when you're ready to actually call saveDataand not on initialization. Similar care should be taken within the component itself to notupdate customSettingsData unless it involved a user interaction, though typically thisis less of a concern.

Continue to Step 16: Asset Management.

Chapter 16Step 15: Integration with the Page Undo and Redo Behavior

16-31

Step 16: Asset ManagementThis step describes and explains how to manage the assets used by a component.

Assets include components and custom components that Oracle Content andExperience must know about to manage the life cycle of the assets.

Oracle Content and Experience content Folder

Each site that you create in Oracle Content and Experience comes with its owncontent folder. This is a hidden folder that you won't normally see. When the site ispublished, all the files in the content folder are also published to the file system.

For example, when you select an image using the Image component, Oracle Contentand Experience makes a copy of the image you selected and places it in the contentfolder. Your URL always points to this copied version of the image so that if you deletethe original image, your site won't break. This also applies to the other componentsprovided by Oracle Content and Experience: Gallery, Gallery Grid, Document, SocialBar, File Download, as well as background images for slots and componentGroups.

For a custom component to take part in this asset life cycle, the custom componentmust tell Oracle Content and Experience about any assets it wants the service tomanage on its behalf. Because this involves making a copy of the asset, the customcomponent must also use Oracle Content and Experience APIs to select the asset sothat we know how to manage it.

Manage URLs

The URL to an asset changes based on a number of criteria.

• The runtime URL to a component is different than the Site Builder URL to thecomponent

• If you copy a page, Oracle Content and Experience also makes a copy of all thereferenced assets in the content folder so you never have two componentspointing to the same asset in the content folder

• Dropping a componentGroup onto the page makes new copies for any assetsreferenced by a component in the componentGroup

In addition, while a relative URL may be fine for a local component, remotecomponents require the fully qualified URL to any asset that you want Oracle Contentand Experience to manage on your behalf so they can render their inline frame contentwith the full URL.

Because you can't rely on the URL remaining static, you must only hold references tothe ID to the asset in your code and retrieve the asset's URL when you want to renderthe asset.

Manage Assets

These Sites SDK APIs are available for managing assets.

SitesSDK.getProperty('componentAssets', callback);

• This gets the array of current assets

• Each asset entry consists of:

Chapter 16Step 16: Asset Management

16-32

– id: Unique ID for the asset.

– title: Oracle Content and Experience title metadata.

– description: Oracle Content and Experience description metadata.

– fileName: Original name of the selected file. Useful for display in the Settingspanel for your custom component so users know what file they selected. Thisis not the name of the file copied to the content folder.

– source: Macro enabled URL to the asset. This value will change over timeand should not be referenced by your component, but it must be saved as partof the asset.

– url: Fully qualified URL to the asset based on the context in whichgetPropert() was called.

SitesSDK.setProperty('componentAssets', [assets]);

• Call this to save all the assets you want Oracle Content and Experience tomanage on your behalf.

• If you don't call this, then no asset will be saved.

• Any assets not in this array will be deleted when the site is published.

• The assets parameter is an array of assets in the same format as you getreturned by getProperty and is also returned by filePicker.

Note:

No url value is stored. That value is dynamically created when you askfor the assets.

SitesSDK.filePicker(options, callback);

• An API to bring up the file picker to select the list of assets.

• It calls the callback on successful selection of assets passing in the array ofselected assets.

• Nothing is saved at this point and it’s up to the component to callsetProperty('componentAssets', [assets]); to save items from this selectioncombined with any other assets to be saved.

Example of Select Asset

This section shows you how to select an asset, store its ID, and re-fetch the actualvalues from the stored assets.

1. Edit the settings.html file.

2. Change the template object to include an Image selection.

<div>  <label id="imageLabel" for="imageAsset" class="settings-heading" data-bind="text: 'Image'"></label> <input id="imageAsset" data-bind="value: imageName" readonly class="settings-text-box"> <button id="imageSelect" type="button" class="selectbutton" data-


16-33

bind="click: showFilePicker">Select Image</button></div>

3. Change the viewModel to add an observable to store the ID of the selected asset.

self.imageID = ko.observable();

4. Change the viewModel to manage selection of the asset by bringing up the filepicker and displaying the name of the selected asset.

//// handle component assets//self.assets = [] // bring up a file picker to select the assetsself.showFilePicker = function () { // select an image SitesSDK.filePicker({ 'multiSelect': false, 'supportedFileExtensions': ['jpg', 'png'] }, function (result) { if (result.length === 1) { // update the array of assets self.assets = result; // update the image in customSettingsData self.imageID(result[0].id); } });}; // update the display name based on the assetsself.imageName = ko.computed(function () { var imageName = '', imageID = self.imageID(); for (var i = 0; i < self.assets.length; i++) { if (self.assets[i].id === imageID) { imageName = self.assets[i].fileName; break; } } return imageName}, self);

5. Update the viewModel to first retrieve the assets before getting thecustomSettingsData. This code will also cause the self.imageName to be invokedwhen the self.ImageID() observable changes.

SitesSDK.getProperty('componentAssets', function (assets) { self.assets = assets; SitesSDK.getProperty('customSettingsData', function (data) { //update observable


16-34

self.imageWidth(data.imageWidth); self.imageID(data.imageID); self.titleText(data.titleText); self.userText(data.userText); // note that viewModel is initialized and can start saving data self.initialized(true); self.saveData = true; });});

6. Finally, update the save function to save the imageID and make sure to update thecomponentAssets with your list of referenced assets.

self.save = ko.computed(function () { var saveconfig = { 'imageWidth': isNaN(self.imageWidth()) ? self.imageWidth() : self.imageWidth() + 'px', 'imageID': self.imageID(), 'titleText': self.titleText(), 'userText': self.userText() }; // store the selected asset and update custom settings if (self.saveData) { SitesSDK.setProperty('componentAssets', self.assets); SitesSDK.setProperty('customSettingsData', saveconfig); }}, self);

Check the Results for Select Asset



3. Drag and drop your component on the page.

4. Bring up the Settings panel.

5. Click the Select image button.

6. Browse (or upload) and select an image.

Note that the name of the image is stored showing the selected image.

7. Close out of the Settings panel.

8. Bring up the Settings panel again.

Note that the name of the image is again reflected.

Example of Render Asset

This section shows you how to retrieve the assets and render them in yourcomponent, and also have the component dynamically update whenever values arechanged in your settings panel.


16-35

Note:

Although this is showing an example for a local component that is in an inlineframe on the page, similar code will work for components rendered inline inthe page.

1. Edit the render.html file.

2. Update the template to include your asset:.

<div style="flex-shrink:0;"> <img data-bind="attr: {style: imageStyle, id: 'imageId', src: imageURL, alt: '', title: ''}, click: imageClicked" /></div>

3. In the viewModel, create two observables to get the imageID from thecustomSetttingsData and store the imageURL retrieved from the stored list ofassets.

self.imageID = ko.observable();self.imageURL = ko.observable();

4. Update the viewModel so that whenever the imageID changes, it gets thecorresponding image asset URL.

self.imageID.subscribe(function (imageID) { // whenever the image changes get the updated referenced asset SitesSDK.getProperty('componentAssets', function (assets) { for (var i = 0; i < assets.length; i++) { if (assets[i].id === imageID) { self.imageURL(assets[i].url); break; } } });});

5. Update the viewModel to retrieve the ID from the customSettingsData.

Check the Results for Render Asset



3. Drag and drop your component on the page.

4. Bring up the Settings panel.

5. Click the Select image button.

6. Browse (or upload) and select an image.


16-36

Note that the name of the image is stored showing the selected image.

7. Close out of the Settings panel.

At this point you should see your selected image rendered in the component.

Continue to Tutorial Review.

Tutorial ReviewThis tutorial gives you an overview of how to create a customized component using aKnockout Component Factory.

The main purpose of this tutorial is that using this pattern, you can create any customcomponent by just updating the SampleComponentViewModel andsampleComponentTemplate JavaScript objects. The sampleComponentFactory andSampleComponentImpl objects haven't changed as you went through the tutorial. Youwere able to implement these changes without having to deal with communicating withthe page, and were able to perform these tasks:

• Communicate changes from your Settings panel to your component, and havethose changes persisted.

• Execute triggers and actions, and interact with other components on the page.

• Create layouts and leverage nested components.

• Define component-specific styles.

While this example split out the custom component into a number of files, this was forclarity of the tutorial. For optimization, you should consider appropriately packagingyour files to avoid multiple downloads.

Finally, while this tutorial is suitable for Knockout based components, if you want tocreate custom components using another JavaScript technology stack such asAngularJS, you must re-implement the SampleComponentImpl object to create thecorresponding communication with that framework along with a technology specificimplementation of the actual component. This work is beyond the scope of this tutorial.

Chapter 16Tutorial Review

16-37

Integrating and Extending Oracle Content and Experience...REST API for Sites Management 4-41 REST...

Documents

Transcript of Integrating and Extending Oracle Content and Experience...REST API for Sites Management 4-41 REST...