iKnowBase Service API

The iKnowBase Service API exposes functionality to access and process documents and metadata in the iKnowBase Content Store. The API is available both as functions and procedures in PL/SQL packages, Java methods, and Web Services. This chapter, together with the documentation created from the PL/SQL and Java code, composes the documentation of the API.

Security considerations

When using the iKnowBase Service API, the programmer who implements the api client is responsible for authentication the end user. The programmer will then pass that user identity to the Service API using the parameter authenticatedUser, which is present on all methods. The API will then use the security privileges of that user when determening which functionality and data which is available.

API documentation

For the PLSQL-documentation, see /ressurs/iknowbase/doc/api/iknowbase-database-api/index.html
For the Java API documentation, see /ressurs/iknowbase/doc/api/iknowbase-contentservices-api/index.html
For the WebServices API, the WSDL is available at the configured web services endpoint, e.g. /ws/iknowbase-2.wsdl

Sample code

This chapter contains both Java and PL/SQL sample code.

The Java samples uses a variable ds which references a DocumentService instance.

Instantiate a reference object

You can instantiate a reference object, ie object-, document-, or user reference, using a smart constructor which takes one argument; either an external key or an id.

Java

// Smart constructors
ObjectReference objectReferenceFromExternalKey = new ObjectReference("EXTERNAL_KEY");
ObjectReference objectReferenceFromId = new ObjectReference(123456);

PL/SQL

-- Smart constructors
objref_from_external_key := ot_objectreference('EXTERNAL_KEY');
objref_from_id := ot_objectreference(123456);

Instantiate a document attribute

You can instantiate a document attribute using a smart constructor which takes an attribute reference and a value argument. The attribute reference may be specified as an external key or an object reference. The value may be a single value or a list of values for a multi value attribute. An implicit data conversion will take place if the value is of incorrect type.

Java

// Automatic data type conversion
DocumentAttribute clobAttribute = new DocumentAttribute("ATTRIBUTE_CLOB", "This string will be converted to a clob");
DocumentAttribute dimensionAttribute = new DocumentAttribute("ATTRIBUTE_CUSTOMER", "DIM_CUSTOMER_NSF");
dimensionAttribute = new DocumentAttribute("ATTRIBUTE_CUSTOMER", 12345);
DocumentAttribute multiValueDimensionAttribute = new DocumentAttribute("ATTRIBUTE_CUSTOMER",
		"DIMENSION_CUSTOMER_NSF", "DIMENSION_CUSTOMER_GARD");

PL/SQL

-- Automatic data type conversion
clob_docattr := ot_document_attribute('ATTRIBUTE_CLOB', 'This string will be converted to a clob');
dimension_docattr := ot_document_attribute('ATTRIBUTE_CUSTOMER', 'DIM_CUSTOMER_NSF');
dimension_docattr := ot_document_attribute('ATTRIBUTE_CUSTOMER', 12345);
multival_dimension_docattr := ot_document_attribute('ATTRIBUTE_CUSTOMER', 
	ct_document_attribute_values(ot_document_attribute_value('DIMENSION_CUSTOMER_NSF'), ot_document_attribute_value('DIMENSION_CUSTOMER_GARD')));

Document properties

You can handle document properties as plain attributes. Document properties are part of the document object, but may be created, updated, retrieved, and deleted using document attribute objects.

Java

// Document properties as plain attributes
DocumentAttribute titleAttribute = new DocumentAttribute("IKB$TITLE", "This is the document title");
DocumentAttribute documentTypeAttribute = new DocumentAttribute("IKB$DOCTYPE", "DOCTYPE_CUSTOMERINFO");

// Get document property - status
DocumentAttribute documentAttribute = ds.getDocumentAttribute(new UserReference("ORCLADMIN"), documentReference, new ObjectReference("IKB$STATUS"),GetOperationEnumeration.FULL);

// Update document property - title
ds.saveDocumentAttributes(new UserReference("ORCLADMIN"), documentReference,
		Arrays.asList(new DocumentAttribute("IKB$TITLE", "This is the updated title")),
		SaveOperationEnumeration.MERGE, DocumentVersioningModeEnumeration.NONE, null, null, false);

PL/SQL

-- Document properties as plain attributes
title_docattr := ot_document_attribute('IKB$TITLE', 'This is the document title');
document_type_docattr := ot_document_attribute('IKB$DOCUMENT_TYPE', 'DOCTYPE_CUSTOMERINFO');

-- Get document property - status
l_status_docattr := ikb_service_api.get_document_attribute(
	ot_userreference('ORCLADMIN'), 
	l_objref_document, 
	ot_objectreference('IKB$STATUS'), 
	ikb_service_api.get_operation_full
);

-- Update document property - title
l_objref_document := ikb_service_api.save_document_attributes(
	p_execution_user     => ot_userreference('ORCLADMIN'),
	p_document_reference => l_objref_document,
	p_attributes         => ct_document_attributes(
		ot_document_attribute('IKB$TITLE', 'This document is the updated title')
	)
);

Create document

You can create a document using the document object or simply by using document attribute objects.

Java

// Create document from a document object
Document document = new Document()
        .withTitle("This document is created from a java document object")
        .withDocumentTypeReference(new ObjectReference("TEMPDATA"))
        .withValidity(new Document.Validity(new GregorianCalendar(), null))
        .withContent("This is the text content")
        .withDocumentAttributes(
                new DocumentAttribute("SYSTEST_ATTR_CLOB", "This string will be converted to a clob"),
                new DocumentAttribute("IKB_CUSTOMER", Arrays.asList("DIM_CUSTOMER1", "DIM_CUSTOMER2"))
        );
documentReference = ds.saveDocument(new UserReference("ORCLADMIN"), document, SaveOperationEnumeration.MERGE,
        SaveOperationEnumeration.MERGE, SaveOperationEnumeration.MERGE, DocumentVersioningModeEnumeration.NONE,
        null, null, false);

// Create document from document attribute objects
documentReference = ds.saveDocumentAttributes(new UserReference("ORCLADMIN"), null, // Document reference
        Arrays.asList(
                new DocumentAttribute("IKB$TITLE", "This document is created from java document attribute objects"),
                new DocumentAttribute("IKB$DOCUMENT_TYPE", "TEMPDATA"),
                new DocumentAttribute("IKB$VALID_FROM", new GregorianCalendar()),
                new DocumentAttribute("IKB$TEXT", "The text content"),
                new DocumentAttribute("SYSTEST_ATTR_CLOB", "This string will be converted to a clob"),
                new DocumentAttribute("IKB_CUSTOMER", Arrays.asList("DIM_CUSTOMER1", "DIM_CUSTOMER2"))
        ),
        SaveOperationEnumeration.MERGE,DocumentVersioningModeEnumeration.NONE, null, null, false);

PL/SQL

-- Create document from a document object
l_document := ot_document();
l_document.title := 'This document is created from a ot_document object';
l_document.document_type_reference := ot_objectreference('TEMPDATA');
l_document.valid_from := sysdate;
l_document.text_content := 'This is the text content';
l_document.attribute_references := ct_document_attributes(
  ot_document_attribute('SYSTEST_ATTR_CLOB', 'This string will be converted to a clob'),
  ot_document_attribute('IKB_CUSTOMER', ct_document_attribute_values(
	  ot_document_attribute_value('DIM_CUSTOMER1'), 
	  ot_document_attribute_value('DIM_CUSTOMER2')))
);
l_objref := ikb_service_api.save_document(
	p_execution_user  => ot_userreference('ORCLADMIN'),
	p_document        => l_document
);

-- Create document from document attribute objects
l_objref := ikb_service_api.save_document_attributes(
	p_execution_user     => ot_userreference('ORCLADMIN'),
	p_document_reference => ot_document_reference(),
	p_attributes         => ct_document_attributes(
		ot_document_attribute('IKB$TITLE', 'This document is created from ot_document_attribute objects'),
		ot_document_attribute('IKB$DOCUMENT_TYPE', 'TEMPDATA'),
		ot_document_attribute('IKB$VALID_FROM', sysdate),
		ot_document_attribute('IKB$TEXT', 'The text content'),
		ot_document_attribute('SYSTEST_ATTR_CLOB', 'This string will be converted to a clob'),
		ot_document_attribute('IKB_CUSTOMER', ct_document_attribute_values(
			  ot_document_attribute_value('DIM_CUSTOMER1'), 
			  ot_document_attribute_value('DIM_CUSTOMER2')
		))
	)
);

Delete document attribute

You can delete a document attribute from a document. You can also choose to delete only a single value of a multi value doucment attribute.

Java

// Delete document attribute value
ds.saveDocumentAttributes(new UserReference("ORCLADMIN"), documentReference,
        Arrays.asList(new DocumentAttribute("IKB_CUSTOMER", Arrays.asList("DIM_CUSTOMER1"))),
        SaveOperationEnumeration.DELETE_VALUE,
        DocumentVersioningModeEnumeration.NONE,
        null,
        null,
        false);

PL/SQL

-- Delete document attribute value
l_objref_document := ikb_service_api.save_document_attributes(
	p_execution_user      => ot_userreference('ORCLADMIN'),
	p_document_reference  => l_objref_document,
	p_attributes          => ct_document_attributes(
		ot_document_attribute('IKB_CUSTOMER', 'DIM_CUSTOMER1')
	),
	p_attribute_operation => ikb_service_api.save_operation_delete_value
);

iKnowBase Service API
Previous		Next
Integration Using External Attribute Types		iKnowBase Process Services for Activiti

Previous	Top	Next
Integration Using External Attribute Types		iKnowBase Process Services for Activiti