15 Develop Custom Actions

Integrate third-party services and applications with Oracle Content and Experience through custom actions you can develop in the Application Integration Framework (AIF).

These topics describe AIF and how to use it for effective integration:

Application Integration Framework Overview

Application Integration Framework (AIF) provides a simple and effective way to integrate third-party services and applications into the Oracle Content and Experience interface.

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

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

The definition for one or more integrations is stored in a single file in JSON format. As a developer, you can upload the configuration file and add it to a list of available applications. You can also edit and validate the configuration file directly in the interface, 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 in JSON format. The configuration file defines and manages the interactions between the app, native objects and interface elements. The configuration file includes:
  • App properties including tenant and user preferences

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

  • How the results are presented to the user

  • Interface strings with support for multiple languages


Description of aif_process_flow.png follows
Description of the illustration aif_process_flow.png

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

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


Description of admin_applications.png follows
Description of the illustration admin_applications.png

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

Setting Description

Custom Application On/Off button

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

Add a New Application Definition button

Browse local folders and files to locate and upload an application configuration file.

Information icon

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

Preferences icon

Display the preferences resource defined in the tenantPrefs element of the configuration file.

Edit icon

Open the configuration file in the integrated JSON editor. The editor validates the syntax of the file to ensure that the file contains valid JSON code. Changes you make to the configuration file are immediately available in the enabled application.

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

Download icon

Download the file from the server to a local destination.

Trash icon

Delete the configuration permanently.

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

Configuration File Format

The definition for one or more integrations is stored in a single configuration file in JSON 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 the configuration are case-sensitive.

{
	"id": "ExampleCoPublishing",
	"name": "APP_SUBMIT_TO_PUBLISH_DOCS_NAME",
	"description": "APP_SUBMIT_TO_PUBLISH_DOCS_DESC",
	"category": "CUSTOM",
	"supportEmail": "support@example.com",
	"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": ""
		}
	},
	"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",
				"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 JavaScript underscore library (http://underscorejs.org); however, AIF does not allow defining functions as parameters of underscore functions.

The sections that follow describe the functional areas of the Application Integration Framework.

Functional Area Description

Application Properties

Describes the application properties.

Action Command

Describes the general elements of the action command. Use the action command to specify how to trigger and start a task. The invoke and presentation components of the action command are presented in their own sections.

Invoke Command

Describes the elements of the invoke command. Use the invoke command to call a third-party service, page, or script.

Presentation Command

Describes the elements of the presentation command. Use the presentation command to specify how the third-party content retrieved by the invoke command is presented to the user.

Expressions

Provides examples and general information about expressions used with the invoke and evaluate commands.

Variables

Provides descriptions of the available item and user variables, the permissions and status objects, and AIF functions.

Localization

Provides an example and general information about how to localize an app with translated labels and descriptions.

Application Properties

The following table shows the properties of an Application Integration Framework application.

Property Required Description

id

Yes

A non-empty string that uniquely identifies the application across Oracle Content and Experience.

name

Yes

A non-empty string that is displayed for the application’s user interface. It can also be a key that can be translated using translation maps defined in stringsMap.

description

No

A string that is displayed with the application name in the user interface. It can also be a key that can be translated using translation maps defined in stringsMap.

category

No

Category of the application. CUSTOM is the only allowed value. If you do not explicitly include category in the configuration file, it is dynamically added during application configuration and is given the default value of CUSTOM.

supportEmail

No

Email address of application support owner.

baseURL

No

Base URL used as a prefix to any relative URLs specified in the application.

stringsMap

No

Used to map languages to translation objects, so that keys in the application definition can be translated to the corresponding language.

info

No

Allows an integrator to show a dialog to display information about the application. It contains presentation and invoke properties.

documentation

No

Lets you add comments in the file, such as a comment to identify the purpose of an action. You might add a documentation property at the start of the code sample to describe the application itself.

tenantPrefs

No

Allows an integrator to expose application-level options in the preference settings. It contains presentation and invoke properties.

userPrefs

No

Allows an integrator to expose application-level options in the preference settings for users. It contains presentation and invoke properties.

actions

Yes

A collection of actions contained in the application. It must contain at least one action.

Action Command

Use the action command to specify how to trigger and start a specified task and how to present the results.

The following table shows the properties of an action command.

Property Required Description

id

Yes

A non-empty string that uniquely identifies the action in the application.

name

Yes

A non-empty string that is displayed for the action in the user interface. It can also be a key that can be translated using translation maps defined in stringsMap.

description

No

A string that is displayed for the action in a user interface tooltip. It can also be a key that can be translated using translation maps defined in stringsMap.

trigger

No

Specifies if the action is triggered through a context menu taskbar (MENU), or when the item is opened (SELECT). If you do not explicitly include trigger in the configuration file, it is dynamically added during application configuration and is given the default value of MENU.

In the Application Integration Framework, the SELECT trigger occurs when an item is opened, not when simply checked in a folder listing.

type

No

Specifies how action results are displayed to the end user. Possible values are UI and DIRECT. If the value is DIRECT, a call is made to the URL specified with invoke, and the response displays as a notification in the Oracle Content and Experience interface, if possible. If the value is UI, the presentation property specifies the type of interface to use.

presentation

No

Specifies the presentation to use if type is set to UI. Possible values are CLIENT to embed the action results in the integrations side panel on the right of the display, POPUP to display action results in a separate browser dialog, and WINDOW to display action results in a new browser window or tab. If type is set to UI and presentation is omitted, it is added to the action with the default value of CLIENT. See Presentation Command.

multi

No

Specifies if the action applies when multiple items are selected (true) or not (false). If you do not explicitly include multi in the configuration file, it is dynamically added during application configuration and is given the default value of false.

evaluate

Yes

Must be valid JavaScript Boolean value that evaluates to true or false for the selected item. For more information about expression evaluation, see Expressions.

invoke

Yes

Specifies the external service in an invoke command to use when action is triggered. See Invoke Command.

Invoke Command

Use the invoke command to call an external service, page, or script.

The following table shows the properties of the invoke command.

Property Required Description

method

Yes

Specifies the HTTP method to use for invocation. Valid values are GET, POST, PUT, DELETE, and HEAD.

url

Yes

A URL expression to specify the URL for the third-party service. It can be an absolute or relative URL. If a relative URL is specified, it will be added to the baseUrl of the application, if specified.

data

No

An expression that specifies data to be sent with the URL. See Expressions.

A JSON payload can added to the request body as a string object.

appLinkRole

No

If the action is a request to create an application link (applink), use appLinkRole to specify the role to use for the applink. Valid values are contributor, downloader, and viewer. See Applinks Resource.

header

No

A custom header to include when making POST calls.

token

No

Specifies if any special security token needs to be passed. Valid values are PCS (PCS OAUTH token) and NONE.

Presentation Command

Use the presentation command to specify how the third-party content retrieved by the invoke command is presented to the user.

The following table shows the properties of the presentation command.

Property Required Description

view

No

Specifies how action response content is displayed to the user. Use CLIENT to embed results in the application, POPUP to display results in a separate browser dialog, or WINDOW to display results in a new browser window or tab.

If you use CLIENT with the SELECT trigger, action results are displayed in the integrations side panel on the right of the display. The integrations panel must be open for the results to display. The SELECT trigger occurs when an item is opened, not when simply checked in a folder listing. If you use CLIENT with the MENU trigger, action results are displayed in a pop-up dialog. If you do not explicitly include view in the configuration file, it is dynamically added during application configuration and is given the default value of CLIENT.

popupWidth

No

A number specifying the width of the container. If none is specified, a default value is used, depending on the context.

popupHeight

No

A number specifying the height of the container. If none is specified, a default value is used, depending on the context.

Expressions

The invoke and evaluate commands accept expressions, which can include variables and operators that are evaluated at runtime.

Invoke Expressions

An invoke expression is a template used to generate URL and data values at runtime by replacing the variables specified in the template with their runtime values. Variables can reference one or more selected items, information about the current user, and other system information.

  • Anything enclosed in a brace { } is considered to be a key value that is mapped to the corresponding attribute of a file, folder, or the currently signed-in user. User attributes are prefixed by user.

    For example, if John Smith is the current user, userid={user.name} resolves to this:

    userid=John Smith

  • For multiselection, use the [repeated template separator] syntax. The repeated template is resolved for each selected item, and resolved strings for items are separated 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 for a particular action. The expression can contain zero or more variables that are replaced with their runtime values before the expression is evaluated. This expression must be a valid JavaScript expression after all the values of the variables are replaced with their values at runtime.

The expression must evaluate to true or false. If the result is true, the action is made available as specified by the trigger property. If the result is false, the action is not made available to the user.

For example, the following expression returns a true value only if all three conditions evaluate to true: the item selected in the interface is a file, the user is signed in (not accessing 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 property group field name>.

Some commonly used JavaScript comparison and logical operators follow.

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

Variables

You can use variables in applications to dynamically provide information about the current 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 the relationship explicit, especially in cases where variable names are the same, such as name. 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 user name, use user.name. If you specify name without the category, then item.name (the folder 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 by the user. Folder and file variables belong to the item category. The following table lists variables that apply to both folder and file items.

Folder or File Variable 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

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, if appLinkRole was specified in the invoke command

The appLink object has id, url, and accessToken properties that can 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 file items 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 permissions associated with an item. The properties return a Boolean value.

Permission Properties 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.

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 a link.

linkShareRead

User has read permission for the item shared with the user through a link.

linkShareUpdate

User has update permission for the item shared with the user through a link.

linkShareWrite

User has write permission for the item shared with the user through a link.

Item State

State is a JSON object that you can query to determine certain states of an item. The properties 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

ismember

Returns true if the user is not accessing an item through public link or app link and false otherwise

ispubliclink

Returns true if the user is accessing the item through a public link and false otherwise

isapplink

Returns true if the user is accessing the item through an applink and false otherwise

role

Current user's role for an item

hasprivilegesas

Specified with a user role as a string argument to determine if the user has the specified role

API Functions

Use the following utility functions with evaluate or invoke expressions to return information about a specified item.

Variable Description

isReservedByAnotherUser(item)

Returns true if the item is reserved by another user, or returns false otherwise

hasPrivilegesAs(item, role)

Returns true if the user has role privileges for the item, or returns false otherwise

getUserRole(item)

Returns the user’s role for the item

Localization

Use the stringsMap element to provide localized versions of labels and descriptions used in the integration.

The following example shows sample application and action names and descriptions in 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"
		}