Updating a document with category metadata using updateDocument(): error!

Question

I have studied the sample code and the API docs, and I feel pretty sure I am coding it according to the docs, but I cannot successfully update a document with category metadata. I always get a MetaDataSchemaInvalid exception.
My process goes like this:
1. Upload a new file, creating a new document publicobject.
2. Create a CATEGORY_DEFINITION with all the metadata name/value pairs I wish to write.
3. Call FileManager.updateDocument() with this CATEGORY_DEFINITION.
My process differs from the docs in that I am first uploading the document, and then adding the metadata as a second step. I want to get it working this way to make my system more modular. I do not want to make my upload method dependent upon metadata attributes, and vice versa.
Step 1 is working fine. The document is being uploaded to the right folder. Good to go.
Step 3 is where I get the error. If the error is my fault, then it must be a result of what I do in step 2. The structure of my CATEGORY_DEFINITION must be messed up.
Here is my code for creating the CATEGORY_DEFINITION. The Document class is my own entity that encapsulates the binary data for a document, as well as the metadata attributes that are to be assigned to the document once it is uploaded into Content Services. We don't need to worry about where the data comes from. Just assume the raw data is correct.
public NamedValue[] newCategoryAttributeDefinition(Document document, String categoryDisplayName) throws WebserviceClientException {
/* Get the category attribute name-value pairs as a 2-D array. */
Map metadataMap = document.getMetadataParser().getAttributeNameMapping();
List categoryDefinitionAttributeList = new ArrayList();
for(Iterator i = metadataMap.entrySet().iterator(); i.hasNext();) {
Map.Entry entry = (Map.Entry)i.next();
String name = "CUSTOM_" + (String)entry.getKey();
Object value = entry.getValue();
if(value != null) {
categoryDefinitionAttributeList.add(new Object[] { name, value });
Object[][] categoryDefinitionAttributeArray = new Object[categoryDefinitionAttributeList.size()][];
int index = 0;
for(Iterator i = categoryDefinitionAttributeList.iterator(); i.hasNext();) {
Object[] value = (Object[])i.next();
categoryDefinitionAttributeArray[index++] = value;
/* Create the NamedValue tree that describes this category's attribute values. */
Long categoryId = new Long(getCategoryClassId(categoryDisplayName));
NamedValue[] categoryAttributeDefinition = WebserviceUtils.newNamedValueArray(new Object[][] {
{ Options.CATEGORY_ID, categoryId },
{ Options.CATEGORY_DEFINITION_ATTRIBUTES, WebserviceUtils.newNamedValueArray(categoryDefinitionAttributeArray) }
NamedValue[] categoryDefinition = WebserviceUtils.newNamedValueArray(Options.CATEGORY_DEFINITION, categoryAttributeDefinition);
return categoryDefinition;
And below is the resulting CATEGORY_DEFINITION, as seen in a jdb debugger.
-- The OPT.CATEGORY_ID value is equal to the ID column in ODMV_SCHEMACATEGORY, otherwise known as the category class id.
-- My OPT.CATEGORY_DEFINITION_ATTRIBUTES tree for this document has the 4 attributes that I want to set. The category has more than these 4 attributes; I am not populating every attribute. None of the attributes are required, and all are editable. I don't need to include every attribute in my CATEGORY_DEFINITION, even if the values are null, do I? Also, all the attribute names start with "CUSTOM_", which I believe is necessary - right?
-- I am setting only the OPT.CATEGORY_ID and OPT.CATEGORY_DEFINITION_ATTRIBUTES. Am I missing some other required attribute?
http-8888-Processor5[1] http-8888-Processor5[1] dump categoryDefinition
categoryDefinition = {
instance of oracle.ifs.fdk.NamedValue(id=2562)
http-8888-Processor5[1] dump categoryDefinition[0]
categoryDefinition[0] = {
name: "OPT.CATEGORY_DEFINITION"
value: instance of oracle.ifs.fdk.NamedValue[2] (id=2559)
__equalsCalc: null
__hashCodeCalc: false
typeDesc: instance of org.apache.axis.description.TypeDesc(id=2564)
class$oracle$ifs$fdk$NamedValue: instance of java.lang.Class(reflected class=oracle.ifs.fdk.NamedValue, id=1975)
http-8888-Processor5[1] dump categoryDefinition[0].value[0]
categoryDefinition[0].value[0] = {
name: "OPT.CATEGORY_ID"
value: instance of java.lang.Long(id=2558)
__equalsCalc: null
__hashCodeCalc: false
typeDesc: instance of org.apache.axis.description.TypeDesc(id=2564)
class$oracle$ifs$fdk$NamedValue: instance of java.lang.Class(reflected class=oracle.ifs.fdk.NamedValue, id=1975)
http-8888-Processor5[1] dump categoryDefinition[0].value[0].value.toString()
categoryDefinition[0].value[0].value.toString() = "60068"
http-8888-Processor5[1] dump categoryDefinition[0].value[1]
categoryDefinition[0].value[1] = {
name: "OPT.CATEGORY_DEFINITION_ATTRIBUTES"
value: instance of oracle.ifs.fdk.NamedValue[4] (id=2570)
__equalsCalc: null
__hashCodeCalc: false
typeDesc: instance of org.apache.axis.description.TypeDesc(id=2564)
class$oracle$ifs$fdk$NamedValue: instance of java.lang.Class(reflected class=oracle.ifs.fdk.NamedValue, id=1975)
http-8888-Processor5[1] dump categoryDefinition[0].value[1].value[0]
categoryDefinition[0].value[1].value[0] = {
name: "CUSTOM_From"
value: "SA"
__equalsCalc: null
__hashCodeCalc: false
typeDesc: instance of org.apache.axis.description.TypeDesc(id=2564)
class$oracle$ifs$fdk$NamedValue: instance of java.lang.Class(reflected class=oracle.ifs.fdk.NamedValue, id=1975)
http-8888-Processor5[1] dump categoryDefinition[0].value[1].value[1]
categoryDefinition[0].value[1].value[1] = {
name: "CUSTOM_Footer Number"
value: "PRM 34-318"
__equalsCalc: null
__hashCodeCalc: false
typeDesc: instance of org.apache.axis.description.TypeDesc(id=2564)
class$oracle$ifs$fdk$NamedValue: instance of java.lang.Class(reflected class=oracle.ifs.fdk.NamedValue, id=1975)
http-8888-Processor5[1] dump categoryDefinition[0].value[1].value[2]
categoryDefinition[0].value[1].value[2] = {
name: "CUSTOM_To"
value: "PROJECT TEAM"
__equalsCalc: null
__hashCodeCalc: false
typeDesc: instance of org.apache.axis.description.TypeDesc(id=2564)
class$oracle$ifs$fdk$NamedValue: instance of java.lang.Class(reflected class=oracle.ifs.fdk.NamedValue, id=1975)
http-8888-Processor5[1] dump categoryDefinition[0].value[1].value[3]
categoryDefinition[0].value[1].value[3] = {
name: "CUSTOM_Subject"
value: "Riverside Energy Resource Center Meeting Minutes-Internal"
__equalsCalc: null
__hashCodeCalc: false
typeDesc: instance of org.apache.axis.description.TypeDesc(id=2564)
class$oracle$ifs$fdk$NamedValue: instance of java.lang.Class(reflected class=oracle.ifs.fdk.NamedValue, id=1975)
After building this CATEGORY_DEFINITION, I go on to attempt an update to the document with this information. Here is the method I call. I always fall into the catch(), and the error dump follows the code snippet. Unfortunately, the error doesn't tell me a lot about what's wrong. That's why I am asking for help in spotting any conspicuous errors in my CATEGORY_DEFINITION.
public Item addCategoryToDocument(Item documentItem,
NamedValue[] categoryDefinition)
throws WebserviceClientException {
FileManager fileManager = getWebserviceClient().getFileManager();
Item documentItemWithCategory = null;
try {
documentItemWithCategory = fileManager.updateDocument(documentItem.getId(), categoryDefinition, null);
} catch(Exception e) {
throw new WebserviceClientException("Could not update document with category definition.", e);
return documentItemWithCategory;
http-8888-Processor4[1] http-8888-Processor4[1] dump e
e = {
detailedErrorCode: "ORACLE.FDK.AggregateError"
errorCode: "ORACLE.FDK.AggregateError"
exceptionEntries: instance of oracle.ifs.fdk.FdkExceptionEntry[1] (id=2691)
info: null
serverStackTraceId: ""
__equalsCalc: null
__hashCodeCalc: false
typeDesc: instance of org.apache.axis.description.TypeDesc(id=2694)
class$oracle$ifs$fdk$FdkException: instance of java.lang.Class(reflected class=oracle.ifs.fdk.FdkException, id=1972)
org.apache.axis.AxisFault.log: instance of org.apache.commons.logging.impl.Log4JLogger(id=2695)
org.apache.axis.AxisFault.faultCode: instance of javax.xml.namespace.QName(id=2696)
org.apache.axis.AxisFault.faultSubCode: null
org.apache.axis.AxisFault.faultString: "ORACLE.FDK.AggregateError:ORACLE.FDK.AggregateError"
org.apache.axis.AxisFault.faultActor: null
org.apache.axis.AxisFault.faultDetails: instance of java.util.Vector(id=2698)
org.apache.axis.AxisFault.faultNode: null
org.apache.axis.AxisFault.faultHeaders: null
org.apache.axis.AxisFault.class$org$apache$axis$AxisFault: instance of java.lang.Class(reflected class=org.apache.axis.AxisFault, id=1928)
java.rmi.RemoteException.serialVersionUID: -5148567311918794206
java.rmi.RemoteException.detail: null
java.lang.Exception.serialVersionUID: -3387516993124229948
java.lang.Throwable.serialVersionUID: -3042686055658047285
java.lang.Throwable.detailMessage: null
java.lang.Throwable.cause: null
java.lang.Throwable.stackTrace: instance of java.lang.StackTraceElement[76] (id=2699)
http-8888-Processor4[1] dump e.exceptionEntries[0]
e.exceptionEntries[0] = {
detailedErrorCode: "ORACLE.FDK.MetadataSchemaInvalid"
errorCode: "ORACLE.FDK.MetaDataError"
id: 348018
info: null
serverStackTraceId: ""
__equalsCalc: null
__hashCodeCalc: false
typeDesc: instance of org.apache.axis.description.TypeDesc(id=2705)
class$oracle$ifs$fdk$FdkExceptionEntry: instance of java.lang.Class(reflected class=oracle.ifs.fdk.FdkExceptionEntry, id=1973)
}

Answer 1

1 – For an existing document, how do I determine what category instances have been applied to it and their attribute values
FdkSession session = …;
// Consider we have an existing item myDoc of type document
Item myDoc = …;
CommonManager cm = Managers.getCommonManager(session);
AttributeRequest[] requestedAttributes = new AttributeRequest[]
  // The Categories associated with this Document, if any
new AttributeRequest(Attributes.CATEGORIES,
  // sub attributerequest
  new AttributeRequest[] {
    // the actual attributes name/values for the category instance – returns a namedvalue array
    new AttributeRequest(Attributes.CUSTOM_ALL,null),
    // the actual category class for the category instance – returns an item
    new AttributeRequest(Attributes.CATEGORY_CLASS_OBJECT,null)
myDoc = cm.getItem(myDoc.getId(), requestedAttributes);
log(myDoc); /* output could look like:
(Item) 14385 DOCUMENT sample3.doc
requested attributes ...
CATEGORIES (Item[])=
(Item) 14387 CATEGORY
requested attributes ...
CUSTOM_ALL (NamedValue[])=
CUSTOM_14352=true (Boolean)
CUSTOM_14353=Internal Only Pending Review (String)
CATEGORY_CLASS_OBJECT (Item)=
(Item) 14354 CATEGORY_CLASS 5044-14351
This means, that for document sample3.doc, we have 1 instance of a category object applied to it.
The category object instance has id 14387. The instance is of a category class object type 14354. The instance has two attributes with internal names CUSTOM_14352, and CUSTOM_15353. The values of these attributes are of type Boolean and String respectively.
2 - How do I update an attribute value of an existing category instance applied to an item
FdkSession session = …;
// Consider we have an existing item myDoc of type document
Item myDoc = …;
.. perform code along the lines of that shown in step1 above to determine existing category instance info on the document ..
FileManager fm = Managers.getFileManager(session);
NamedValue[] categoryInstanceAttributes = new NamedValue[] {
  // use the internal attribute name for all attributes
  new NamedValue("CUSTOM_14352", Boolean.FALSE),
  new NamedValue("CUSTOM_14352", "Company Confidential")
NamedValue[] categoryDef = new NamedValue[] {
  // the category instance that we are updating
new NamedValue(Options.UPDATE_CATEGORY_ID,new Long(14387)),
// the updated values of the category instance
  new NamedValue(Options.CATEGORY_DEFINITION_ATTRIBUTES, categoryInstanceAttributes)
NamedValue[] documentDef = new NamedValue[] {
new NamedValue(Options.CATEGORY_DEFINITION, categoryDef)
requestedAttributes = ...
myDoc = fm.updateDocument(myDoc.getId(),documentDef,requestedAttributes) ;
3 – For a document item X, what is the associated category configuration which could include
a) what are the category objects I can apply on it (either explicitly restricted by way of ALLOWED_CATEGORIES on the folder configuration, or any site/domain category by way of ALLOW_ALL_CATEGORIES)
b) is there any attribute overrides
c) is there any enforced categories
FdkSession session = …;
// Consider we have an existing item myDoc of type document
Item myDoc = …;
CommonManager cm = Managers.getCommonManager(session);
AttributeRequest[] categoryObjectAttributes = new AttributeRequest[]
// What is the category object class name
new AttributeRequest(Attributes.CLASS_NAME,null),
  // What is the category classobject display name
new AttributeRequest(Attributes.DISPLAY_NAME,null),
// get attributes inherited and introduced by category object
new AttributeRequest(Attributes.METADATA_ATTRIBUTES,
  new AttributeRequest[]
    // Attribute internal name
    new AttributeRequest(Attributes.ATTRIBUTE_NAME,null),
    // Attribute display name
    new AttributeRequest(Attributes.DISPLAY_NAME,null),
    new AttributeRequest(Attributes.ATTRIBUTE_TYPE,null),
    new AttributeRequest(Attributes.ATTRIBUTE_DEFAULT,null),
    new AttributeRequest(Attributes.ATTRIBUTE_ENUMERATION,null),
    new AttributeRequest(Attributes.ATTRIBUTE_REQUIRED,null),
    new AttributeRequest(Attributes.ATTRIBUTE_SETTABLE,null),
    new AttributeRequest(Attributes.ATTRIBUTE_UPDATEABLE,null),
    new AttributeRequest(Attributes.ATTRIBUTE_HIDDEN,null),
    new AttributeRequest(Attributes.ATTRIBUTE_PROMPTED,null),
    new AttributeRequest(Attributes.ATTRIBUTE_OVERRIDEABLE,null),
AttributeRequest[] overrideAttributes = new AttributeRequest[]
// id of the attribute to be overridden
new AttributeRequest(Attributes.ATTRIBUTE_OVERRIDE_ATTRIBUTE,null),
// id of the category class object to which this attribute override applies
new AttributeRequest(Attributes.ATTRIBUTE_OVERRIDE_CATEGORY_CLASS,null),
// new default value
new AttributeRequest(Attributes.ATTRIBUTE_OVERRIDE_DEFAULT,null),
// should attribute now be prompted
new AttributeRequest(Attributes.ATTRIBUTE_OVERRIDE_PROMPT,null),
// is the attribute now required
new AttributeRequest(Attributes.ATTRIBUTE_OVERRIDE_REQUIRED,null),
// can instances of this attribute have there value updated
new AttributeRequest(Attributes.ATTRIBUTE_OVERRIDE_SETTABLE,null),
AttributeRequest[] requestedAttributes = new AttributeRequest[]
// what is the category configuration for the item
new AttributeRequest(Attributes.CATEGORY_CONFIGURATION,
  new AttributeRequest[]
    // Is the category configuration enabled
     new AttributeRequest(Attributes.CONFIGURATION_ENABLED,null),
     // Can the category configuration be overridden or is it final
    new AttributeRequest(Attributes.CONFIGURATION_FINAL,null),
    // What are the required categories for the category configuration and associated attribute information
    new AttributeRequest(Attributes.REQUIRED_CATEGORIES,categoryObjectAttributes),
    // Can any categories in the site be utilized
    new AttributeRequest(Attributes.ALLOW_ALL_CATEGORIES,null),
    // or .. are we restricting the categories to only the following
    new AttributeRequest(Attributes.ALLOWED_CATEGORIES,categoryObjectAttributes),
    // are there any attribute overrides on category object attributes for this category config?
    new AttributeRequest(Attributes.ATTRIBUTE_OVERRIDES,overrideAttributes)
log(cm.getItem(myDoc.getId(), requestedAttributes); /*
If ALLOW_ALL_CATEGORIES is set to true, any category in the domain can be utilized that is not abstract. To determine these, the domain item has a property CATEGORY_CLASSES that returns all category objects in the domain. It also has a property ROOT_CATEGORY_CLASSES which returns just the top level categories (those that have no custom category superclass). You would create a sub AttributeRequest[] checking for CLASS_ABSTRACT when requesting the appropriate categories attribute from the domain.
If ALLOW_ALL_CATEGORIES is set to false, the applicable categories objects that can be utilized on items contained in the folder is determined by the items contained in the ALLOWED_CATEGORIES attribute of the category configuration.
Finally, the REQUIRED_CATEGORIES attribute list the category items that must be applied to all new items added to the folder.
4 – How do I manually apply an instance of a category to an existing item
FdkSession session = …;
// Consider we have an existing item myDoc of type document
Item myDoc = …;
.. use techniques in step3 above to determine what category objects that you planning to apply to the document ..
.. if the category configuration on the item has ALLOW_ALL_CATEGORIES set to true, you can use any category in the system
.. otherwise, you must use a category defined in the allowed categories list
.. the code here is essentially the same as step2 above
.. you must utilize internal attribute names, and specify the id of the category class object
FileManager fm = Managers.getFileManager(session);
NamedValue[] categoryInstanceAttributes = new NamedValue[] {
  // use the internal attribute name for all attributes
  new NamedValue("CUSTOM_14352", Boolean.FALSE),
  new NamedValue("CUSTOM_14352", "Company Confidential")
NamedValue[] categoryDef = new NamedValue[] {
  // the id of the category object class for which this new category will be an instance of
new NamedValue(Options.CATEGORY_CLASS_ID,new Long(14354)),
// the updated values of the category instance
  new NamedValue(Options.CATEGORY_DEFINITION_ATTRIBUTES, categoryInstanceAttributes)
NamedValue[] documentDef = new NamedValue[] {
new NamedValue(Options.CATEGORY_DEFINITION, categoryDef)
requestedAttributes = ...
myDoc = fm.updateDocument(myDoc.getId(),documentDef,requestedAttributes);
// Note – it is possible for one to peform creation, updating, and deletion of various category instances for an existing item in the fileManager updateDocument call!
// you simply supply multiple Options.CATEGORY_DEFINITIONs to the fm.updateDocument call along with any Options.REMOVE_CATEGORY_IDs 5 – How do I specify a category instance when creating a new item
FdkSession session = …;
.. use techniques in step3 above to determine what category objects that you planning to apply to the new document ..
.. you get the category configuration information from the destination folder!!!
Item destinationFolder = …;
CommonManager cm = Managers.getCommonManager(session);
AttributeRequest[] requestedAttributes = new AttributeRequest[]
// what is the category configuration for the item
new AttributeRequest(Attributes.CATEGORY_CONFIGURATION,
destinationFolder = cm.getItem(destinationFolder.getId(),requestedAttributes);.. if the category configuration on the folder item has ALLOW_ALL_CATEGORIES set to true, you can use any category in the system
.. otherwise, you must use a category defined in the allowed categories list
.. the code here is essentially the same as step2 above, just we are using createDocument and document definitions now
.. you must utilize internal attribute names, and specify the id of the category class object
FileManager fm = Managers.getFileManager(session);
NamedValue[] categoryInstanceAttributes = new NamedValue[] {
  // use the internal attribute name for all attributes
  new NamedValue("CUSTOM_14352", Boolean.FALSE),
  new NamedValue("CUSTOM_14352", "Company Confidential")
NamedValue[] categoryDef = new NamedValue[] {
  // the id of the category object class for which this new category will be an instance of
new NamedValue(Options.CATEGORY_CLASS_ID,new Long(14354)),
// the attribute values for this new category instance
  new NamedValue(Options.CATEGORY_DEFINITION_ATTRIBUTES, categoryInstanceAttributes)
String destinationFile = "sample.doc";
requestedAttributes = new AttributeRequest[]
  new AttributeRequest(Attributes.URL,null)
Item docDef = fm.createDocumentDefinition(new NamedValue[]
  new NamedValue(Attributes.NAME, destinationFile),
},requestedAttributes);
String defURL = ...  // get URL from document definition
doFileUpload(...)  // upload file using http put to defURL
NamedValue[] documentDef = new NamedValue[] {
  new NamedValue(Options.USE_SAVED_DEFINITION,new Long(docDef.getId())),
new NamedValue(Options.DESTFOLDER, new Long(destinationFolder.getId())),
// specify character set if appropriate
  new NamedValue(Attributes.DOCUMENT_CHARACTER_SET,"ISO-8859-1"),
  // specify language if appropriate
new NamedValue(Attributes.DOCUMENT_LANGUAGE,"ENGLISH"),
// apply category instance information
new NamedValue(Options.CATEGORY_DEFINITION, categoryDef),
requestedAttributes = ...
Item doc = fm.createDocument(documentDef,null, requestedAttributes);
// Note – it is possible for one to peform creation of multiple category instances on a document at the same time
// you simply supply multiple Options.CATEGORY_DEFINITIONs to the fm.createDocument call
// Note – that if a folder has a category configuration containing required categories, and you do not specify
// all applicable category definitions on createDocument, you will receive an FdkException along the lines of
// missing metadata. You can catch this exception, and retry the createDocument call supplying the valid category definition(s).