FreeMarker model reference

1. Introduction

This part of the book contains API references for various APIs you may want to use while developing an application using iKnowBase.

Every component which supports FreeMarker templates has its own section in this chapter, with a separate chapter for shared model object at the end.

1.1. Understanding the notation

For every component, there are two pieces of information:

  • The first table inside the chapter describes the objects made available to the FreeMarker template. For each object there is a short description, as well as information about the type of the model object.

  • Subsequent tables describe the properties of each model object type. For each property there is a short description, as well as information about the type of the property.

Often, there is a reference to a property named <default>. This is the value returned from the model object when no property is specified.

Also, there are often references to a property named <name>. These refer to a "generic" notation, where you can use any name. This name is then typically used to look up information for an object of that name.

1.2. Wrapped objects

Some of the models may refer to wrapped object properties, with reference to a java class. In those situations, the properties of that model object will be defined by the java class directly, through the use of FreeMarker’s BeanModel. For detailed information, see the FreeMarker documentation of the BeansModel class.

2. Global objects

Certain model objects are always available when running inside an iKnowBase-managed template:

context

This object contains information about the execution context.

ObjectReferenceModel

iknowbase

A reference to the iKnowBase repository

[RepositoryModel]

userdata

An (initially) empty map used for passing data between chained templates in a template set

Map

When running in a web settings, where there is in fact an underlying HTTP servlet, the following objects are also available:

httpServletRequest

Provides access to the underlying HttpServletRequest

HttpServletRequest

httpServletResponse

Provides access to the underlying HttpServletResponse

HttpServletResponse

encodeURL

Function that encodes URL, in particular to optimize access to static resources

encodeURL

When using the Presentation Services' Form Processor (typically in a plugin), the following objects are also available

form

Default reference name for accessing the Form Processor’s "form" model.

FormModel

3. Generic models

These models are used across components and portlets.

3.1. ObjectReferenceModel

This object contains a single reference to an external object (value list, dimension, etc).

Property Description Type

label

The label value of the reference object

String

objectId

The object id of the references object

Number

objectGuid

The object guid of the referenced object

String

externalKey

The external_key specified for the attribute behind the field

String

<default>

When used directly, this object evaluates to the "label" property.

String

3.2. UserReferenceModel

This object contains a single reference to a user

Property Description Type

label

The label value of the reference object

String

objectId

The object id of the references object

Number

objectGuid

The object guid of the referenced object

String

externalKey

The external_key specified for the attribute behind the field

String

<default>

When used directly, this object evaluates to the "label" property.

String

3.3. ComponentModel

This object contains information about the currently execution component (the ContentViewer).

Property Description Type

id

Name of the component as it is known on the client side (in the web browser). Use this for ajax-based api calls on the component.

String

Example:

function refreshThisComponent() {
   iKnowBase.PageEngine.reloadComponent ('${component.id}');
}

3.4. ContextModel

The ContextModel-object contains general information related to an execution context. Use this object to find information about current time and current user.

Example:

<p>
This information was last refreshed on ${context.datetime}
</p>
Property Description Type

user

Information about the executing user, either a logged on user or the guest user applicable to the request

UserModel

domain

Information about the domain applicable to the request

DomainModel

date

Current date

Date

time

Current time

Time

datetime

Current date and time

Datetime

millis

Number of milliseconds since 1.1.1970

Number

request

Information about the current request

RequestModel

language

iKnowBase language code for the current context.

String

isDevelopmentMode

Flag indicating whether development mode is enabled or not

Boolean

isServeExpandedResources

Flag indicating whether resources should be served expanded (without compression)

Boolean

commonScripts

HTML for resources to generate in <head> of HTML-page

String

3.5. UserModel

The UserModel-object contains information about the executing user, either a logged on user or the guest user applicable to the request.

Property Description Type

isLoggedOn

Whether the current user is logged on, or is a public user

Number

isAdmin

Whether the current user has administrator access

Number

id

Numeric user id for the user

Number

username

Username (loginname) for the user

String

token

UserToken for secure authentication without logging in, for ajax-based processing.

UserTokenModel

socialAuthentication

Information regarding the active OAuth2 user authentication (if used).

UserTokenModel

3.6. UserTokenModel

The UserTokenModel-object contains a token for secure authentication without logging in, for ajax-based processing.

Property Description Type

name

Name of the URL-parameter for the token

String

value

Token value

String

3.7. SocialAuthenticationModel

The SocialAuthenticationModel-object contains information regarding the users profile from the external OAuth2 identity provider. Only applicable if OAuth2 is used for authentication.

Property Description Type

providerId

The id of the provider the connection is associated with.

String

attributes

A map of the available OAuth2 attributes from the provider.

Map

3.8. DomainModel

The DomainModel-object contains information about the domain applicable to the current request.

Property Description Type

objectId

The object ID of the domain

Number

objectGuid

The object guid of the domain

String

label

The label of the domain

String

name

The name of the domain, typically HOST.PORT

String

ikbViewerPath

The path to the ikbViewer module, without a trailing slash

String

pageEnginePath

The path to the page engine, without a trailing slash/ikbViewer

String

contentServerPath

The path to the content server, without a trailing slash

String

resourcePath

The path to the resource directory, without a trailing slash

String

ikbStudioPath

The path to the development studio, without a trailing slash

String

3.9. RequestModel

This object contains parameters available to the component.

Property Description Type

pageurl

URL for the page currently running.

String

servername

Name of server where the viewer is running (part of pageurl)

String

serverport

Port number of server where the viewer is running (part of pageurl)

String

parameters

Parameters sent to the request.

ParametersModel

<name>

Value of URL-parameter (shortcut to parameter.name).

String

The properties username, referencepath and guid were earlier available in this model. They have been deprecated.

3.10. ParametersModel

This object contains information about request parameters from the current HTTP-request. The model supports several of the basic FreeMarker model types:

  • It is a TemplateHashModel, supporting one property per parameter

  • It is a TemplateHashModelEx, supporting the built-ins ?keys and ?values.

  • It is a ScalarModel, returning a single String with all parameter names and values for debug purposes

Property Description Type

<name>

Value of URL-parameter (shortcut to parameter.name).

ParameterModel, String

3.11. ParameterModel

This model contains all values for a given parameter. The model supports several of the basic FreeMarker model types:

  • It is a String (ScalarModel), returning the first (or only) value for the parameter

  • It is a TemplateSequenceModel containing Strings, supporting index-based lookups (context.request.parameters.paramname[index]) and iteration ([#list context.request.parameters.paramname as param]…​[/#list]).

3.12. TextMapModel

This model object contains language specific texts defined with various iKnowBase objects. The model object is a compound object. First is the actual TextMapModel, which enables you to find a TextString based on a user defined key. Next is the TextStringModel, which decides which definition of the string to use, for example the one stored with a Page or the one stored with a Template.

You may use only the TextMapModel object (as in ${viewer.strings.contactEmail}), which will then search for the string in any of the available locations. You may also specify the location "any" for the same purpose (as in ${viewer.strings.contactEmail.any}). If you want complete control of the string location, specify it directly (as in ${viewer.strings.contactEmail.template}).

The locations available vary from portlet to portlet. See the definition of the portlet object for description of which locations apply to that portlet.

3.12.1. TextMapModel

Property Description Type

<name>

Text string definition.

TextStringModel

3.12.2. TextStringModel

Property Description Type

page

The value of the text with the given name, as specified on the page.

String

template

The value of the text with the given name, as specified on the template.

String

style

The value of the text with the given name, as specified on the presentation style.

String

viewer

The value of the text with the given name, as specified on the viewer.

String

domain

The value of the text with the given name, as specified on the domain.

String

any

Return any string, from any of the available locations (properties).

String

<default>

Value from one of style, viewer and domain, if present; otherwise null.

String

Examples:

<!-- The text specified in the "contactEmail" string, in any available location. -->
${viewer.strings.contactEmail}
<!-- The text specified in the "contactEmail" string, in any available location. -->
${viewer.strings.contactEmail.any}
<!-- The text specified in the "contactEmail" string, on the template only -->
${viewer.strings.contactEmail.template}
<!-- The freemarker default value operator does not work without a location -->
${viewer.strings.contactEmail!"default-email`example.com"}
<!-- The freemarker default value operator works only when specifying a location -->
${viewer.strings.contactEmail.any!"default-email`example.com"}
${viewer.strings.contactEmail.template!"default-email`example.com"}

3.13. LoadXML macro

Use this macro to load XML from a specified URL, for further processing using FreeMarker.

Parameter Description Type

name

Name of variable you want to create, where the XML will be loaded into

String

url

URL where the specified XML resides

String

timeout

Optional timeout in milliseconds. If no timeout is specified, a default value of 60 seconds will be used.. The timeout applies to each of the connect and read phases independently.

Number

Examples:

<@ikb.loadXML 'myxml' 'http://www.example.com/xmlfeed' />
<#list ikb.myxml.entries as entry>
    ${entry.title}
</#list>
<@ikb.loadXML 'myxml' 'http://www.example.com/xmlfeed' 2000 />
<#if ikb.myxml! == "">
   No data was returned; possibly timeout
</#if>

3.14. LoadURL macro

Use this macro to load arbitrary text from a specified URL, for further processing using FreeMarker.

Parameter Description Type

name

Name of variable you want to create, where the content will be loaded into.

String

url

URL where the specified content resides.

String

timeout

Optional timeout in milliseconds. The timeout applies to each of the connect and read phases independently. Default is 60 seconds.

Number

maxsize

Optional max content size, in bytes. Default is 65536 (64KiB).

Number

Example:

<@ikb.loadURL 'myurl' 'http://my.domain.com/htmlfeed '/>
<div>
    ${ikb.myurl}
</div>

3.15. AssignDate macro

Use this macro for simple date arithmetic, where you start with a certain date and then add a duration.

Parameter Description Type

name

Name of variable you want to create, where the content will be loaded into

String

base

Base date

Datetime

increment

Increment in milliseconds

Number

Example:

<@ikb.assignDate 'dueWarning' viewer.logic.currentDate 259200000 />
<div>
    ${ikb.dueWarning}
</div>

3.16. encodeURL

The function encodeURL will encode an URL, if required, in particular to optimize access to static resources.

For a default iKnowBase installation, it will encode references to static resources (such as /ressurs/iknowbase/css/iknowbase.css), for much better front-end caching. If the URL does not refer to a known resource, the URL is returned unchanged.

Note
 The returned URL will change if the content of the resource changes. The function should not be used if the output URL is expected to be bookmarked or otherwise stored

The function is a FreeMarker-specific shortcut to the standard function HttpServletRequest.encodeURL from the servlet API. For other template languages, you may call that function directly.

Example:

Encoded:     ${encodeURL('/ressurs/iknowbase/css/iknowbase.css')}
Not encoded: ${encodeURL('http://dagbladet.no')}

4. Content viewer

4.1. Overview

The figure below gives a quick overview of the models available to the ContentViewer.

  • viewer

    • data

      • isEmpty

      • count

      • lastLevel

      • level/recurse

        • fields

          • <name> (String, Number, Date)

            • text

            • date

            • number

            • externalKey

            • hasValue

            • label

            • style

            • xml

            • url

            • script

            • nodeText

        • documentLevel

        • documentId

        • isFirst

        • isLast

        • isOdd

        • isEven

        • sub

          • data

          • style

  • style

    • fields

      • <name>

        • label

        • isSortActive

        • isSortActiveAscending

        • isSortActiveDescending

        • sortAction

        • sortActionAscending

        • sortActionDescending

        • sortIconActive

        • sortIconAscending

        • sortIconDescending

    • hasQuickLink

    • quickLink

      • text

      • url

      • script

      • nodeText

    • portletTitle

  • logic

    • languageId

    • noRecordsFound

    • currentDate

    • dbExecute

    • hasContainer

  • navigation

    • pageSize

    • firstRow

    • totalRows

    • startRow

    • maxRow

    • lastRow

    • text

    • isEmpty

    • range

    • first

    • previous

    • next

    • last

    • goto

    • showMore

  • param

    • username

    • pageurl

    • referencepath

    • servername

    • serverport

    • guid

    • <name>

  • strings

    • <name>

      • style

      • viewer

      • domain

  • context

    • user

      • id

      • username

      • token

        • name

        • value

    • date

    • time

    • datetime

    • millis

  • request

    • pageurl

    • servername

    • serverport

  • component

    • id

4.2. Global objects

These are the global (top level) objects available when using FreeMarker from a ContentViewer.

Object Description Type

viewer

This object contains information about the viewer, its presentation style and its data.

ViewerModel

context

This object contains information about the execution context.

ObjectReferenceModel

component

This object contains information about the executing component.

ComponentModel

4.3. ViewerModel

This object contains information about the ContentViewer itself, its definition and data.

Property Description Type

data

The full data set of the content viewer.

RowSetModel

style

The presentation style of the content viewer.

StyleModel

logic

Logic information about the content viewer.

LogicModel

navigation

Navigational information about the content viewer.

NavigationModel

param

URL-parameters.

ParameterModel

strings

Available strings for the viewer. This TextMapModel supports locations "style", "viewer" and "domain".

TextMapModel

<default>

When used directly, this object evaluates to the value of the "data" property.

RowSetModel

4.4. RowSetModel

This object contains a set of rows/documents. The top level RowSetModel (as returned from viewer.data) contains all rows/documents returned from the content viewer, whereas RowSetModels accessed differently (for example through row.sub from a specific row) contains only a partial set of documents.

The object is a freemarker sequence model, so you can access the nodes directly using ${data[index]}, or you can traverse it using the [#list]…​[/#list] syntax.

The object is also a freemarker node, so you can also use the built-ins ?children, ?parent, ?root, ?ancestors, ?node_name, ?node_type and ?node_namespace. The ?node_name and ?node_type properties are both "DocumentList".

Property Description Type

isEmpty

A flag indicating whether the content viewer returned any rows. Returns true if the viewer is empty.

Boolean

count

The number of documents on the current level (documentLevel)

Number

lastLevel

The level of the last document available in this data set.

Number

level

A sequence containing only documents on this particular level, e.g. without subdocuments. This is the default, so it can be skipped.

Sequence(Row)

recurse

A sequence containing both documents on this level and all subdocuments.

Sequence(Row)

style

The presentation style of the current level of the ContentViewer.

StyleModel

?children

List of documents

List of RowModel

?parent

There is no parent; it always returns null.

Null

?root

There is no root node; it always returns null.

RowModel

?ancestors

List of ancestors

List of RowModel

?node_namespace

There is no namespace; it always returns null.

Null

?node_type

Always the string "DocumentList"

String

?node_name

Always the string "DocumentList"

String

<default>

When used directly, the rowset object evaluates to a sequence of Row-objects.

Sequence(Row)

<name>

The data field object for a given field. The field name refers to "reference name" from the presentation style definition. The type of the property varies, depending on the data type of the data field.

DataFieldXxx

4.5. RowModel

This model object contains information about a single row / document returned from the viewer.

The model is a freemarker node, so you can also use the built-ins ?children, ?parent, ?root, ?ancestors, ?node_name, ?node_type and ?node_namespace.

Note that part of the information is context sensitive. For example, a document might be the second document in the collection data.viewer.level (and thus have isOdd=false), while also being available as the third document in the collection data.viewer.recurse (and thus have isOdd=true).

Property Description Type

fields

The fields (attributes) from a single row/document in the data set of the ContentViewer.

DataFields

documentLevel

The level of the current document.

Number

documentId

The documentId of the current document.

Number

isOdd

The current document is on an odd row number (1,3,5,…​)

Boolean

isFirst

The current document is the first in the result set.

Boolean

isLast

The current document is the last in the result set.

Boolean

sub

A collection of sub documents from the current document.

RowSetModel

document

The returned document, without attributes

DocumentModel

?children

List of children documents

List of RowModel

?parent

Parent node

RowModel

?root

Root node

RowModel

?ancestors

List of ancestors

List of RowModel

?node_namespace

There is no namespace; it always returns null.

Null

?node_type

Always the string "Document"

String

?node_name

Always the string "Document"

String

<default>

When used directly, this object evaluates to the "fields" property.

<name>

The data field object for a given field. The field name refers to "reference name" from the presentation style definition. The type of the property varies, depending on the data type of the data field.

DataFieldXxx

4.6. DocumentModel

This object represents an iKnowBase document. The structure of the DocumentModel is more or less the same as the "Document" object in the ServiceAPI.

Note that this model may not be fully populated. In particular, the various ObjectReferences will probably only contain an id or a guid, and the list of attributes is often not present.

Property Description Type

documentReference

Document identity, with id, guid and externalKey

ObjectReferenceModel

title

Document title (same as documentReference.label)

ObjectReferenceModel

description

Document description (ingress)

String

aclReference

Reference to acl

ObjectReferenceModel

documentTypeReference

Reference to document type

ObjectReferenceModel

ownerReference

Reference to document owner

UserReferenceModel

parentReference

Reference to parent document

ObjectReferenceModel

statusReference

Reference to document status

ObjectReferenceModel

content

Document content, if loaded

ContentModel

validity

Document validity

ValidityModel

auditInformation

Document audit information

AuditInformationModel

validFrom

"Valid from" attribute of document

Date

validTo

"Valid to" attribute of document

Date

created

Created-time of document

Date

createdBy

Reference to user who created document (same as owner)

Date

updated

Updated-time of document

Date

updatedBy

Reference to user who made last update to document

Date

filename

Filename of document content, if it is a file

String

url

URL stored on document, if it is an URL

String

isFile

Indicates whether the document content is a file

Boolean

isUrl

Indicates whether the document content is an URL

Boolean

isText

Indicates whether the document content is text (plain or html)

Boolean

isXml

Indicates whether the document content is XML

Boolean

4.7. ContentModel

Property Description Type

filename

Filename of stored content

String

url

Stored URL

String

textContent

Stored text content

String

xmlContent

Stored XML-content

org.w3c.Element

4.8. ValidityModel

Property Description Type

from

Datetime document is valid from

Datetime

to

Datetime document is valid to

Datetime

4.9. AuditInformationModel

Property Description Type

timestamp

Datetime of any document change

Datetime

created.user

Reference to user who created document

UserReferenceModel

created.date

Datetime document was created

Datetime

updated.user

Reference to user who updated document

UserReferenceModel

updated.date

Datetime document was updated

Datetime

4.10. DataFields

This object is a FreeMarker "hash" container containing the data fields for a given document in the ContentViewer. The object can be accessed by field name, as defined in the presentation style defintion.

Property Description Type

<name>

The data field object for a given field. The field name refers to "reference name" from the presentation style definition. The type of the property varies, depending on the data type of the data field.

DataFieldXxx.

4.11. DataFieldString

This object contains the data field of type String.

Property Description Type

char

The unformatted string value of the field.

String

html

The formatted html value of the field.

String

text

The formatted html value of the field (deprecated for ".html")

String

label

The label value of the field

String

attribute

The attribute behind the field, or null if there is no attribute

AttributeModel

externalKey

(Deprecated, use attribute.externalKey)

String

hasValue

A boolean indicating whether the value is specified and not blank.

Boolean

style

The style specification for this particular data field.

Style

xml

For non-system attributes, return the string value as a parsed XML Node object.

XML

url

For system attributes that represent a link, this returns the value of the "href" attribute of the <a>-tag.

String

onclick

For system attributes that represent a link, this returns a javascript-statement that can be used to follow the link. The onclick event must be attached to an <a>-tag, since the returned statement refers to the containing <a>-tag.

String

script

This property is deprecated; use the onclick-property instead.

String

nodeText

(Deprecated) For system attributes that return a link, this returns the text elements inside the <a>-tag.

String

nodeValue

(Deprecated) For system attributes that return a link, this returns the text elements inside the <a>-tag.

String

<default>

When used directly, this object evaluates to the "html" property.

String

4.12. DataFieldNumber

This object contains the data field of type Number.

Property Description Type

number

The number value of the field.

Number

char

The unformatted string value of the field.

String

html

The formatted html value of the field.

String

text

The formatted html value of the field (deprecated for ".html")

String

label

The label value of the field

String

attribute

The attribute behind the field, or null if there is no attribute

AttributeModel

externalKey

(Deprecated, use attribute.externalKey)

String

hasValue

A boolean indicating whether the value is specified and not blank.

Boolean

style

The style specification for this particular data field.

StyleModel

<default>

When used directly, this object evaluates to the "number" property.

Number

4.13. DataFieldDate

This object contains the data field of type Number.

Property Description Type

date

The date value of the field.

Date

char

The unformatted string value of the field.

String

html

The formatted html value of the field.

String

text

The formatted html value of the field (deprecated for ".html")

String

label

The label value of the field

String

attribute

The attribute behind the field, or null if there is no attribute

AttributeModel

externalKey

The external_key specified for the attribute behind the field

String

hasValue

A boolean indicating whether the value is specified and not blank.

Boolean

style

The style specification for this particular data field.

StyleModel

<default>

When used directly, this object evaluates to the "date" property.

Date

4.14. DataFieldClob

This object contains the data field of type Clob.

Property Description Type

char

The unformatted string value of the field.

String

html

The formatted html value of the field.

String

text

The formatted html value of the field (deprecated for ".html")

String

label

The label value of the field

String

attribute

The attribute behind the field, or null if there is no attribute

AttributeModel

externalKey

The external_key specified for the attribute behind the field

String

hasValue

A boolean indicating whether the value is specified and not blank.

Boolean

style

The style specification for this particular data field.

Style

<default>

When used directly, this object evaluates to the "html" property.

String

4.15. DataFieldFiles

This object contains the data field of type Files, e.g. where the value is one or more files. This is of course used for attachments, but also for derived image formats (such as thumbnails) for image documents.

Property Description Type

char

The unformatted string value of the field.

String

html

The formatted html value of the field.

String

text

The formatted html value of the field (deprecated for ".html")

String

label

The label value of the field

String

attribute

The attribute behind the field, or null if there is no attribute

AttributeModel

externalKey

The external_key specified for the attribute behind the field

String

hasValue

A boolean indicating whether the value is specified and not blank.

Boolean

style

The style specification for this particular data field.

Style

…​

Any other property maps to the same property on the first File, so that ${file.xxxx} maps to {file[0].xxx}

…​

[]

This object is a sequence of DataFieldReference objects.

DataFieldReference

<default>

When used directly, this object evaluates to the "html" property.

String

4.16. DataFieldFile

This object represents a File value.

Property Description Type

url

The URL of the file content

String

mimetype

The mimetype of the file, if known

String

filename

The filename of the file, if known

String

4.17. DataFieldReference

This object contains an ObjectReference, e.g. a reference to an object in the iKnowBase repository. Exactly what is being pointed to cannot be found from this object; this must be derived from the context (such as the containing attribute): A value list attribute would contain a reference to a value list, while a dimension attribute would contain a reference to a dimension.

Property Description Type

label

The label value of the reference

String

objectId

The ID of the reference

Number

objectGuid

The guid of the reference

String

externalKey

The external key of the reference

String

4.18. DataFieldReferences

This object contains the data field of type References, e.g. where the value is one or more references to external objects (value lists, dimensions, etc).

Property Description Type

char

The unformatted string value of the field.

String

html

The formatted html value of the field.

String

text

The formatted html value of the field (deprecated for ".html")

String

label

The label value of the field

String

attribute

The attribute behind the field, or null if there is no attribute

AttributeModel

externalKey

The external_key specified for the attribute behind the field

String

hasValue

A boolean indicating whether the value is specified and not blank.

Boolean

style

The style specification for this particular data field.

Style

…​

Any other property maps to the same property on the first reference

…​

[]

This object is a sequence of DataFieldReference objects.

DataFieldReference

<default>

When used directly, this object evaluates to the "html" property.

String

4.19. DataFieldAction

This object represents a single action, typically represented as a HTML <a>-tag.

Property Description Type

label

The label value of the action

String

url

The URL of the action, used as the "href" attribute of the <a>-tag.

String

onclick

The value of the "onclick" attribute of the <a>-tag.

String

script

The value of the "onclick" attribute of the <a>-tag.

String

4.20. DataFieldUserAction

This object is an extension of the DataFieldAction-object, and represents an action that applies to a specific user. In addition to the action information in the DataFieldAction-object, you can also find information about the referred user:

Property Description Type

label

The label value of the action

String

url

The URL of the action, used as the "href" attribute of the <a>-tag.

String

onclick

The value of the "onclick" attribute of the <a>-tag.

String

script

The value of the "onclick" attribute of the <a>-tag.

String

reference

The user referenced by this action

UserReferenceModel

4.21. DataFieldObjectAction

This object is an extension of the DataFieldAction-object, and represents an action that applies to a specific object. In addition to the action information in the DataFieldAction-object, you can also find information about the referred object; the type of the object should be apparent from the type of the field:

Property Description Type

label

The label value of the action

String

url

The URL of the action, used as the "href" attribute of the <a>-tag.

String

onclick

The value of the "onclick" attribute of the <a>-tag.

String

script

The value of the "onclick" attribute of the <a>-tag.

String

reference

The object referenced by this action

ObjectReferenceModel

4.22. DataFieldDocumentAction

This object is an extension of the DataFieldAction-object, and represents an action that applies to a specific document. In addition to the action information in the DataFieldAction-object, you can also find information about the referred object:

Property Description Type

label

The label value of the action

String

url

The URL of the action, used as the "href" attribute of the <a>-tag.

String

onclick

The value of the "onclick" attribute of the <a>-tag.

String

script

The value of the "onclick" attribute of the <a>-tag.

String

reference

The document referenced by this action

DocumentReference

4.23. DataFieldActions

This object is used for data fields that represent multiple actions, for example when retrieving document and image links.

Property Description Type

char

The unformatted string value of the field.

String

html

The formatted html value of the field.

String

text

The formatted html value of the field (deprecated for ".html")

String

label

The label value of the field

String

attribute

The attribute behind the field, or null if there is no attribute

AttributeModel

externalKey

The external_key specified for the attribute behind the field

String

hasValue

A boolean indicating whether the value is specified and not blank.

Boolean

style

The style specification for this particular data field.

Style

[]

This object is a sequence of DataFieldAction objects.

DataFieldAction, DataFieldUserAction, DataFieldObjectAction or DataFieldDocumentAction

<default>

When used directly, this object evaluates to the "html" property.

String

Note that the Actions (plural) object typically will return HTML corresponding to all of the linked objects, while you can access each individual link through the sequence operator. Also, detailed information about the referenced object (such as the object label / document title) is only available by referencing the individual objects.

4.24. AttributeModel

This object contains information about a defined attribute. Most DataField model objects have a reference to an AttributeModel object.

Property Description Type

objectId

The ID of the attribute

Number

objectGuid

The guid of the attribute

String

level

The level of the attribute

Number

label

The text of the attribute

String

name

The name of the attribute

String

datatype

The data of the attribute, as defined in the iKnowBase ServiceAPI. (DATE, NUMBER, CHAR, CLOB, DIMENSION, VALUELIST, DOCUMENT_LINK, PICTURE_LINK, EXTERNAL, DOCUMENT_FIELD or FILE).

String

4.25. StyleModel

This object contains the presentation style definition for a ContentViewer, or for a specific level inside the Content Viewer.

Property Description Type

fields

The fields defined inside a presentation style

StyleFields

hasQuickLink

A boolean indicating whether there are quicklinks

Boolean

quickLink

A list of quicklinks

List(QuickLinkModel)

portletTitle

The title of the portlet

String

<default>

When used directly, this object evaluates to the "fields" property.

<name>

The StyleField object for a given field. The field name refers to the "reference name" from the presentation style definition.

StyleField

4.26. QuickLinkModel

This object represents a quick link, as defined in a ContentViewer.

Property Description Type

text

The full html value of the quicklink, e.g. the full <a>-tag including attributes and content.

String

label

The label value of the field

String

url

The URL to the quick link target

String

onclick

The value of the "onclick" attribute of the <a>-tag.

String

script

The value of the "onclick" attribute of the <a>-tag.

String

nodeText

(Deprecated) The text elements inside the <a>-tag.

String

nodeValue

(Deprecated) The text elements inside the <a>-tag.

String

4.27. StyleFields

This object is a FreeMarker "hash" container containing the field specifications for a given presentation style. The object can be accessed by field name, as defined in the presentation style defintion.

Property

Description

Type

<name>

The style field object for a given field. The field name refers to "reference name" from the presentation style definition. Note that the StyleField may also be reached through the "style" property on the DataField objects.

StyleField

4.28. StyleField

This object contains the properties defined on a single field in a presentation style.

The term "next sorting" is used to indicate that the property adapts to current state: If the field is not sorted, it returns a value suitable for ascending sort; if the field already has ascending sort, it returns a value suitable for descending sort; finally, if it already has descending sort, it returns a value suitable for ascending sort.

Property Description Type

label

The label value of the presentation style field.

String

externalKey

The external_key specified for the attribute behind the field.

String

isSortActive

Indicator to whether any sort is active for the field

Boolean

isSortActiveAscending

Indicator to whether ascending sort is active for the field

Boolean

isSortActiveDescending

Indicator to whether descending sort is active for the field

Boolean

sortAction

A clickable action for "next sorting".

HtmlLink

sortActionAscending

A clickable action for ascending sorting

HtmlLink

sortActionDescending

A clickable action for descending sorting

HtmlLink

sortIconActive

HTML image tag displaying icon for currently active sort, if any.

String

sortIconAscending

HTLM image tag displaying either active or passive icon for ascending sort.

String

sortIconDescending

HTLM image tag displaying either active or passive icon for descending sort.

String

sortLabel

Deprecated, use "sortAction" instead.

HtmlLink

sortIconAsc

Deprecated, use "sortIconAscending" instead.

String

sortIconDesc

Deprecated, use "sortIconDescending" instead.

String

4.29. LogicModel

This object contains the set of fields defined in the presentation style

Property Description Type

languageId

The languageId of the viewer.

String

noRecordsFound

The text to display if the viewer does not return any rows.

String

currentDate

Deprecated; use top level ContextModel instead (${context.date}).

Date

dbExecute

Directive that runs a plsql-block and returns the returned HTP-content.

String

hasContainer

Whether the viewer renders an ajax-capable html container

Boolean

Example:

[@viewer.logic.dbExecute]
BEGIN
    HTP.prn ('<div>');
    HTP.prn ('You are currently connect to instance number ' || DBMS_UTILITY.CURRENT_INSTANCE);
    HTP.prn ('</div>');
END;
[/@viewer.logic.dbExecute]

This object contains information supporting navigation in the viewer.

Property Description Type

pageSize

The number of rows defined to show on each page.

Number

firstRow

Index of the first row.

Number

lastRow

Index of the last row in the current data set (current page).

Number

totalRows

Total number of rows available to the viewer, even after navigation, if available.

Number

startRow

The first row requested (even though it may not actually exist).

Number

maxRow

Max number of rows to return by the viewer.

Number

isEmpty

True if there is no navigation bar.

Boolean

text

HTML of the entire navigation bar

String

range

The current navigation range (#-# of #)

String

first

Link to the first page of the viewer

NavigationLink

previous

Link to the previous page of the viewer

NavigationLink

next

Link to the next page of the viewer

NavigationLink

last

Link to the last page of the viewer

NavigationLink

goto

One or more links to specific row numbers

GotoModel

showMore

A link to the "show more" target defined for the viewer.

HtmlLink

moreLink

This property is deprecated; use "showMore" instead.

String

4.31. GotoModel

This object is a method model that lets you generate links to specific row numbers. As the object is a method, you call it using a method syntax as shown below.

Signature Description Type

goto (start)

Link to single page

NavigationLink

goto (start, pagesize)

Link to single page with page size

NavigationLink

goto (start, interval, count)

List of links

List (NavigationLink)

4.31.1. Link to single page

To generate a simple link, use the syntax with a single argument:

Argument Description Type

start

Row number to generate link to

Number

 
<!-- To generate a single link to row number 50 -->
${viewer.navigation.goto(50)}

4.31.2. Link to single page with page size

To generate a link that both navigates to a specific row and sets the page size, use the syntax with two arguments:

Argument Description Type

start

Row number to generate link to

Number

pagesize

Number of rows per page

Number

 
<!-- To generate a single link to row number 50, with a pagseize of 25 -->
${viewer.navigation.goto(50, 25)}

To generate a list of links, use the syntax with three arguments. The method will return a list of links, useful for generating navigating bars with many links, for many pages:

Argument Description Type

start

Row number to generate link to

Number

interval

Interval between links

Number

count

Number of links to generate

Number

The list method will not return any illegal links. If you request goto(50,10,10), you are asking for 10 links to rows 50, 60, 70 …​ 140. However, the method will not return links beyond the last record, so if the viewer has only 65 records, you would get two links only, to rows 50 and 60.

The list method will also allow you to generate links "backwards", using a negative interval. goto(50,-10,10) will generate ten links 10 record intervals, up to row 50. Since it will not generate illegal links, this will in fact return five links: 10,20,30,40 and 50.

<!-- To generate five links before "this row", then "this row", then five links after -->
[#list viewer.navigation.goto(viewer.navigation.firstRow-10, -10, 5) as link]${link}[/#list]
${viewer.navigation.goto(viewer.navigation.firstRow)}
[#list viewer.navigation.goto(viewer.navigation.firstRow+10, +10, 5) as link]${link}[/#list]

This object represents a single html link.

When used directly, the HtmlLink returns a string with the full link (<a>…​</a>);

Property Description Type

label

Localized text to use for the link text

String

url

The URL of the action, used as the "href" attribute of the <a>-tag.

String

onclick

The script to be used for the "onclick" attribute for an <a>-tag

String

script

The script to be used for the "onclick" attribute for an <a>-tag

String

target

The name of the html target (window) for an <a>-tag

String

<default>

The complete link element (<a>…​</a>)

String

This object represents a single navigation link.

When used directly, the NavigationLink returns a string with the full link (<a>…​</a>);

Property Description Type

label

Localized text to use for the link text

String

url

The URL of the action, used as the "href" attribute of the <a>-tag.

String

onclick

The script to be used for the "onclick" attribute for an <a>-tag

String

startRow

The first row to be displayed if the link is followed.

String

isValid

A value indicating whether a link is valid or not.

Boolean

<default>

The complete link element (<a>…​</a>)

String

An invalid link has a start row outside the legal range. Both previous, next and last can return in invalid links, for example if you try to refer to the "previous" value when already on the first page. An invalid link has startRow set to null, url and onclick set to null, while the label contains the proper value.

5. Content search

The Content Search freemarker model is an extension of the Content Viewer, with an extra object available inside the ViewerModel.

5.1. Global objects

These are the global (top level) objects available when using FreeMarker from a Search Viewer.

Object Description Type

viewer

This object contains information about the viewer, its presentation style and its data.

ViewerModel

context

This object contains information about the execution context.

ObjectReferenceModel

component

This object contains information about the executing component.

ComponentModel

5.2. ViewerModel

This object contains information about the Search Viewer itself, its definition and data. With the exception of the "search" property, all the others are documented along with the Content Viewer models.

Property Description Type

data

The data set of the content viewer.

DataModel

style

The presentation style of the content viewer.

StyleModel

logic

Logic information about the content viewer.

LogicModel

navigation

Navigational information about the content viewer.

NavigationModel

param

URL-parameters

ParameterModel

strings

Available strings for the viewer. This TextMapModel supports locations "style", "viewer" and "domain".

TextMapModel

search

Available search model information

SearchModel

<default>

When used directly, this object evaluates to the value of the "data" property.

5.3. SearchModel

This object contains information about the Search Viewer itself, its definition and data.

Property Description Type

form

The search form, as HTML

String

term

The search term, as a string

String

6. XML viewer

6.1. Overview

The figure below gives a quick overview of the models available to the XMLViewer.

  • xmlviewer

  • xmlurl

  • param

    • username

    • pageurl

    • referencepath

    • servername

    • serverport

    • guid

    • <name>

  • context

    • user

      • id

      • username

      • token

        • name

        • value

    • date

    • time

    • datetime

    • millis

6.2. Global objects

These are the global (top level) objects available when using FreeMarker from a XMLViewer.

Object Description Type

xmlviewer

This object contains the loaded XML

XML

xmlurl

This object contains the URL that the XMl was loaded from

String

param

URL-parameters

ParameterModel

context

This object contains information about the execution context.

ObjectReferenceModel

viewer

This property contains information about the viewer.

ViewerModel

6.3. ViewerModel

This object contains information about the XMLViewer.

Property Description Type

strings

Available strings for the viewer. This TextMapModel supports locations "template" and "domain".

TextMapModel

7. Dimension viewer

7.1. Overview

The figure below gives a quick overview of the models available when rendering a Dimension Viewer using a template.

7.2. Global objects

These are the global (top level) objects available when using FreeMarker in a Dimension Viewer.

Object Description Type

component

This object contains information about the executing component.

ComponentModel

context

This property contains information about the execution context.

ObjectReferenceModel

nodes

This property contains the top level nodes in the viewer.

DimensionListModel

viewer

This property contains information about the viewer.

ViewerModel

7.3. ViewerModel

This object contains information about the DimensionViewer.

Property Description Type

strings

Available strings for the viewer. This TextMapModel supports locations "template" and "domain".

TextMapModel

7.4. DimensionListModel

This object contains the top level nodes in the viewer, and is really just a collection of DimensionModel objects.

The object is a freemarker sequence model, so you can access the nodes directly using ${nodes[index]}, or you can traverse it using the [#list]…​[/#list] syntax.

The object is also a freemarker node, so you can also use the built-ins ?children, ?parent, ?root, ?ancestors, ?node_name, ?node_type and ?node_namespace. The ?node_name and ?node_type properties are both DimensionList.

7.5. DimensionModel

This object contains information about a single dimension item.

The object is a freemarker node, so you can also use the built-ins ?children, ?parent, ?root, ?ancestors, ?node_name, ?node_type and ?node_namespace.

Property Description Type

objectId

The object ID of the node

Number

objectGuid

The object guid of the node

String

level

The level of the node

Number

label

The text of the node

String

isActive

An indicator of whether this node is the "active" one.

Boolean

hasActiveChild

An indicator of whether a sub-node of this one is the "active" one.

Boolean

url

The url of the menu item destination, typically used in the href-attribute of an <a>-tag.

String

action

The action specification for the dimension

DimensionActionModel

dimensionTypes

List of dimensions types applicable to this node

List of ObjectReferenceModel

?children

List of children nodes

List of DimensionModel

?parent

Parent node

DimensionModel

?root

Root node

DimensionModel

?ancestors

List of ancestors

List of DimensionModel

?node_namespace

There is no namespace; it always returns null.

Null

?node_type

Always the string "Dimension"

String

?node_name

Always the string "Dimension"

String

7.6. DimensionActionModel

This object contains information about a single dimension action, typically a URL link.

Property Description Type

label

The label value of the action

String

url

The URL of the action, used as the "href" attribute of the <a>-tag.

String

onclick

The value of the "onclick" attribute of the <a>-tag.

String

script

The value of the "onclick" attribute of the <a>-tag.

String

<default>

Formatted <a>-tag representing the action.

(Any)

8.1. Overview

The figure below gives a quick overview of the models available when rendering a Menu Viewer using a template.

8.2. Global objects

These are the global (top level) objects available when using FreeMarker with a menu viewer.

Object Description Type

component

This object contains information about the executing component.

ComponentModel

context

This property contains information about the execution context.

ObjectReferenceModel

nodes

This property contains the top level nodes in the viewer.

MenuItemListModel

viewer

This property contains information about the viewer.

ViewerModel

This object contains information about the MenuViewer.

Property Description Type

portletTitle

The title of the portlet

String

strings

Available strings for the viewer. This TextMapModel supports locations "template" and "domain".

TextMapModel

This object contains the top level nodes in the viewer, and is really just a collection of MenuItem objects.

The object is a freemarker sequence model, so you can access the nodes directly using ${nodes[index]}, or you can traverse it using the [#list]…​[/#list] syntax.

The object is also a freemarker node, so you can also use the built-ins ?children, ?parent, ?root, ?ancestors, ?node_name, ?node_type and ?node_namespace. The ?node_name and ?node_type properties are both "MenuItemList".

This object contains information about a single menu item.

The object is a freemarker node, so you can also use the built-ins ?children, ?parent, ?root, ?ancestors, ?node_name, ?node_type and ?node_namespace.

Property Description Type

objectId

The ID of the node

Number

objectGuid

The guid of the node

String

level

The level of the node

Number

label

The text of the node

String

isActive

An indicator of whether this node is the "active" one.

Boolean

hasActiveChild

An indicator of whether a sub-node of this one is the "active" one.

Boolean

url

The url of the menu item destination, typically used in the href-attribute of an <a>-tag.

String

action

The action specification for the menu item

MenuItemActionModel

tooltip

The tooltip text of the menu item

String

cssClass

The text of the css information specified on the menu item

String

image

The name/path of the image specified on the menu item. Often, styling based on cssClass is a better choice.

String

imageRollover

The name/path of the rollover image specified on the menu item. Often, styling based on cssClass is a better choice.

String

isBreadcrumb

An indicator of whether this node is tagged with "breadcrumb"

Boolean

isSitemap

An indicator of whether this node is tagged with "sitemap"

Boolean

?children

List of children nodes

List of MenuItemModel

?parent

Parent node

MenuItemModel

?root

Root node

MenuItemModel

?ancestors

List of ancestors

List of MenuItemModel

?node_namespace

There is no namespace; it always returns null.

Null

?node_type

Always the string "MenuItem"

String

?node_name

Always the string "MenuItem"

String

This object contains information about a single menu item action, typically a URL link.

Property Description Type

label

The label value of the action

String

url

The URL of the action, used as the "href" attribute of the <a>-tag.

String

onclick

The value of the "onclick" attribute of the <a>-tag.

String

script

The value of the "onclick" attribute of the <a>-tag.

String

<default>

Formatted <a>-tag representing the action.

(Any)

9. Template Viewer

9.1. Overview

The figure below gives a quick overview of the models available when rendering a Template Viewer portlet.

9.2. Global objects

These are the global (top level) objects available when using FreeMarker with a HTML Item Viewer.

Object Description Type

component

This object contains information about the executing component.

ComponentModel

context

This property contains information about the execution context.

ObjectReferenceModel

viewer

This property contains information about the viewer.

ViewerModel

9.3. ViewerModel

This object contains information about the TemplateViewer.

Property Description Type

strings

Available strings for the viewer. This TextMapModel supports locations "template" and "domain".

TextMapModel

10. Activiti Form viewer

The Activiti Form viewer is the component used to render forms related to the Activiti process engine, related to either starting new processes or completing manual tasks.

A few nice-to-know items about the Activiti Form viewer:

  • The form object is created the first time it is rendered. On repeated renderings (after submits, etc), the same form object is reused, with all the information intact (even if information is not rendered every time).

  • Form components are "bound" to a data model, where they get their values from and store their values to. However, until a form is submitted or saved, values in the form component are independent from values in the data models.

10.1. Overview

The figure below gives a quick overview of the models available to the Activiti FormViewer:

  • form

    • components

    • currentCommand

    • commonScripts

    • form

    • input

    • label

    • button

    • message

    • row

    • rows

    • debugString

10.2. ActitiviFormModel

This object contains information about the form data and form components, as well as directives used to render the form.

Property Description Type

currentCommand

The current command of this invocation

HashModel

form

Directive used to print the html code for the form

ActitiviFormDirective

input

Directive used to create and render a UI component for the form

ActitiviFormInputDirective

label

Directive used to render a label for a component of the form

ActitiviFormLabelDirective

button

Directive used to render an action button

ActitiviFormButtonDirective

message

Directive used to render a message for a component of the form

ActitiviFormMessageDirective

row

Directive used to render a html row with label and input

[ActitiviFormRowDirective]

rows

Directive used to render html rows for many data elements

[ActitiviFormRowsDirective]

components

Hash with user inteface components of the form

ActitiviFormComponentModel

10.3. ActitiviFormDataModel

This object contains information about a single Activiti FormData object for the form, either a Task form or a Start form, depending on usage.

Property Description Type

type

Type of form data, either "TaskFormData" or "StartFormData"

String

processDefinitionId

ID of activiti process definition

String

processInstanceId

ID of the process instance. For a start form, this has value only after submitting the form.

String

formKey

Form key defined on the activiti form

String

task

Wrapped object of the underlying task. Valid only for Task forms. For detailed information, see the FreeMarker documentation of the Task class

String

items

Map of items, with all values as strings.

HashModel

10.4. ActitiviFormComponentModel

This object, accessible through ${form.components[componentname]} (e.g form.components["task.description"] to access the component named "task.description"), contains information about a single form component. Note that the component models are only available after the component has been created through a form.input reference during the initial rendering; this means that the model is always available after a redisplay of the form (e.g. if validation fails, or if you use a command which does not submit data), but that the first time you display the form, the component does not exist prior to the form.input reference.

Property Description Type

name

Name of the component

String

bindExpression

Bind expression of the component

String

value

Value of the component

(Any)

Example:

<!-- Bind and value will be empty on initial rendering -->
Description: Bind=${form.components["task.description].bindExpression!}: Value=${form.components["task.description].value!}<br />

[@form.form debug="true"]
   ...
   [@form.input name="task.description" /]                  <!-- Creates the component during initial rendering -->
   ...
[/@form.form]

<!-- Bind will not be empty during initial rendering; value might be (depends on Activiti form defintition) -->
Description: Bind=${form.components["task.description].bindExpression!}: Value=${form.components["task.description].value!}<br />

10.5. ActitiviFormDirective

This directive is used to render a <form> html tag. The directive must be closed at the end.

Parameter Description Type

debug

Set to "true" to render debug information at end of form. Optional .

String

Example:

[@form.form debug="true"]
...
[/@form.form]

10.6. ActitiviFormInputDirective

This directive is used to create a form component and render an input field for a data model item. The directive will automatically adapt its defaults according to the underlying data object’s semantics.

Parameter Description Type

name

Name you want to use for component; this will also be the "name" attribute in the html form.

String

bind

Path to object you want to load data from and store data to, such as "task.description". If not present, it will default to the "name" attribute.

String

type

Type of input field, according to table below. Default value will depend on type of the bound object

String

attribute

External key of iKnowbBase attribute used to determine field type

String

<default>

Other parameters are rendered as they are, allowing any html attribute to be used and rendered.

String

The input fields can take many different forms, depending on its type. The type is initially decided from the underlying data field, such that a numeric field will render as a number field. You can also specify a type manually to override this; this is particularly useful when a single field type has many possible renderings (such as a list of values, which can render as select or radio, and sometimes even as a popup).

Type Description

text

Normal text input field

number

Input field of type number

textarea

Normal text area

tinymce

Text area with tinymce editor

date

Text field with date popup and date format

datetime-local

Text field with datetime popup and format

hidden

Hidden input field

checkbox

Check box to toggle a boolean value on or off

radio

Radio list (buttons), with values popuplated from underlying data field

select

Select list (drop down), with values populated from underlying data field.

popup

Popup button, with values populated from underlying data field.

Examples:

<!-- Default input field -->
[@form.input name="task.title" /]
<!-- Text area and tinymce editor -->
[@form.input name="description" bind="task.description" type="textarea" /]
[@form.input name="content"     bind="task.content" type="tinymce" tinymce="small"/]
<!-- Renders a dimension navigator, a drop-down to select dimensions and a user popup to select user, based on attribute definitions -->
[@form.input name="dimNavPopup"  bind="task.organization" attribute="MY_ORG_DIM_ATTRIBUTE" /]
[@form.input name="dimNavSelect" bind="task.brand"        attribute="MY_BRAND_DIM_ATTRIBUTE" /]
[@form.input name="userPopup"    bind="task.manager"      attribute="MY_USER_ATTRIBUTE" /]

10.7. ActitiviFormLabelDirective

This directive is used to render a label for a data model item, using the label defined in the underlying data model. For example, an Activiti Task item will have an attached label that you can render using this directive.

Parameter Description Type

bind

Path to object you want to render label for

String

Example:

[@form.label bind="task.description" /]

10.8. ActitiviFormButtonDirective

This directive is used to render an action button for the form.

Parameter Description Type

name

Name of button to create. Required.

String

action

Action you want the button to perform. Use "submit" to submit form data; leave out to just reload form. Optional.

String

Examples:

<!-- Simple save-action -->
[@form.action name="submit" action="submit"]Complete task[/@form.action]
<!-- Three buttons, typically used on page 3 in a wizard. Use ${form.currentCommand.name} to decide which page to display -->
[@form.action name="page2"]Previous[/@form.action]
[@form.action name="page2"]Next[/@form.action]
[@form.action name="submit" action="submit"]Complete task[/@form.action]

10.9. ActitiviFormMessageDirective

This directive is used to render a message for a component of the form. Messages are typically the result of validation failures (for most input fields), but are also used to store errors occuring during action processing.

Examples:

<!-- A typical scenario rendering a label, an input field and an error message -->
<tr>
<td>[@form.label bind="task.valuelist" /]</td>
<td>[@form.input name="task.valuelist" attribute="SYSTEST_ATTR_VALUELIST" /]</td>
<td>[@form.message for="task.valuelist" class="validationerror" /]</td>
</tr>
<!-- Renders an error message for a "submit" button -->
[@form.action name="submit" action="submit"]Complete task[/@form.action]
[@form.message for="submit" class="validationerror" /]

11. Form Processor Macros

The iKnowBase Presentation Services FormProcessor provides directives used to render form elements in a plugin development environment.

Requirements:

  • Plugin development environment (See Development Guide > KnowBase Development Toolkit for Java).

  • Spring Controller with

    • iKnowBase Presentation Services Form Processor with

      • A backing bean containing properties with iKnowBase AttributeMapping-annotations (the directives are only available for these properties)

      • With explicit registration/enabling of the Plugin form macro

    • FreeMarker view

11.1. Overview

Overview of the available model and directives:

  • form

    • input

    • label

    • bindingFieldErrors

    • message

    • resources

Note
 "form" is the default and recommended name, but you may change it when you register the form macro on the Form Processor. The model name "form" is also used by the Activiti Form Viewer.

11.2. FormModel

This object contains directives used to render form elements for backing bean properties annotated with iKnowBase AttributeMapping.

Property Description Type

input

Directive used to create and render a UI component for the form

FormInputDirective

label

Directive used to render a label for a component of the form

FormLabelDirective

bindingFieldErrors

Directive and model used to render any binding errors for the currently submitted form.

FormBindingFieldErrors

message

Directive and model used to render a language specific message from the message source (set of property files)

FormMessage

resources

Directive used to render HTML for resources required by the Plugin form macro directives.

FormResourcesDirective

11.3. FormInputDirective

This directive is used to render an input field for an iKnowBase AttributeMapping-annotated bean property. The directive will automatically adapt its defaults according to the annotations present on the property, including the referenced iKnowBase attribute definition.

For read-only bean properties, this directive will display the value of the property. Any input fields will be disabled.

Parameter Description Type

name

Name of the iKnowBase annotated bean property for which to render input field; this will also be the "name" attribute in the html form.

String

type

Type of input field, see table below for supported values. Default value will depend on type of the bound object.

String

<options>

Type specific options, see table below for an overview.

String

<default>

Other parameters are rendered as they are, allowing any html attribute to be used and rendered.

String

The input fields can take many different forms, depending on its type. The type is initially decided from the underlying data field, such that a numeric field will render as a number field. You can also specify a type manually to override this; this is particularly useful when a single field type has many possible renderings (such as a list of values, which can render as select or radio, and sometimes even as a popup).

Type Description

favoritepopup

For dimensions only: Popup with an additional select box with the last used dimensions for the current user

personalacl

ACL popup with iKnowBase personal acl functionality

popup

Popup with values populated from underlying data field

textarea

Text area

<default>

Any HTML compatible input type (like date, datetime-local, number, text, select, checkbox, radio, …​)

Examples:

<!-- Default input field -->
[@form.input name="title" /]
<!-- Renders a dimension navigator, a drop-down to select dimensions and a user popup to select user, based on attribute definitions and explit forced type -->
[@form.input name="organization" type="popup" /] <!-- NOTE: popup is default and therefore optional on this attribute -->
[@form.input name="brand" type="select" /]
[@form.input name="manager" type="popup" /]

The following table gives an overview of type specific options. The options are available for the given input types and attribute types.

Option Description Input types Attribute types

include

A comma-separated list of external keys for values to be included in the available options (array of strings)

select, radio, checkbox

Acl, Dimension,Valuelist, Documenttype

exclude

A comma-separated list of external keys for values to be excluded from the available options (array of string)

select, radio, checkbox

Acl, Dimension,Valuelist, Documenttype

showRoot

Whether to include root dimensions in the available options or not (boolean)

select, radio, checkbox

Dimension

levels

How many dimension levels to include in the available options (number)

select, radio, checkbox

Dimension

sortBy

"label" to sort valuelist options by label, otherwise sort by sort key (string)

select, radio, checkbox

Valuelist

selectImgSrc

Custom select icon (string - url)

popup

Dimension, Acl, User, Documentlink, Imagelink

selectImgAlt

Custom alt text for select icon (string)

popup

Dimension, Acl, User, Documentlink, Imagelink

selectImgTitle

Custom title text for select icon (string)

popup

Dimension, Acl, User, Documentlink, Imagelink

removeImgSrc

Custom remove icon (string - url)

popup

Dimension, Acl, User, Documentlink, Imagelink

removeImgAlt

Custom alt text for remove icon (string)

popup

Dimension, Acl, User, Documentlink, Imagelink

removeImgTitle

Custom title text for remove icon (string)

popup

Dimension, Acl, User, Documentlink, Imagelink

editImgSrc

Custom edit icon (string - url)

popup

Dimension, Acl, User, Documentlink, Imagelink

editImgAlt

Custom alt text for edit icon (string)

popup

Dimension, Acl, User, Documentlink, Imagelink

editImgTitle

Custom title text for edit icon (string)

popup

Dimension, Acl, User, Documentlink, Imagelink

Examples:

<!-- Renders radio buttons for a filtered valuelist sorted by label  -->
[@form.input name="status" type="radio" include=["IKB_DRAFT", "IKB_COMPLETE"] sortBy="label"/]

11.4. FormLabelDirective

This directive is used to render a label for an iKnowBase AttributeMapping-annotated bean property, using the language specific label defined for the attribute.

Parameter Description Type

name

Name of the iKnowBase annotated bean property you want to render label for

String

<default>

Other parameters are rendered as they are, allowing any html attribute to be used and rendered.

String

Example:

[@form.label name="description" /]

11.5. FormBindingFieldErrors

form.bindingFieldErrors can be used both as a directive and as a model:

  • As Directive: Render a message for a component of the form. Messages are typically the result of data mapping or validation failures (for most input fields) according to the bean validation rules set on the backing bean.

  • As Model: Both a freemarker sequence and hash model, so you can access the nodes directly using ${form.bindingFieldErrors[index]}, or you can traverse it using the [#list]…​[/#list] syntax.

Parameter Description Type

name

Name of the iKnowBase annotated bean property you want to render label for. If ommitted, display errors for all fields

String

separator

If there are more than one error, use this HTML separator between messages

String

Examples:

<!-- A typical scenario rendering all error messages for all form fields -->
[@form.bindingFieldErrors separator="<br>" class="error" /]
<!-- A typical scenario rendering a label, an input field and an error message -->
<tr>
<td>[@form.label name="title" /]</td>
<td>[@form.input name="title" /]</td>
<td>[@form.bindingFieldErrors name="title" separator="<br>" class="error" /]</td>
</tr>
<!-- All errors -->
[#list form.bindingFieldErrors! as fieldError]
    ${fieldError.field} - ${fieldError.rejectedValue!} - ${fieldError.defaultMessage!} - ${fieldError.localizedMessage!} <br />
[/#list]
<!-- Errors for documentType property only -->
[#list form.bindingFieldErrors.documentType! as fieldError]
    ${fieldError.field} - ${fieldError.rejectedValue!} - ${fieldError.defaultMessage!} - ${fieldError.localizedMessage!} <br />
[/#list]

11.6. FormMessage

form.message can be used both as a directive and as a model:

  • As Directive: Render a a language specific message for a given code contained within the Form Processor’s MessageSource (you’ll specify it during construction of the Form Processor), which may contain a set of property files specific for your plugin..

  • As Model: A freemarker hash model, so you can access a message directly using ${form.message[key]}.

Parameter Description Type

code

Key of property in message source (property files)

String

default

Default message if the key was not found in message source

String

 
[@form.message code="myLocalizedFormTitle" default="A default form title" /]

11.7. FormResourcesDirective

This directive is used to render HTML for resources required by the Plugin form macro directives. Typically to be used in the <head> of the HTML-page.

[@form.resources /]

12. Page

12.1. Overview

The figure below gives a quick overview of the models available when rendering a Page using a template.

  • page

    • resources

      • head

      • body

    • regions

      • <name>

    • clientPage

    • strings

      • <name>

        • template

        • page

        • domain

  • context

    • user

      • id

      • username

      • token

        • name

        • value

    • date

    • time

    • datetime

    • millis

    • request

      • pageurl

      • servername

      • serverport

12.2. Global objects

These are the global (top level) objects available when using FreeMarker in a PageViewer, or directly from the PageEngine.

Object Description Type

page

This property contains information about the page itself.

PageModel

context

This property contains information about the execution context.

ObjectReferenceModel

12.3. PageModel

This object contains information about the page.

Property Description Type(s)

resources

Resources that need to be included in the final HTML-page.

ResourcesModel

regions

Page regions (as defined by the components, and not by the template).

[RegionMacro], RegionModel

clientPage

Content of the clientPage, if there is a client page for this page execution.

String

strings

Available strings for the page. This TextMapModel supports locations "template", "page" and "domain".

TextMapModel

12.4. ResourcesModel

This object contains information about resources that need to be included in the final HTML-page, typically page title, scripts and css-references.

The object can be used as is, producing all the relevant resources:

<head>
    ${page.resources}
</head>

Alternatively, you can generate head and body properties separately. The head-property contains references that must be in the <head> part of the HTML-page, while the body-property contains references that may occur at the end of the <body> part:

<html>
<head>
    ${page.resources.head}
</head>
<body>
   ...
    ${page.resources.body}
</body>
Property Description Type

head

HTML for resources to generate in <head> of HTML-page

String

body

HTML for resources to generate in <body> of HTML-page

String

<default>

All resources at once, typically for use in <head> of HTML-page

String

12.5. RegionsModel

This model contains all the regions declared in the page. The model supports several of the basic FreeMarker model types:

  • It is a TemplateHashModel, supporting the properties described in the table below.

  • It is a TemplateHashModelEx, supporting the built-ins ?keys and ?values.

  • It is a TemplateSequenceModel containing RegionModel, supporting index-based lookups (page.regions[index]) and iteration ([#list page.regions as region]…​[/#list]).

  • It is a TemplateNodeModel (where the children is the set of RegionModel), supporting node-based operations.

In addition to exposing the properties described in the table below, the model is also a freemarker sequence containing RegionModel; these can then be accessed using the syntax page.regions[index]. The model is exposed as a sequence of RegionModel, as well as a hash of RegionModel indexed by name, and a freemarker NodeModel which can be used for recursion.

Property Description Type

<name>

A single region

RegionModel

[index]

A single region, by number

RegionModel

?size

Number of regions on page

Number

?keys

Sequence of region names

List of String

?values

Sequence of regions

List of RegionModel

?children

List of children nodes

List of RegionModel

?parent

Parent node

Null

?root

Root node

Null

?ancestors

List of ancestors

List

?node_namespace

There is no namespace; it always returns null.

Null

?node_type

Always the string "Regions"

String

?node_name

Always the string "Regions"

String

12.6. RegionModel

This model contains all the portlets declared for a given region. The model supports several of the basic FreeMarker model types:

  • It is a String (ScalarModel), returning the HTML for the entire region

  • It is a TemplateHashModel, supporting the properties described in the table below.

  • It is a TemplateSequenceModel containing PageComponentModel, supporting index-based lookups (page.regions[index]) and iteration ([#list page.regions as region]…​[/#list]).

  • It is a TemplateNodeModel (where the children is the set of PageComponentModel), supporting node-based operations.

  • It is a TemplateMacro, used to print an entire region with or without a HTML-based container (<div>…​</div>)

Property Description Type

name

Name of the region itself

String

html

HTML for the region content

String

decorated

HTML for the region content, always decorated

String

undecorated

HTML for the region content, never decorated

String

<default>

HTML for the entire region

String

[index]

A single page component, by number

PageComponentModel

?size

Number of regions on page

Number

?children

List of children nodes

List of PageComponentModel

?parent

Parent node

Null

?root

Root node

Null

?ancestors

List of ancestors

List

?node_namespace

There is no namespace; it always returns null.

Null

?node_type

Always the string "Region"

String

?node_name

Always the string "Region"

String

RegionModel is also a macro directive which can beused to print content for a region on a page, using the following syntaxes:

Using ".decorated" will return HTML-content where both the region itself and all containing portlets will be decorated with surrounding <div>-tags, while using ".undecorated" will return HTML-content where neither the region nor the containing portlets will be decorated. In general, use ".undecorated" for content rendered where the <div>-tag will be illegal, such as inside the document <head>, or when rendering non-HTML content (JSON, XML, etc).

<@page.regions region="north" />
<@page.regions region="north" container="true" />
<@page.regions region="north" container="false" />
Parameter Description Type

region

Name of region that you want to print content for

String

container

Flag indicating whether you want to render a surrounding container or not. The default value is "true"

Boolean

Specifying "container=true" for the macro makes the page engine surround every component in the region with an HTML-container(<div>…​</div>). This container is required for AJAX-based operations to work, and is recommended for most content. On the other hand, for content that is not HTML-based, or for content that is to be rendered outside the <body> of a HTML-page, the container may produce illegal output, and must be switched off.

12.7. PageComponentModel

This model contains a given page component (portlet). The model supports several of the basic FreeMarker model types:

  • It is a String (ScalarModel), returning the HTML for the entire page component.

  • It is a TemplateHashModel, supporting the properties described in the table below.

  • It is a TemplateNodeModel (where the children is the set of PageComponentModel), supporting node-based operations.

  • It is a TemplateMacro, used to print an entire region with or without a HTML-based container (<div>…​</div>)

Property Description Type

name

Name of the page component itself

String

markupId

Markup ID for the page component

String

label

Printable and human readable label; often the portlet title

String

<default>

HTML for the entire region

String

?children

List of children nodes

Null

?parent

Parent node

Null

?root

Root node

Null

?ancestors

List of ancestors

List

?node_namespace

There is no namespace; it always returns null.

Null

?node_type

Always the string "PageComponent"

String

?node_name

Always the string "PageComponent"

String

JavaScript library

iKnowBase provides a JavaScript-library in the client page. For the most part, the content of this is private for the various components. However, for components in the page engine there is one feature that might be useful.

The objects, methods and properties in the iKnowBase JavaScript library are generally not intended for manual use, and they will change between versions. However, as far as possible, the items specified in this document will remain backwards compatible.

13. Global objects

These are the global (top level) objects available to HTML clients, provided automatically by iKnowBase.

Object Description Type

iKnowBase

The iKnowBase JavaScript root object

iKnowBase

14. iKnowBase root object

This object contains functions and properties relating to the entire iKnowBase application.

Property Description Type(s)

busyIndicator

This method will run a given function and show a busy indicator while the function runs.

Function

notify

This method will show a notification to the end user.

Function

PageEngine

This property contains the PageEngine object, with methods to refresh page components.

PageEngine

ContentViewer

This property contains the ContentViewer object, with methods to perform document actions.

ContentViewer

14.1. busyIndicator

The busyIndicator method on the iKnowBase-object will run the given function and show a busy indicator while the function runs. It can apply to either a whole page or a given component.

14.1.1. Parameters

Parameter Description Type

options

Can be either a function to be started by the busy indicator, or a hash (object) with properties, as described in the table below.

Function/Object

The hash parameter supports the following properties:

Properties Description Type

autoClose

If true the busy indicator will close automatically, else closing the busy indicator must be handled manually. Defaults to: true.

Boolean

parent

If specified the busy indicator will display for the given component, else it will display for the body. It can be specified as a jQuery selector, element, HTML string, or jQuery object.

String/Object

start

Specifies the function to be started by the busy indicator. Note: This is a required property.

Function

text

Specifies the text to display with the busy indicator.

String

14.1.2. Methods

Method Description

close

Closes the busy indicator.

14.1.3. Example

The following function will show the busy indicator while loading css and scripts. It is manually closed in the start-function’s callback.

IKB.ensure = function(data, callback) {
    iKnowBase.busyIndicator({autoClose: false, start: function() {
        var busy = this;
        load($.makeArray(data.js), $.makeArray(data.css), data.wait, function() {
            busy.close();
            callback();
        });
    }});
}

14.2. notify

The notify method on the iKnowBase-object will show a notification to the user. It can be of type error, warning, or information. The notification will close when the user clicks on it.

14.2.1. Parameters

Parameter Description Type

options

A hash (object) with properties, as described in the table below.

Object

The hash parameter supports the following properties:

Properties Description Type

duration

Specifies the number of milliseconds to show the notification. It not specified, the notification will remain open until it is manually closed.

Number

text

Specifies the text/description.

String

title

Specifies the title.

String

type

Specifies the type of notification. Supported values: 'error', 'info', and 'warning'.

String

14.2.2. Methods

Method

Description

close

Closes the notification.

14.2.3. Example

The following code will show a notification of type information to the user. It will close automatically after 3 seconds.

iKnowBase.notify({
    type:'info',
          title:'Shows both info-icon, title, and text',
          text:'Will automatically close after 3 seconds',
          duration:3000
});

15. iKnowBase.PageEngine

This object contains functions and properties relating to the page engine.

Property Description Type(s)

reloadComponent

This method will reload a component on a page, optionally passing in a set of URL parameters to use during the reload.

Function

15.1. reloadComponent

The reloadComponent method on the PageEngine-object will reload the specified page component from the server, using a number of different settings. The basic syntax is "iKnowBase.PageEngine.reloadComponent (settings)", where settings is a JavaScript hash containing the required settings and parameters, but there are also two old-style supported syntaxes:

It is possible to pass a set of URL-parameters for use during the reload. Whether URL-parameters are required or not, and what various parameters mean, will depend entirely on the (user defined) configuration of the specified page component.

15.1.1. Syntax and parameters

The basic syntax is "iKnowBase.PageEngine.reloadComponent (settings)", where settings is a JavaScript hash containing the required settings and parameters. The settings object supports the following properties:

Parameter Description Type

pageComponent

The client-side ID of the component to reload, or a jQuery-object pointing to the component

String, Element or jQuery

busyIndicator

Whether to show a busy indicator during the reload. Defaults to false.

Boolean

refreshCache

Whether to refresh any current cached content, overriding cache timeouts. Defaults to false.

Boolean

updateHtml

Whether to update the html of the component, or just load data. Defaults to true.

Boolean

errorPopup

Whether to automatically display errors, or ignore them. Defaults to true.

Boolean

data

A hash (object) with URL-parameters to be used during reload

hash

The return value from the reloadComponent is a jQuery promise object (actually a jqXHR object) making it possible to attach callbacks using methods such as done(), fail() and always(). See the example below for more information.

Note
 In order to use updateHtml, the containing page region must be rendered with decorations, as specified by the page.regions FreeMarker model.

The ID of a page component is automatically and computed by the page engine, using an algorithm that may change between versions. You should generate the component ID during component rendering, using the ComponentModel expression ${component.id}. However, you may also specify the pageComponent ID in the page components tab in iKnowBase Development Studio.

The following example reloads the value of a single component, using the parameter p_document_id=1234:

iKnowBase.PageEngine.reloadComponent ({
    pageComponent: '${component.id}',
    data: {
        p_document_id: 1234
    }
});

The following example adds the busy indicator during reload and ensures that the page component content is regenerated (and not loaded from cache):

iKnowBase.PageEngine.reloadComponent ({
    pageComponent: '${component.id}',
    busyIndicator: true,
    refreshCache:  true,
    data: {
        p_document_id: 1234
    }
});

The following example turns off automatic display of errors, and uses the callbacks done and fail for visual status notifications:

iKnowBase.PageEngine.reloadComponent ({
    pageComponent: id,
    errorPopup: false
}).done (function (data, textStatus, jqXHR) {
    jQuery("#" + id).css("background-color", "green");
}).fail (function (jqXHR, textStatus, errorThrown) {
    jQuery("#" + id).css("background-color", "red");
});

15.1.2. Finding the id of the page component

The ID of a page component is normally computed by the page engine, using an algorithm that may change between versions. You should generate the component ID during component rendering, using the FreeMarker expression ${component.id}. You may also specify a stable pageComponent ID in the page components tab in iKnowBase Development Studio, but you are then responsible for ensuring that there are no conflicts.

Use the following template in a ContentViewer to create a function that will reload the viewer with new data:

<script type="text/javascript">
    function showDocument (docid) {
        iKnowBase.PageEngine.reloadComponent ({
            pageComponent: '${component.id}',
            data: {
                p_document_id: docid
            }
        });
    }
</script>
<h2> ${viewer.data.title}</h2>

15.1.3. Deprecated syntax and parameters

reloadComponent still supports a less versatile syntax "iKnowBase.PageEngine.reloadComponent (pageComponent [, url] [, urlParameters]". The traditional syntax has both url and urlParameters as optional function parameters, and it will automatically detect if they are present.

Parameter Description Type

pageComponent

The client-side ID of the component to reload, or a jQuery-object pointing to the component

String, Element or jQuery

url

URL to the page to reload from, possibly including URL-parameters

String

urlParameters

A hash (object) with additional URL-parameters to be used during reload

hash

Note that reloadComponent requires that the containing component has been rendered with decorations, as specified by the page.regions FreeMarker model.

16. iKnowBase.PageEngine.InstantContentCache

This object contains functions and properties relating to the InstantContentCache, i.e. the mechanism that enables clients to receive notification when content caches have been updated. (Note that for this to work, the content cache key must have "publish updates to instant" enabled).

Property Description Type(s)

start

This method will start listening for cache notifications, automatically reloading any component which is present on the page

Function

16.1. start

The reloadComponent method on the PageEngine.InstantContentCache-object will start listening for cache notifications. Before starting, it will check whether it has any page components with known cache keys; if there are none, the listening process witll not start. Whenever a notification is received, it will check whether a component with that particular cache key is known on the page; if it is, it will use PageEngine.reloadComponent to update the data.

16.1.1. Syntax and parameters

The basic syntax is "iKnowBase.PageEngine.InstantContentCache.start (settings)", where settings is a JavaScript hash containing the required settings and parameters. The settings object is currently undocumented:

Parameter Description Type

reloadComponent

The function to be called to reload a component. Parameters to this function is a hash containing only the attribute pageComponent. If the function is not specified, iKnowBase.PageEngine.reloadComponent will be used.

Function

The following example will start listening to cache update notifications, using a default reloadComponent:

iKnowBase.PageEngine.InstantContentCache.start();

The following example will start listening to cache update notifications, telling the user that the page might need to be refreshed:

iKnowBase.PageEngine.InstantContentCache.start({
    reloadComponent: function (settings) {
        iKnowBase.notify ({ text:'Content has been updated. Please refresh the page.' });
    }
});

17. iKnowBase.Instant

The iKnowBase.Instant object contains functions related to the use of iKnowBase Instant, the component providing real time asynchronous messaging to iKnowBase. Some of the available options are in a sub-object named Atmosphere, so named to indicate that these rely on implementation details of the underlying Atmosphere framework.

For simple usage scenarios, the examples below and in the Development Guide may be sufficient; for more advanced usages you may want to consult and understand the underlying Atmosphere APIs.

Property Description Type(s)

Atmosphere.subscribe

Subscribes to a topic, and returns the Atmosphere channel.

Function

Atmosphere.publish

Publishes a message to an already subscribed channel.

Function

Atmosphere.unsubscribe

Unsubscribes from a channel already subscribed to.

Function

Atmosphere.requestUserListUpdate

For userList topics: Request a userList response from the server. Same as subscription option subscribeUserListChanges, but used on demand.

Function

Atmosphere.requestUserList

For userList topics: Request a filtered userList response from the server.

Function

Atmosphere.requestSubscribeUserListChanges

For userList topics: enable or disable join/leave updates for the active connection. Same as subscription option subscribeUserListChanges, but used on demand.

Function

setDefaultOptions

Sets default options to be used for all future subscribe-calls.

Function

17.1. Atmosphere.subscribe

This method establishes a topic-specific channel between the client and a server. The method also sets up callbacks for various events.

17.1.1. Syntax

iKnowBase.Instant.Atmosphere.subscribe (options)
Parameter Description Type

options

Options to be used, a combination of iKnowBase- and Atmosphere specific options.

Hash

17.1.2. Options

The options are as follows:

Parameter Description Type

topicName

The full name of the topic you want to connect to.

String

servletURL

CORS only: URL to Instant servlet. Used in conjunction with enableXDR atmosphere option.

String

subscriptionOptions

iKnowBase-specific options that apply to the subscription. Optional.

Hash

atmosphereOptions

Atmosphere-specific options that apply to the subscription. Optional.

Hash

The subscriptionOptions are as follows:

Parameter Description Type

requestUserList

Request that the server provides a full list of subscribed users as soon as the client has connected. Optional.

Boolean

subscribeUserListChanges

Request that the server provides join and leave messages when users subscribe and unsubscribe to the topic. Optional.

Boolean

The atmoshpereOptions are better described in the Atmosphere documentation, but below are the most important.

Parameter Description Type

transport

Name of transport to use; Legal values are 'websocket' and 'long-polling'; defaults to 'long-polling'.

String

fallbackTransport

Name of transport to use if the preferred transport is unavailable (or fails); defaults to 'long-polling'.

Hash

enableXDR

CORS only: Enable CORS communication. Used in conjunction with servletURL option.

String

onMessage

Callback for when a messsage is received. Receives a single "data" parameter, whose format depends on the topic setup

Function

onOpen

Callbacks for when the channel is opened.

Function

onClose

Callbacks for when the channel is closed.

Function

onReconnect

Callback for when the client reconnects to the server.

Function

onReopen

Callback for when a re-connection successfully reconnected.

Function

onError

Callback for when the client discovers an error.

Function

onMessagePublished

Callback for when using polling and a response was sent back by the server.

Function

onTransportFailure

Callback for when the transport fails because it is not supported by the client or the server.

Function

17.1.3. Topic name and topic options

The topicName option consists of a topic base name and a set of optional topic options. The combination will uniquely identify a specific topic.

The topic base name is required to start with a "/" (forward slash) and can otherwise only contain alphanumeric characters [a-z|A-Z|0-9] and additional forward slashes. The name is case sensitive.

The topic options are added to the topic base name as URL parameters:

Parameter

Value

Description

messageFormat

TEXT

Use simple text message format when publishing and consuming on the topic. This is the default if messageFormat is not set.

messageFormat

IKB

Use IKB message format when publishing and consuming on the topic.

userList

true

Enable userList support. Requires messageFormat=IKB. Instant will keep a list of all connected users and support subscriptionOptions requestUserList and subscribeUserListChanges.

While the TEXT message format can be used to send any text information, the IKB message format has additional application support:

Publishers should send messages using a IKBRequestMessage:

Parameter Description Type

toUserName

The userName of a the recipient. The message will only be delivered to connections with that userName. Optional.

String

messageType

A message type identifier the clients can use to describe the message data payload or reason for message. Optional.

String

correlationId

A optional user specific identifier that can be used with server requests (iKnowBase.Instant.Atmosphere.request*). The identifier will be present in the corresponding response.

String

data

The data to be sent. Required.

String
Note
 Publishers can also choose to send a simple text message to a topic with messageFormat=IKB. This message will be set as data and all optional fields will be empty.

Consumers will always receive messages as a IKBResponseMessage:

Parameter Description Type

fromUser

The UserReference object of the sender. Present if the user was authenticated, otherwise null.

Hash

toUserName

The userName of a the recipient. The recipient can see if this was a private message or a public message. Optional.

String

messageType

A message type identifier the clients can use to describe the message data payload or reason for message. Optional.

String

correlationId

A optional user specific identifier that can be used with server requests (iKnowBase.Instant.Atmosphere.request*). The identifier will be present in the corresponding response.

String

data

The data sent by the publisher.

String

17.1.4. Examples

This example establishes a connection to an instant topic, with a single onMessage-callback.

var channel = iKnowBase.Instant.Atmosphere.subscribe ({
    topicName: "/blog/entries",
    atmosphereOptions: {
        onMessage: function (data) { /* Do something with message */ }
    }
});

This example establishes a connection to an instant topic with specified options, including:

Option type Option Value

Topic

messageFormat

IKB

Topic

userList

true

Subscription

requestUserList

true

Subscription

subscribeUserListChanges

true

Atmosphere

transport

websocket

Atmosphere

onMessage

a callback function

Atmosphere

onError

a callback function

 
[#ftl]
[#if context.user.isLoggedOn]
        [#assign secureTokenAuth =  "'_ikbUserToken':" + "'" + context.user.token.value + "'"]
[#else]
        [#assign secureTokenAuth = '']
[/#if]
var channel = iKnowBase.Instant.Atmosphere.subscribe ({
    topicName: "/blog/entries?messageFormat=IKB&userList=true",
    subscriptionOptions: {
        requestUserList: true,
        subscribeUserListChanges: true,
        ${secureTokenAuth} // Authentication header from ikbViewer
    },
    atmosphereOptions: {
        transport: "websocket",
        onMessage: function (data) { /* Do something with message */ },
        onError: function (atmosphereResponse) { /* Do something with message */ }
    }
});

17.2. Atmosphere.publish

This method establishes a topic-specific channel between the client and a server. The method also sets up callbacks for various events.

17.2.1. Syntax

iKnowBase.Instant.Atmosphere.publish (channel, data)
Parameter Description Type

channel

Channel to publish message on, as returned from subscribe().

Object

data

Data to publish on channel. Type depends on topic messageFormat; use hash for IKB and String for TEXT

String or Hash

17.2.2. Example

To send a text message on a channel with messageFormat=TEXT

iKnowBase.Instant.Atmosphere.publish (channel, "Everybody, there is cake in the reception!");

To send a direct message on a channel with messageFormat=IKB

iKnowBase.Instant.Atmosphere.publish (channel, {
    toUserName: "NARMSTRONG",
    messageType: "WALK_ON_MOON",
    data: "One giant leap, indeed!"
});

17.3. Atmosphere.unsubscribe

This method establishes a topic-specific channel between the client and a server. The method also sets up callbacks for various events.

17.3.1. Syntax

When called without parameters, the unsubscribe-function closes all open connections

iKnowBase.Instant.Atmosphere.unsubscribe ()

When called with a single channel parameters, the unsubscribe-function closes the connection to that channel.

iKnowBase.Instant.Atmosphere.unsubscribe (channel)
Parameter Description Type

channel

Channel to unsubscribe to, as returned from subscribe().

Object

17.4. Atmosphere.requestUserListUpdate

Request a userList response from the server. Same as subscription option subscribeUserListChanges, but used on demand.

17.4.1. Syntax

iKnowBase.Instant.Atmosphere.requestUserListUpdate (channel, correlationId)
Parameter Description Type

channel

Channel for requesting the server information, as returned from subscribe().

Object

correlationId

An optional user specific identified that will be present in the server response.

String

Result is an onMessage call containing IKBResponseMessage with messageType=IKB.USERLIST.RESPONSE and data=List<UserReference>.

17.4.2. Requirements

Active connection on a userList topic.

17.4.3. Example

To request a userList update:

iKnowBase.Instant.Atmosphere.requestUserListUpdate (channel, "MY_CORRELATION_ID");

onMessage response.responseBody:

{
   "toUserName":"ORCLADMIN",
   "fromUser":{
      "guid":null,
      "id":0,
      "username":"ikb$instant",
      "dn":null,
      "label":"iKnowBase Instant Server"
   },
   "messageType":"IKB.USERLIST.USERS",
   "correlationId":"MY_CORRELATION_ID",
   "data":[
      {
         "guid":"BBEA12EB56126795E040000A180038B7",
         "id":58466,
         "username":"KERMIT",
         "dn":null,
         "label":"kermit frog"
      },
      {
         "guid":"8582B1E8B4AA4BDA9B7E0B6422A1D1F7",
         "id":125,
         "username":"ORCLADMIN",
         "dn":"orcladmin",
         "label":"Administrator orcladmin"
      }
   ]
}

17.5. Atmosphere.requestUserList

Request a filtered userList response from the server. Typically used to check a subset of the result from subscribeUserListChanges.

17.5.1. Syntax

iKnowBase.Instant.Atmosphere.requestUserList (channel, correlationId, userNames)
Parameter Description Type

channel

Channel for requesting the server information, as returned from subscribe().

Object

correlationId

An optional user specific identified that will be present in the server response.

String

userNames

An optional array or ; delimited String of usernames used as filter.

String

Result is an onMessage call containing IKBResponseMessage with messageType=IKB.USERLIST.RESPONSE and data=List<UserReference>.

17.5.2. Requirements

Active connection on a userList topic.

17.5.3. Example

To request a filtered userList:

// Example where a full userList would result in ORCLADMIN and KERMIT. Apply KERMIT as filter.
iKnowBase.Instant.Atmosphere.requestUserList (channel, "MY_CORRELATION_ID", "KERMIT");

onMessage response.responseBody:

{
   "toUserName":"ORCLADMIN",
   "fromUser":{
      "guid":null,
      "id":0,
      "username":"ikb$instant",
      "dn":null,
      "label":"iKnowBase Instant Server"
   },
   "messageType":"IKB.USERLIST.RESPONSE",
   "correlationId":"MY_CORRELATION_ID",
   "data":[
      {
         "guid":"BBEA12EB56126795E040000A180038B7",
         "id":58466,
         "username":"KERMIT",
         "dn":null,
         "label":"kermit frog"
      }
   ]
}

17.6. Atmosphere.requestSubscribeUserListChanges

Enable or disable join/leave updates for the active connection. Same as subscription option subscribeUserListChanges, but used on demand.

17.6.1. Syntax

iKnowBase.Instant.Atmosphere.requestSubscribeUserListChanges (channel, correlationId, newSubscribeUserListChangesState)
Parameter Description Type

channel

Channel for requesting the server information, as returned from subscribe().

Object

correlationId

An optional user specific identified that will be present in the server response.

String

newSubscribeUserListChangesState

Boolean for if subscribeUserListChanges should be enabled(true) or disabled(false).

Boolean

Result is an onMessage call containing IKBResponseMessage with messageType=IKB.USERLIST.RESPONSE and data=List<UserReference>.

17.6.2. Requirements

Active connection on a userList topic.

17.6.3. Example

To enable subscribeUserListChanges:

iKnowBase.Instant.Atmosphere.requestSubscribeUserListChanges (channel, "MY_CORRELATION_ID", true);

onMessage response.responseBody:

{
   "toUserName":"ORCLADMIN",
   "fromUser":{
      "guid":null,
      "id":0,
      "username":"ikb$instant",
      "dn":null,
      "label":"iKnowBase Instant Server"
   },
   "messageType":"IKB.USERLIST.SUBSCRIBE.RESPONSE",
   "correlationId":"MY_CORRELATION_ID",
   "data":"Change request for SubscribeUserListChanges: old=false; new=true"
}

To disable subscribeUserListChanges:

iKnowBase.Instant.Atmosphere.requestSubscribeUserListChanges (channel, "MY_CORRELATION_ID", false);

onMessage response.responseBody:

{
   "toUserName":"ORCLADMIN",
   "fromUser":{
      "guid":null,
      "id":0,
      "username":"ikb$instant",
      "dn":null,
      "label":"iKnowBase Instant Server"
   },
   "messageType":"IKB.USERLIST.SUBSCRIBE.RESPONSE",
   "correlationId":"MY_CORRELATION_ID",
   "data":"Change request for SubscribeUserListChanges: old=true; new=false"
}

17.7. setDefaultOptions

This method sets default options to be used for all future subscribe-calls.

17.7.1. Syntax

iKnowBase.Instant.setDefaultOptions (options)

When called with a single channel parameters, the unsubscribe-function closes the connection to that channel.

iKnowBase.Instant.Atmosphere.unsubscribe (channel)
Parameter Description Type

options

Options to be used, a combination of iKnowBase- and Atmosphere specific options. See Atmosphere.subscribe() for details.

Hash

17.8. Complete example

functon displayMessageNotification (data) {
    iKnowBase.notify({
        title: "New message received",
        text: data
    });
}

var channel = iKnowBase.Instant.Atmosphere.subscribe ({
    topicName: "/blog/entries",
    atmosphereOptions: {
        transport: "websocket",
        onMessage: displayMessageNotification
    }
});

18. iKnowBase.ContentViewer

The iKnowBase.ContentViewer object contains functions and properties relating to the content viewer.

Property

Description

Type(s)

deleteDocument

This method will delete a document, with or without prompting the user.

Function

18.1. deleteDocument

The deleteDocument method on the ContentViewer-object will delete the specified document, with or without prompting the user.

18.1.1. Syntax and parameters

The syntax is "iKnowBase.ContentViewer.deleteDocument (options)", where options is a JavaScript hash containing the delete options. The options object supports the following properties:

Parameter

Description

Type

notification

Whether to display notifications or not. Defaults to true.

Boolean

prompt

Whether to prompt the user or not. Defaults to true.

Boolean

documentReferences

Identification of the document(s) to be deleted. Required.

Number , Object or Array

mode

The delete mode. Available modes: ALL (delete all subdocuments), DETACH (detach all subdocuments), CHAIN (attach all subdocuments to deleted document’s parent). Defaults to ALL.

Boolean

onError

Callback function for unsuccessful deletion. Available argurments: data, textStatus, jqXHR.

Function

onSuccess

Callback function for successful deletion. Available argurments: jqXHR, textStatus, errorThrown.

Function

reloadComponentId

The ID of the component to be reloaded after a successful deletion.

String

Use the documentReferences parameter to identify which documents to delete. The property can be one of the following:

  • A document id

  • A document reference object

  • An array of document ids

  • An array of document reference objects

Note
 Deletion of multiple documents is not supported yet.

After a successful delete, a debug message is logged to the browser console, and one of the following happens:

  1. If onSuccess is provided, the callback function is called

  2. If reloadComponentId is provided and notifications are enabled, the component is reloaded and a notification message is displayed

  3. If reloadComponentId is provided and notifications are disabled, the component is reloaded with no notification message

  4. If reloadComponentId is missing and prompts are enabled, the page is reloaded

  5. If reloadComponentId is missing and prompts are disabled, the function performs no UI-operations (the programmer can use the returned promise for actions)

After an unsuccessful delete, a debug message is logged to the browser console, and one of the following happens:

  1. If onError is provided, the callback function is called

  2. If onError is missing and notifications are enabled, a notification message is displayed

  3. If onError is missing and notifications are disabled, the function performs no UI-operations (the programmer can use the returned promise for actions)

The return value from deleteDocument, if called without user prompt, is a jQuery promise object (actually a jqXHR object) making it possible to attach callbacks using methods such as done(), fail() and always(). See the example below for more information.

18.1.2. Examples

The following example prompts the user for deletion of the document with id=1234, if the user accepts the document is deleted and the entire page is reloaded:

iKnowBase.ContentViewer.deleteDocument ({documentReferences: 1234});

The following example prompts the user for deletion of the document with id=1234, if the user accepts the document is deleted, the page component is reloaded and the user is notified:

iKnowBase.ContentViewer.deleteDocument ({documentReferences: 1234, reloadComponentId: ${component.id}});

The following example deletes the document with id=1234 and version=2 without prompting the user, any subdocuments are deleted and the user is notified:

iKnowBase.ContentViewer.deleteDocument ({
    documentReferences: {id:1234, version:2},
    deleteWithoutPrompt: true
});

The following example deletes the document without prompting the user, any subdocuments are detached and the callback is run:

iKnowBase.ContentViewer.deleteDocument ({
    documentReferences: {id:1234, version:2},
    mode: DETACH,
    deleteWithoutPrompt: true,
    onSuccess: function() {alert('delete doucment success')},
    onError: function() {alert('delete document error')}
});

Instead of using the callback properties of the options object, the promise object may be used to run callbacks:

iKnowBase.ContentViewer.deleteDocument ({
    documentReferences: {id:1234, version:2},
    deleteWithoutPrompt: true,
}).done (function () {
    alert('delete doucment success');
}).fail (function () {
    alert('delete doucment error');
});

Other APIs

19. Content Server

The iKnowBase Content Server is the web endpoint for accessing document content. The content server supports both getting (downloading) and putting (uploading) content over the HTTP-protocol.

19.1. Download content

To download content, use the HTTP GET-method with a URL identifying a specific document. The format of the URL is a set of options, separated by slashes and/or commas, ending with a trailing (and unused) readable name:

/Content/id/option,option,option,.../name
/Content/id/option/option/option/.../name

You may use either one or both of the conventions: Separate the options by a forward slash, or use the comma, or a combination of both. Also, there is no restriction on the ordering of the options.

Option

Description

id

A number specifying the document ID of the document whose content you want to retrieve

document.id=number

Specifies the document ID of the document whose content you want to retrieve

document.guid=guid

Specifies the document guid of the document whose content you want to retrieve

document.externalKey=key

Specifies the external key of the document whose content you want to retrieve

docid=number

Specifies the document ID of the document whose content you want to retrieve

guid=guid

Specifies the document guid of the document whose content you want to retrieve

version=number

Specifies the version number of the document that you want to retrieve

attr=guid

Specifies the guid of a file attribute whose content you want to retrieve

cache=millis

This option specified that you want the server to set HTTP-headers that request the document to be cached, if the lastChangedDate of the document matches the given millis-value.

expires=seconds

Specifies that you want the server to set HTTP-headers that request the document to be cached for the specified number of seconds.

no-cache

Specifies that you want the server to set HTTP-headers that request the document not to be cached.

accept=text

Specifies that you want the content object converted to and returned as a pure text file. The server response will use the Mime-type "text/plain".

accept=html

Specifies that you want the content object converted to and returned as an HTML file. The server response will use the Mime-type "text/html".

accept=pdf

Specifies that you want the content object converted to and returned as a PDF file. The server response will use the Mime-type "application/pdf".

accept=zip

Specifies that you want the content object zipped and returned as a zip file. Most useful along when downloading multiple files (see below).

content-disposition=inline

Specifies that you want the server to set the HTTP header "content-disposition: inline". This is a request to the browser that the document is opened inline, inside the browser window.

content-disposition=attachment

Specifies that you want the server to set the HTTP header "content-disposition: attachment". This is a request to the browser that the document is opened as an attachment, in a special application outside the browser window.

content-disposition=none

Specifies that you want the server to NOT set the HTTP header "content-disposition", leaving it up to the browser to decide what to do.

name

Any name you want in the URL. The content server does in fact not use this for anything, but it is useful for providing a human readable URL, and to provide an extension for the web browser.

 
/Content/1234/FlightPlan.doc

The URL above will download the content of document #1234. The part "FlightPlan.doc" is not used by the content server, but may help the user to better understand what the document is about.

/Content/document.id=1234/version=2/accept=html/FlightPlan.html

The URL above will download the content of document #1234, version 2, converted to HTML. Again, the part "FlightPlan.html" is not used by the content server, but may help the user to better understand what the document is about.

/Content/document.externalKey=KEY_CURRENT_FLIGHT_PLAN/accept=pdf/FlightPlan.pdf

The URL above will download the content of a document with external key "KEY_CURRENT_FLIGHT_PLAN", converted to PDF. Again, the part "FlightPlan.pdf" is not used by the content server, but may help the user to better understand what the document is about.

19.2. Download multiple files

You may use the Content Server to download multiple files at once. To do this, add a number of entry-parameters to the URL, where each parameter is a full specification for the Content Server. For example, use the following (one line, broken here for readability):

/Content/accept=zip/test.zip
?entry=/1111/mydocument.doc
&entry=/1111/accept=text/mydocument.text
&entry=/1111/accept=html/mydocument.html
&entry=/docid=2222/version=2/instructions.pdf

The URL above specifies the following:

  • Download a zip-file (accept=zip)

  • Include document ID 1111, named "mydocument.doc"

  • Include document ID 1111, converted to text, named "mydocument.text"

  • Include document ID 1111, converted to html, named "mydocument.text"

  • Include document ID 2222, version 2, named "instructions.pdf"

19.3. Upload content

You may use the ContentServer to upload files, either as new documents or new content for existing documents.

19.3.1. Existing documents

To upload new content for existing documents, POST data to the Content Server, using the same URL that will server document content (shown above). You will need to be logged in for this to work.

19.3.2. New documents

Uploading new documents through the ContentServer works together with the UploadEvent mechanism: The Content Server receives the file, and then triggers an UploadEvent. The implementation of the UploadEvent will then handle the actual storage of the new document.

To upload new documents, POST data to the root of the Content Server. In addition to the files you upload, you may also pass a parameter "uploadParameters" that are forwareded to the UploadEvent; the content of this can be used to specify how the content should be handled.

Uploading content through the file server is most useful with new HTML5-mechanisms, where the following could be used to enable drag-and-drop of files into iKnowBase:

function startUpload(files, uploadParameters) {
   var xhr = new XMLHttpRequest();
   var data = new FormData();
   data.append("uploadParameters", uploadParameters);
   for (var i = 0; i < files.length; i++)
      data.append("file", files[i]);
   xhr.open("POST", "/private/content");
   xhr.send(data);
}

20. Page Engine

The iKnowBase Page Engine is the server component responsible for handling web requests from clients (web browsers, tablets, smart phones, etc). The Page Engine will find the proper page, and return it to the client.

20.1. General use

The basic use of the page engine is to parse the URL, find the page requested, build the page content, and return it to the client. The page engine is available both at the application root, and under the "/page" endpoint.

For example, if the iKnowBase web application with Viewer module is mounted on "/", both of the following requests will find the page "/about", and return to the client:

/about
/page/about

Normally, you will use the root-based mountpoint (/about). However, there are some other services that have higher priority, such as the content server on /Content. Therefore, it is not possible to access a page named "/Content" using "/Content", and you will have to use the specific endpoint "/page/Content".

20.2. Language support

When a user first accesses the Page Engine, he will get a user session. One of the items stored in the session is the current language, where the initial value is decided from the domain configuration, the user settings or the user browser. However, the session language can be changed at runtime, valid only for that session.

For developers, the console available at /ikb$console provides a mechanism for changing the user language. This is readily available under the "developer" tab, and is very convenient for testing.

For application development, the language can also be changed using the URL-parameter "_ikbLanguageCode", with the value set to one of the available language codes. Use the URL-parameter on any page-request; the following two examples will change the language to Norwegian or English:

/about?_ikbLanguageCode=n
/page/about?_ikbLanguageCode=us

20.3. Database trace functionality

The page engine (and really most of the iKnowBase infrastructure) uses a single database connection per request. It is possible to ask that all sql executed by that request should be traced in the Oracle database.

To enable tracing for a single request, use the optional URL parameter "_ikbRequestTracefile=trace_identifier", as follows:

/page/frontpage?_ikbRequestTracefile=frontpage

Then, the database will create a trace file to the default trace location (which varies between database installations), using the specified trace identifier. For example, on an 11g installation this could be "/app/oracle/diag/rdbms/orcl/orcl/trace/orcl_ora_4851_frontpage.trc".

20.4. Refresh content cache

Page components that are configured to use content caching will automatically deliver their content from cache, whenever the cache is present and valid (not expired). However, it is possible to ask that a single request should refresh all content, and not delivered anything from cache.

To enable cache refresh for a single request, use the optional URL parameter "_ikbRefreshContentCache=true", as follows:

/page/frontpage?_ikbRefreshContentCache=true

You may also use the "refreshCache" option on the loadComponent JavaScript-api, which in fact adds a "_ikbRefreshContentCache" parameter under the hood:

iKnowBase.PageEngine.reloadComponent ({
    pageComponent: "ikb4",
    refreshCache: true
})

21. Form HTML Template support

When you chose to use html-based generation for a Content form or Search source, you must supply the HTML markup that is used when the form is rendered. In the markup you provide, you can use a number of iKnowBase-specific tags, which are replaced with appropriate markup and information at runtime.

For getting started, use the Create new template button on the HTML tab; this will produce a sample template you can modify as needed.

21.1. Overview of IKB-tags

Tag

Description

<IKB:FORM>

Renders a HTML form-tag with the appropriate information.

<IKB:FORMNAME>

Renders the name of the HTML-form.

<IKB:LABEL>

Renders the label for a form field.

<IKB:INPUT>

Renders an input field for a form field.

<IKB:DIMENSION>

Renders a dimension selector for a form field.

<IKB:FAVORITE>

Renders a drop-down list of favorite dimensions for a form field.

<IKB:SPACE>

Renders a non-breaking space.

<IKB:CALENDAR>

Renders the calendar button for a form field.

<IKB:RADIO>

Renders a radio button for a form field.

<IKB:CHECK>

Renders a checkbox for a form field.

<IKB:SELECT>

Renders a select list for a form field.

<IKB:BUTTON>

Renders a button for the form.

<IKB:RELATED_OBJECT>

Renders a button for selecting "related objects" for a form field.

<IKB:RELATED_IMAGE>

Renders a button for selecting "related image" for a form field.

<IKB:CONDITIONAL>

Works as an if-test, conditionally rendering or skipping the content, depending on document state.

<IKB:FILE>

Renders a button to upload file content.

<IKB:FILELINK>

Renders the current filename of file content.

<IKB:FILEURL>

Renders the current link to file content.

<IKB:ATTACHMENT>

Renders a button for adding attachments to the document being edited.

<IKB:TEXTAREA>

Renders a textarea for a form field.

<IKB:ADDATTRIBUTE>

Renders a drop down list for adding more attributes to the form at run time.

<IKB:DISPLAY_ADD_ATTR>

Renders a list of dynamic attributes added to the form at run-time. Applicable to Search sources.

<IKB:PROMPT>

Renders the prompt defined for the form field.

<IKB:DISPLAY>

Renders a readable text value of a form field.

<IKB:CONDITIONAL>

Conditionally either renders or skips the content of the tag, depending on the document context.

<IKB:MASTERSELECT>

Renders a button for selecting the parent document for the current document.

<IKB:CONDITION>

Renders the conditions defined for the search form field. Only applicable to Search sources.

<IKB:SAVE_FUNCTION>

Replaces the tag with the name of the database procedure used to save the data when posting the form

<ORACLE>

Executes a PL/SQL code fragment, and renders the output from the execution.

Generally, you can add any HTML-attribute to the iKnowBase tag, and it will be rendered as part of the output.

21.2. ikb:form

The <ikb:form> tag renders an HTML form-tag with the required attributes (action, method) set appropriately.

21.3. ikb:formname

The <ikb:formname> tag renders the form name, either as set in the setup of the RunForm portlet or using a default value of "form_<formId>".

21.4. ikb:label

The <ikb:label> tag will render the label of a form field, as specified in the forms configuration. The actual <ikb:label>-tag will be replaced with a <span> tag, while the value "IKB:PROMPT" inside the tag will be replaced with the actual value.

Example:

<IKB:LABEL id="-344" class="label">IKB:PROMPT</IKB:LABEL>

Renders as:

<span class="label">TheSpecifiedLabel</span>

21.5. ikb:input

The <ikb:input> tag renders a html text field that can be used for editing a form field.

Example:

<IKB:INPUT id="-344" />

21.6. ikb:dimension

The <ikb:dimension> tag renders an iconic button that will open a dimension selector for selecting more values for a form field. Use this along with <ikb:value>, which will show the already selected values.

Example:

<IKB:DIMENSION id="800" imagesrc="/ressurs/list.gif" class="ikbFormDimension" />
<IKB:VALUE id="800" class="iKBFormInput" />

21.7. ikb:favorite_select

The <ikb:favorite_select> tag renders a drop down list of the last recently used values for the dimension attribute. It is typically used with <ikb:dimension>, which allow for the selection of values not in the drop down list.

Example:

<IKB:FAVORITE_SELECT id="802"  size="1" />
<IKB:DIMENSION id="802" imagesrc="/ressurs/list.gif" />
<IKB:VALUE id="800" class="iKBFormInput" />

21.8. ikb:space

The <ikb:space> tag renders a non-breaking space, the HTML entity &nbsp;

Example:

<IKB:SPACE>

21.9. ikb:calendar

The <ikb:calendar> tag renders a button used to open a calendar for selecting date values.

Example:

<IKB:CALENDAR id="764" imagesrc="/ressurs/evita/cal/calendar.gif" buttonclass="ikbFormCalendarButton" />

21.10. ikb:radio

The <ikb:radio> tag renders a set of radio buttons, corresponding to the options of a form field. The content of the tag will be repeated for each value, with the placeholders <IKB:INPUT_ID> and <IKB:INPUT_PROMPT> being replaced with the actual ID and prompt for each value.

Example:

<IKB:RADIO id="802">
  <IKB:INPUT_ID>
  <span class="label">IKB:INPUT_PROMPT</span>
</IKB:RADIO>

21.11. ikb:check

The <ikb:check> tag renders a set of checkboxes, corresponding to the options of a form field. The content of the tag will be repeated for each value, with the placeholders <IKB:INPUT_ID> and <IKB:INPUT_PROMPT> being replaced with the actual ID and prompt for each value.

Example:

<IKB:CHECK id="-142">
  <IKB:INPUT_ID class="ikbCheck" maxlength="20" size="20">
  <span class="label">IKB:INPUT_PROMPT</span>
</IKB:CHECK>

21.12. ikb:select

The <ikb:select> tag renders a select box for a form field. The select box may allow either single or multiple select, depending on the specified options.

Examples of a single select box:

<IKB:SELECT id="803"  size="1" />

Example of a multi-select box.

<IKB:SELECT id="-161" class="ikbSelect" size="4" multiple/>

21.13. ikb:button

The <ikb:button> tag renders a button for one of the default actions of the form. Specify which type of button it is by using the id-attribute of the <ikb:button>-tag.

Id Description

SAVE

When the user clicks on this button the information given in the form will be saved, and the form will close. Applicable to Forms.

APPLY

When the user clicks on this button the information given in the form will be saved, and the form will remain open.Applicable to Forms.

NEXT

When the user clicks on this button the changes will be saved and he will navigate to the next Form in the Task wizard. Applicable to Forms which are part of a Task wizard.

PREVIOUS

When the user clicks on this button he the changes will be saved and he will navigate to the previous Form in the Task wizard. Applicable to Forms which are part of a Task wizard.

FINISH

When the user clicks on this button the changes will be saved, and the Task wizard will close. Applicable to Forms which are part of a Task wizard.

SEARCH

When the user clicks on this button the search will be performed with the search criteria given in the search form. Applicable to Search sources.

STORE

When the user clicks on this button the search criterias will be stored. They can be used to support saved search functionality. Applicable to Search sources.

RESET

When the user clicks on this button the changes performed in the form will be reset to the original values. Applicable to Forms and Search sources.

Example of a save button:

<IKB:BUTTON id="SAVE" class="ikbFormResetButton" value="Save" />

Example of a cancel button:

<IKB:BUTTON id="RESET" class="ikbFormResetButton" value="Cancel" />

Language support can be implemented by entering a NLS-string identification as the value of the tag:

<IKB:BUTTON id="RESET" value="#cs.reset#" />

21.14. ikb:related_object

The <ikb:related_object> tag renders an iconic button that will open a picklist for selecting related document objects for a form field. Use this along with <ikb:value>, which will show the already selected values.

Example:

<IKB:related_object id="800" imagesrc="/ressurs/list.gif" class="ikbFormDimension" />
<IKB:VALUE id="800" class="iKBFormInput" />

21.15. ikb:related_image

The <ikb:related_image> tag renders an iconic button that will open the image archive for selecting images for a form field. Use this along with <ikb:value>, which will show the already selected values.

Example:

<IKB:RELATED_IMAGE id="800" imagesrc="/ressurs/list.gif"  class="ikbFormDimension" />
<IKB:VALUE id="800" class="iKBFormInput" />

21.16. ikb:file

The <ikb:file> tag renders a "browse" button for uploading file content into a form field. Use along with <ikb:filelink>, which shows the current filename (if any).

Example:

<IKB:FILE id="675"  />

The <ikb:filelink> tag renders the filename of the current file of the document being edited.

Example:

<IKB:FILELINK id="675" />

21.18. ikb:fileurl

The <ikb:fileurl> tag renders the url to the current file of the document being edited. Can be used within a File attribute or a document file attribute

Example:

<img border="2" src="<IKB:FILEURL id="675" />">
<a href="<IKB:FILEURL id="675" />" title="This is an image">My title</a>

21.19. ikb:attachment

The <ikb:attachment> tag renders a "browse" button for uploading attachments to the document being edited.

Use along with <ikb:filelink>, which shows the current filename (if any).

Example:

<IKB:ATTACHMENT id="774"  />

21.20. ikb:textarea

The <ikb:textarea> tag renders a HTML <textarea>..</textarea> for a form field.

Example:

<IKB:TEXTAREA id="646" ROWS="rows" COLS="cols">IKB:VALUE</IKB:TEXTAREA>

21.21. ikb:addattribute

The <ikb:addattribute> tag renders a select list of possible other attributes for the form. Use this for dynamic forms, where you want the user to be able to add other attributes to the form, at will.

Example:

<IKB:ADDATTRIBUTE id="-5"/>
<IKB:DISPLAY_ADD_ATTR id="-5"/>

21.22. ikb:display_add_attr

The <ikb:display_add_attr> tag renders a list of attributes added to the form at run-time. Use this for dynamic forms, where you want the user to be able to add other attributes to the form, at will.

Example:

<IKB:DISPLAY_ADD_ATTR id="-5"/>

21.23. ikb:prompt

The <ikb:prompt> tag renders the prompt defined for the form field.

Example:

<IKB:LABEL id="794">IKB:PROMPT</IKB:LABEL>

21.24. ikb:display

The <ikb:display> tag renders the value of a form field as a readable text.

Example:

<IKB:DISPLAY id="18">IKB:VALUE</IKB:DISPLAY>

21.25. ikb:conditional

The <ikb:conditional> tag conditionally either renders or skips the content of the tag, depending on the document context.

Example for "select folder", which is displayed only when uploading a document from a desktop productivity package (Microsoft Office):

<IKB:CONDITIONAL id="752"  />
  <IKB:DIMENSION id="752" imagesrc="/ressurs/list.gif" class="ikbFormDimension" />
</IKB:CONDITIONAL id="752">

Example for "select template", which runs only when a document is not uploaded from a desktop productivity package:

<IKB:CONDITIONAL id="753" />
  <IKB:SELECT id="753"  size="1" />
</IKB:CONDITIONAL id="753">

21.26. ikb:masterselect

The <ikb:masterselect> renders a button for selecting the parent document for the current document.

21.27. ikb:condition

The <ikb:condition> tag renders the conditions defined for the search form field.

Example:

<IKB:CONDITION id="-344" class=""/>

This tag is only applicable to search sources.

21.28. oracle

The <oracle> tag executes any PL/SQL code fragment, and renders the output produced by the executed code. The standard HTP-package supplied with the database may be used.

All valid PL/SQL commands are permitted, and you can call other functions that are implemented in packets or self-contained functions.

Note
 Stored functions are preferred over in-place code due to maintenance issues.

You can also send context-based parameters.

Variable Description

:DOCUMENT_ID

If the document exists, the document ID is sent.

:PARENT_ID

DocumentID of the parent document, if the parent ID exists

:REFERENCE_PATH

Identifier for the portlet instance

:STYLE_ID

Identifier for the form definition

:TASK_ID

Identifier for the task wizard definition, when applicable

:STEP_ID

Identifier for the task step definition, when applicable

:LANGUAGE_ID

The current language code (from user, form, session, …​)

:USER_ID

Userid of the current user

:FORMNAME

The formname

:BACK_URL

The Back URL, as defined by Portal.

Example:

<ikb:form>
<table>
  <tr>
    <td>
      <p><ORACLE>
      Begin
          Htp.p('The time is now: '||to_char(sysdate,'hh24:mi'));
      End;
      </ORACLE></p>
    </td>
    <td>
      <p><ORACLE>
      Begin
          Htp.p( 'The number of sub-documents are: '
                  || subdocuments_count(:DOCUMENT_ID));
      End;
      </ORACLE></p>
    </td>
  </tr>
</table>
</ikb:form>

22. SOLR Schema model

Integration between SOLR and iKnowBase is implemented with usage of a solr configuration (in iKBStudio) where the mapping between iKnowBase attributes and the Solr schema is done. To support the dynamic attribute model in iKnowBase, we use dynamic fields in Solr to store, index or make searchable the same attributes. Also NLS-support is implemented with dynamic fields, and by default Norwegian and English is supported. If the iKnowBase instance supports more languages, we need to add the required fields for each language.

The following table shows the iKnowBase fields in solr/Schema.xml

Tag Type Description Property

id

System

Unique identifier for a solr document. Syntax is <application>-<documentId> where application is typically IKNOWBASE

Stored, indexed

indextime

System

Indicates when the document was last indexed in SOLR

Stored, Indexed

document_id

Document

iKnowBase document id

Stored, indexed

url

Document

The URL to the document in iKnowBase

Stored

title

Document

The title in iKnowBase

Stored, indexed

description

Document

Description of the document

body

Document

The body text or content from a file

type_<language>

Document

Name of the document type

Stored, Indexed

status_<language>

Document

Document status

Stored, Indexed

acl_id

Document

ACL id on the document. -1 if null

Indexed

owner_id

Document

The ownerID of the document

Indexed

valid_from

Document

Indicated when the document is valid from

Stored, Indexed

*_single_qc

Dynamic

Used to build query completion fields. Single valued

Indexed

*_multi_qc

Dynamic

Used to build query completion fields. Multi valued

Indexed

content1

Query field

Contains the searchable title

Indexed

content2

Query field

Contains the searchable description

Indexed

content3

Query field

Contains the searchable body text

Indexed

content4 or content4_<language>

Query field

Contains the searchable attribute values

Indexed

stem1

Query field

Stemmer field for title

Indexed

stem2

Query field

Stemmer field for description

Indexed

stem3

Query field

Stemmer field for body

Indexed

stem4 or stem4_<language>

Query field

Stemmer field for attribute values

Indexed

*_search<_language>

Attribute

Makes the value searchable

*_index<_language>

Attribute

Index the value. Can be used as a query condition

Indexed

*_store<_language>

Attribute

Stores the value. Used for presentation

Store

*_search_index<_language>

Attribute

Combined field

Stored, Indexed

*_search_store<_language>

Attribute

Combined field

Stored

*_search_index_store<_language>

Attribute

Combined field

Stored, Indexed

*_index_store<_language>

Attribute

Combined field

Stored, Indexed

*_index_store_date

Attribute

Date type to store and index dates

Store, Indexed

*_store_date

Attribute

Date type to store dates

Indexed

*_index_date

Attribute

Date type to index dates

Indexed

*_ident

Attribute

Integer type to handle id’s e.g dimensionID

Stored, Indexed

*_guid

Attribute

String type to handle GUID values e.g dimensionGuid

Stored, Indexed

*__path

Attribute

String type to handle dimension paths

Stored

23. Instant Server

The iKnowBase Instant Server is the web endpoint for real time asynchronous messaging.

In addition to the JavaScript API, see JavaScript library > iKnowBase.Instant in the iKnowBase API Reference, which supports both publish and consume, the following APIs are available for publishing messages.

23.1. HTTP API

The HTTP API supports publishing to topics and is an easy way of publishing messages for HTTP clients when there is no need for subscribing to and receiving messages.

The HTTP API v1 has the following endpoints:

Endpoint Authentication Authentication type Return value Comment

/ikb$instant/service/v1/publish

Optional*

_ikbUserToken

NONE

*Topics with UserList support requires authentication using Secure Token Engine Authentication.

/ikb$instant/private/service/v1/publish

Required

Container

NONE

This is a protected URL. Clients will be prompted for authentication according to authentication setu

/ikb$instant/service/v1/requestUserList

Required

_ikbUserToken

JSON:List of UserReference

Request a filtered userlist for the specified topic.

/ikb$instant/private/service/v1/requestUserList

Required

Container

JSON:List of UserReference

Request a filtered userlist for the specified topic.

/ikb$instant/service/v1/requestUserListUpdate

Required

_ikbUserToken

JSON:List of UserReference

Request a full userlist for the specified topic. Same as the JavaScript client subscription option requestUserList=true.

/ikb$instant/private/service/v1/requestUserListUpdate

Required

Container

JSON:List of UserReference

Request a full userlist for the specified topic. Same as the JavaScript client subscription option requestUserList=true.
Note
 For the old method "sendMessage" is deprecated and replaced by "publish".

23.1.1. /ikb$instant/service/v1/sendMessage:

Parameter Description Type Required

topic

Topic to publish message on. This is the full topicName (<topic base name>?<topic options>).

String

YES

message

Text coded data to publish on channel.

String

YES

_ikbUserToken

Scure token identifying the client user.

String

NO*

23.1.2. /ikb$instant/private/service/v1/sendMessage:

Parameter Description Type Required

topic

Topic to publish message on. This is the full topicName (<topic base name>?<topic options>).

String

YES

message

Text coded data to publish on channel.

String

YES

23.1.3. Sending messageFormat=IKB

An example "message" parameter using sendMessage with messageFormat=IKB:

{"toUserName":"","messageType":"SAMPLE_MESSAGE","data":"Hi, how are you?"}

fromUser will be added to the IKBResponseMessage based on authentication.

23.1.4. /ikb$instant/service/v1/requestUserList:

Parameter Description Type Required

topic

Topic requested for user list. This is the full topicName (<topic base name>?<topic options>).

String

YES

userNames

Array of usernames.

String[]

NO

_ikbUserToken

Scure token identifying the client user.

String

YES

Return value: List of UserReference as JSON.

23.1.5. /ikb$instant/private/service/v1/requestUserList:

Parameter Description Type Required

topic

Topic requested for user list. This is the full topicName (<topic base name>?<topic options>).

String

YES

userNames

Array of usernames.

String[]

YES

Return value: List of UserReference as JSON.

23.1.6. /ikb$instant/service/v1/requestUserListUpdate:

Parameter Description Type Required

topic

Topic requested for user list. This is the full topicName (<topic base name>?<topic options>).

String

YES

_ikbUserToken

Scure token identifying the client user.

String

YES

Return value: List of UserReference as JSON.

23.1.7. /ikb$instant/private/service/v1/requestUserListUpdate:

Parameter Description Type Required

topic

Topic requested for user list. This is the full topicName (<topic base name>?<topic options>).

String

YES

Return value: List of UserReference as JSON.

23.2. PLSQL API

See also: PL/SQL ContentServices API and the package "IKB_INSTANT".

23.2.1. Publish message

The PLSQL API supports publishing to topics using procedure IKB_INSTANT.PUBLISH with the following parameters.

Parameter Description Type Required Message formats

p_topic

Topic to publish message on. This is the full topicName (<topic base name>?<topic options>).

VARCHAR2

YES

TEXT,IKB

p_data

Text coded data to publish on channel.

CLOB

YES

TEXT,IKB

p_from_username

The userName that published the message.

VARCHAR2

NO*

IKB

p_to_username

The target userName when publishing a private message.

VARCHAR2

NO

IKB

p_message_type

A message type used by the application.

VARCHAR2

NO

IKB

Example procedure for integration with iKnowBase Event using TEXT message:

CREATE OR REPLACE
PROCEDURE publish_to_instant_topic1_text
(
  PARAMS      IN    OT_EVENTPARAMS
  , OLDREC    IN    OT_DOCUMENT
)
IS
  P_TOPIC         VARCHAR2(200);
  P_DATA          CLOB;
  P_FROM_USERNAME VARCHAR2(200);
  P_TO_USERNAME   VARCHAR2(200);
  P_MESSAGE_TYPE  VARCHAR2(200);
BEGIN
  P_TOPIC         := '/Topic1?messageFormat=TEXT';
  P_DATA          := 'Event triggered due to id: '||params.object_id;
  P_FROM_USERNAME := NULL;
  P_TO_USERNAME   := NULL;
  P_MESSAGE_TYPE  := NULL;
  IKB_INSTANT.PUBLISH(
      P_TOPIC
      , p_DATA
      , P_FROM_USERNAME
      , P_TO_USERNAME
      , P_MESSAGE_TYPE
  );
  COMMIT;
END;

Example procedure for integration with iKnowBase Event using IKB message:

CREATE OR REPLACE
PROCEDURE publish_to_instant_topic1_ikb
(
  PARAMS      IN    OT_EVENTPARAMS
  , OLDREC    IN    OT_DOCUMENT
)
IS
  P_TOPIC         VARCHAR2(200);
  P_DATA          CLOB;
  P_FROM_USERNAME VARCHAR2(200);
  P_TO_USERNAME   VARCHAR2(200);
  P_MESSAGE_TYPE  VARCHAR2(200);
BEGIN
  P_TOPIC         := '/Topic1?messageFormat=IKB';
  P_DATA          := 'Event triggered due to id: '||params.object_id;
  P_FROM_USERNAME := 'IKBUSER1';
  P_TO_USERNAME   := NULL;
  P_MESSAGE_TYPE  := 'SAMPLE_MESSAGE';
  IKB_INSTANT.PUBLISH(
      P_TOPIC
      , p_DATA
      , P_FROM_USERNAME
      , P_TO_USERNAME
      , P_MESSAGE_TYPE
  );
  COMMIT;
END;
Note
 You may need to issue "set define off" due to ampersands (&) in P_TOPIC.

23.2.2. Server request: requestUserList

The PLSQL API supports the server request "requestUserList" for UserList topics.

Parameter Description Type Required Default value

p_topic

Topic requested for user list. This is the full topicName (<topic base name>?<topic options>).

VARCHAR2

YES

null

p_from_username

The userName that requests the list.

VARCHAR2

YES

null

p_user_names

Specify to only receive a filtered list of users.

IKB_PORTAL_API.VC_ARR

NO

empty array

p_timeout

Specify to only receive a filtered list of users.

IKB_PORTAL_API.VC_ARR

NO

10 (seconds)

The call will return CT_USEREFERENCE, which is a list of OT_USERREFERENCE of users currently registered as online on the topic.

Example statement for calling the requestUserList:

DECLARE
  P_TOPIC VARCHAR2(200);
  P_USER_NAMES IKB_PORTAL_API.VC_ARR;
  P_FROM_USERNAME VARCHAR2(200);
  P_TIMEOUT NUMBER;
  L_USER_REFERENCES CT_USERREFERENCE;
BEGIN
  P_TOPIC := '/Topic1?messageFormat=IKB&userList=true';
  P_USER_NAMES := ikb_portal_api.empty_vc_arr;
  P_FROM_USERNAME := 'ORCLADMIN';
  P_TIMEOUT := 10;
  L_USER_REFERENCES := IKB_INSTANT.REQUEST_USERLIST(
    P_TOPIC => P_TOPIC,
    P_USER_NAMES => P_USER_NAMES,
    P_FROM_USERNAME => P_FROM_USERNAME,
    P_TIMEOUT => P_TIMEOUT
  );
  DBMS_OUTPUT.PUT_LINE('Number of user references returned: ' || l_user_references.COUNT);
  FOR i IN 1 .. L_USER_REFERENCES.COUNT
  LOOP
     DBMS_OUTPUT.PUT_LINE('id=' || L_USER_REFERENCES(i).id || '; guid=' || L_USER_REFERENCES(i).guid || '; username=' || L_USER_REFERENCES(i).username || '; dn=' || L_USER_REFERENCES(i).dn || '; label=' || L_USER_REFERENCES(i).label);
  END LOOP;
END;
Note
 You may need to issue "set define off" due to ampersands (&) in P_TOPIC.

23.2.3. Server request: requestUserListUpdate

The PLSQL API supports the server request "requestUserListUpdate" for UserList topics. This call produces the exact same output as the JavaScript client subscription option requestUserList=true.

Parameter Description Type Required Default value

p_topic

Topic requested for user list. This is the full topicName (<topic base name>?<topic options>).

VARCHAR2

YES

null

p_from_username

The userName that requests the list.

VARCHAR2

YES

null

p_timeout

Specify to only receive a filtered list of users.

IKB_PORTAL_API.VC_ARR

NO

10 (seconds)

The call will return CT_USEREFERENCE, which is a list of OT_USERREFERENCE of users currently registered as online on the topic.

Example statement for calling the requestUserList:

DECLARE
  P_TOPIC VARCHAR2(200);
  P_FROM_USERNAME VARCHAR2(200);
  P_TIMEOUT NUMBER;
  L_USER_REFERENCES CT_USERREFERENCE;
BEGIN
  P_TOPIC := '/Topic1?messageFormat=IKB&userList=true';
  P_FROM_USERNAME := 'ORCLADMIN';
  P_TIMEOUT := 10;
  L_USER_REFERENCES := IKB_INSTANT.REQUEST_USERLIST_UPDATE(
    P_TOPIC => P_TOPIC,
    P_FROM_USERNAME => P_FROM_USERNAME,
    P_TIMEOUT => P_TIMEOUT
  );
  DBMS_OUTPUT.PUT_LINE('Number of user references returned: ' || l_user_references.COUNT);
  FOR i IN 1 .. L_USER_REFERENCES.COUNT
  LOOP
     DBMS_OUTPUT.PUT_LINE('id=' || L_USER_REFERENCES(i).id || '; guid=' || L_USER_REFERENCES(i).guid || '; username=' || L_USER_REFERENCES(i).username || '; dn=' || L_USER_REFERENCES(i).dn || '; label=' || L_USER_REFERENCES(i).label);
  END LOOP;
END;
Note
 You may need to issue "set define off" due to ampersands (&) in P_TOPIC.

24. ikb_mailsender

The PL/SQL ikb_mailsender-package is used to send emails to one or more recipients.

24.1. PLSQL API

See also: PL/SQL ContentServices API and the package "IKB_MAILSENDER".

24.1.1. Mail

The PLSQL API supports a method to send mail to one or more recipients with or without attachments.

Example procedure for sending a file to recipients with cc and bcc as arrays as a single mail:

procedure send_file (p_filename in varchar2, p_mimetype in varchar2, p_file blob) is
begin
        ikb_mailsender.send(p_profile => 'default',
                      p_from => ''myadr-from-0`dummy.no'',
                      p_recip  => sendmail.makeArray(ct_value_varchars(
                                                ot_value_varchar('myadr-0`dummy.no'),
                                                ot_value_varchar('myadr-1`dummy.no'))),
                      p_subject => 'This is a mail',
                      p_text_body => 'With some content',
                      p_html_body => '`<h1>With some content</h1>`',
                      p_attachment => ct_attachment(
                                        ot_attachment(p_filename,p_mimetype,p_file)),
                      p_cc  => sendmail.makeArray(ct_value_varchars(
                                                ot_value_varchar('myadr-2`dummy.no'),
                                                ot_value_varchar('myadr-3`dummy.no'))),
                      p_bcc  => sendmail.makeArray(ct_value_varchars(
                                                ot_value_varchar('myadr-4`dummy.no'),
                                                ot_value_varchar('myadr-5`dummy.no'))),
                      p_send_individual => 'N',
                      p_header_name  => sendmail.makeArray(ct_value_varchars(
                                                ot_value_varchar('x-priority'),
                                                ot_value_varchar('Return-Path'))),
                      p_header_value => sendmail.makeArray(ct_value_varchars(
                                                ot_value_varchar('1'),
                                                ot_value_varchar('my-return-path'))));
end;

25. ikb_trashbin

The PL/SQL ikb_trashbin-package is used to restore documents stored in it.

25.1. PLSQL API

See also: PL/SQL ContentServices API and the package "IKB_TRASHBIN".

25.1.1. Recovery of deleted documents

The trash bin is not activated by default, this is done per document type in ikb$console. If activated, a delete operation will move the document to the trash bin and keep it there until it 'expires', defined by the number of days to keep the document.

A PLSQL API supports a method to restore documents from the trash bin.

Example code for restoring two documents from the trash bin:

begin
        ikb_trashbin.RestoreFromTrashBin
                               (p_document_references      => ct_document_reference(
                                                                 ot_document_reference('EXT-KEY-1'),
                                                                 ot_document_reference('EXT-KEY-2')),
                                p_execution_user           => ot_userreference('Username'));
end;

A restore can fail, e.g the external key has been reused or values referencing metadata no longer exists in iKnowBase. To resolve such an error you need direct database access. Check the error message carefully, connect to the iKnowBase schema and query the document from the tables ikb_trash_document and ikb_trash_document_attribute. Fix the error in any of these tables and do retry.