Set Node

Description

Set a node, i.e. create or update it, or retrieve information required to create or update it.

Input

<SetNode>

  <userLogonReference>userid</userLogonReference>
  <password>password</password>

  <action>new|edit|create|update|impact|force</action>

  <protected>false|true</protected>

  <!-- For create, this identifies the type node -->
  <nodeVersionIdentifierType/>
  <nodeVersionReferenceType/>

  <!-- For update, this identifies the node to be updated -->
  <nodeVersionIdentifier/>
  <nodeVersionReference/>

  <nodeVersionIdentifierView/>
  <nodeVersionReferenceView/>

  <!-- tabNumber is the current tab number -->
  <!-- tabNumberRequest is the requested tab number if there are no errors -->
  <tabNumber/>
  <tabNumberRequest/>

  <context/>

  <!-- Only passed on create and new, if user has set node reference. -->
  <NodeReferenceSection>
    <nodeReference/>
    <nodeReferencePackage/>
    <nodeLocalReference/>
  </NodeReferenceSection>

  <!-- Only passed if the user has set the comment. -->
  <NodeVersionCommentSection>
    <nodeVersionComment/>
  </NodeVersionCommentSection>

  <!-- Only required if the parent node has been set -->
  <ParentNodeSection>
    <nodeVersionIdentifierParent/>
    <nodeVersionReferenceParent/>
    <nodeVersionIdentifierMemberTypeParent/>
    <nodeVersionReferenceMemberTypeParent/>
  </ParentNodeSection>

  <MemberType>  <!-- Repeats for each member type -->
    <nodeVersionIdentifierMemberType/>
    <nodeVersionReferenceMemberType/>
    <Member>    <!-- Repeats for each member -->
      <nodeMemberSequence/>
      <nodeMemberSequenceNew/>
      <nodeMemberValue/>
      <nodeMemberScale/>
      <nodeVersionIdentifierTarget/>
      <nodeVersionReferenceTarget/>
      <nodeVersionIdentifierTargetNew/>
      <nodeVersionReferenceTargetNew/>
      <deleteMemberIndicator/>
      <retainMemberIndicator/>
      <nodeMemberComment/>
    </Member>
  </MemberType> 

</SetNode>

Action parameter:

  • new – retrieve information required to display a page to create a new node.
  • edit – retrieve information required to display a page to edit an existing node.
  • create – create a new node
  • update – update an existing node
  • impact - this shows errors or warnings of performing an update.
  • force - perform an update even if there are warnings

The new and edit processing is included in SetNode because they are complete subsets of the processing. It also allow initial parameters to be passed, and validated, with new and edit, and be shown on the screen.

For an action of new or create, the type of the node to be created is read from the nodeVersionIdentifierType or nodeVersionIdentifierReference parameter. The reference and comment for the new node are read from the nodeReferenceSet and nodeVersionCommentSet parameters.

An action of impact is basically like edit, except that it performs full validation, including impact detection. Use this to show the user the impacts of an update. (Usually there are no impacts, but there may be impacts, e.g. if you delete members from the member type list of a type.)

An action of update will search for impacts and not proceed if there are any impacts, even if they are only warnings.

An action of force will update if there are impact warnings, but not if there are impact errors.

If the node version is frozen, all the mayUpdate indicators in the output will be set to false. If the node version is frozen and is called with an action of update, impact and force, it will be treated as "edit", though parameters should not be passed in this case. This allows clients to provide an edit view of frozen nodes without actually updating them.

A protected value of true sets protected mode. In protected mode then member types with the Protected (system.PROTECTED_TAG) tag set can not be updated, and are returned with mayUpdate set to false. If the node has the Protected tag set, then no member types can be updated.

nodeVersionIdentifierView or nodeVersionIdentifierReference identify the view to be used when returning data to the user. This defaults to the node type (for new or create, as passed as a parameter, for edit/update as read for the passed parameter). Currently only the node type is supported. The tab (page) of the view is specified using the tabNumber. This is optional - it defaults to the first or only page. To request a different view on output from the one on input, use tabNumberRequest. For example, tabNumber 1, tabNumberRequest 2 means "here is tab 1's data. If there are any errors, reshow tab 1. If all OK, give me the data for tab 2." tabNumberRequest defaults to tabNumber. Use tabNumber 0 to return all data, tabNumber -1 to return no data.

If members are passed that are not on the view or tab, they will be processed if possible, but will not be re-shown in the output even if they are in error, i.e. the output always conforms to the requested view and tab, even if the input does not.

The context parameter is used to pass in a node version reference. This will be used as the basis for evaluating target lists that use relative paths or dynamic bindings. This is useful when creating a new node, and when using a transaction node that is in a temporary package. If not passed, these are evaluated from the node that is being set.

For an action of edit or update, the node version to be updated is read from the nodeVersionIdentifier or nodeVersionReference parameter. For new and create, the new reference is read from NodeReferenceSection/nodeReference.

Similar processing applies to the NodeVersionCommentSection. If this is omitted, the comment is not updated.

Within NodeReferenceSection, nodeReference can be replaced by the parameters nodeReferencePackage and nodeLocalReference. If both nodeReference and nodeReferencePackage are passed, nodeReference takes precedence.

nodeLocalReference, or the final part of nodeReference, can be replaced with the special value $auto, in which case a unique reference will be automatically generated for the node. This will be based on the node name, if present.

For new and create, the service checks the user's permission to use the type and the package for the reference.

For edit and update, the service checks the user's admin authority over the node. It does not check permission to use the type. It only checks permission to use the package if there reference is changed.

The nodeVersionReference can take various forms.

The ParentNode section is used for an action of create (though it can be passed on new also). It is optional. It specifies a logical parent of the node, and a member type on that parent that should link to the new node. If passed, the user must have update member authority on the given node and member. If the member type has a maximum cardinality of 1, the link to the newly-created node will overwrite any existing links. Otherwise, the link to the newly-created node will be added to the list of links.

The MemberType structure is slightly redundant, but it allows the intelligence for interpreting the structure to be moved to the SetNode service, rather than in the caller.

The member type is identified by nodeVersionIdentifierMemberType or nodeVersionReferenceMemberType. Identifier takes precedence.

MemberType may be entirely empty (this is useful when the flat-pack XML assembler is being used but not all member types of a group are being updated).

nodeMemberSequence identifies the member that is to be updated. nodeMemberSequence of 0 (the default) means "a new member".

nodeMemberSequenceNew identifies the new position of the member. nodeMemberSequence of 0 means "the same position", which for new members is at the end of the list. nodeMemberSequenceNew is optional.

The target for the member is specified by one of the following, in precedence order:

  • nodeVersionIdentifierTargetNew
  • nodeVersionReferenceTargetNew
  • nodeVersionIdentifierTarget
  • nodeVersionReferenceTarget

You can update a target just by using the *Target field; the *TargetNew allows you to have two have an additional input (e.g. a text area in addition to a drop-down), which you use in preference to the normal one if present.

deleteMemberIndicator indicates that the member should be deleted, unless retainMemberIndicator is true, in which case it is not deleted. This allows for the following cases:

  • A delete member input, optionally passing deleteMemberIndicator
  • A retain member input, setting all the deleteMemberIndicator fields and optionally passing retainMemberIndicator.

Output

If the error number is 0, 105, 108 or 109, SetNode returns the structure below. In other cases it returns a system error.

<NodeEdit>

  <errorNumber>0|105|108|109</errorNumber>

  <!-- Returned when there is an error. 
       Error fields contains a blank-delimited list of fields in error.
       The standard fields are:
         nodeReference
         nodeReferencePackage
         nodeLocalReference
         nodeVersionComment
       Member-level fields are returned as
         nodeVersionReferenceMember or nodeVersionReferenceMember[n]
       e.g.
         com.somecompany.apackage.mytype[3] means that the third member
         with member type com.somecompany.apackage.mytype[3] is in error.
    -->
  <errorDescription/>
  <errorMessage/>
  <errorFields/>

  <!-- Impact list is shown for errors 108 (impact warning) and 109 (impact error) only.
       Impact error lists only error impact types, i.e. nodes that would be impacted by
       an update but which the user can not change.
       Impact warning lists only warnings.  These are nodes that will be deleted or
       modified as a result of the change.
    -->
 
  <ImpactList>
    <Impact>
      <impactType>delete|modify|error</impactType>
      <nodeVersionIdentifier/>
      <nodeVersionReference/>
      <nodeName/>
    </Impact>
  </ImpactList>

  <!-- What this was called with. -->
  <requestAction>new|edit|create|update</requestAction>

  <!-- What the next action should be.
       For requestAction of new, or requestAction of create if this is not successful, this is create.
       For requestAction of edit or update, or requestAction of create if successful, this is update.
       Clients should use this field to decide how to display the results. 
    -->

  <action>create|update</action>

  <!-- For an action of update, details of existing node. -->
  <nodeVersionIdentifier/>
  <nodeVersionReference/>
  <nodeName/>
  <nodeIdentifier/>
  <nodeReference/>
  <nodeVersionNumber/>
  <nodeFrozenVersionNumber/>

  <!-- For update or create, details of the type -->
  <nodeVersionIdentifierType/>
  <nodeVersionReferenceType/>
  <nodeNameType/>
  <nodeIdentifierType/>
  <nodeReferenceType/>
  <nodeVersionNumberType/>

  <!-- Node display properties (see GetNode for a description).
       These are always from the type. -->
  <DisplayProperties>
    <propertyName>property value</propertyName>
    : etc.  
  </DisplayProperties>

  <!-- Node reference.
       Indicate if the user may update the reference.
       True if the action is create, false otherwise.
       If this is true, let the user update the reference.
       If this is false, just show if required.
       EditNode returns the existing reference as nodeReference and split into
       nodeReferencePackage and nodeLocalReferenceSet.
       If the user is not permitted to set the node reference, SetNode returns the same as EditNode.
       If the user is permitted to set the node reference, successful SetNode returns the same as EditNode,
       but if there is an error, SetNode returns whatever was passed to it.
       Empty node reference fields are not necessarily passed, e.g. on create.
    -->

  <NodeReferenceSection>
    <mayUpdate/>
    <nodeReference/>
    <nodeReferencePackage/>
    <nodeNamePackage/>
    <nodeLocalReference/>
  </NodeReferenceSection>

  <!-- The current view and tab. -->
  <nodeVersionIdentifierView/>
  <nodeVersionReferenceView/>
  <nodeNameView/>
  <tabNumber/>

  <!-- The tabNumberRequest is only relevant in odd situations, e.g. looking at the
       impact of an update, this holds where the user should go if they select to update,
       and tabNumber holds where they should go if they want to edit again. -->
  <tabNumberRequest/>

  <!-- The available tabs -->
  <TabList>
    <Tab> <!-- repeats for each tab -->
      <tabReference/>
      <tabName/>
    </Tab>
  </TabList>

  <!-- Node version comment.
       Indicate if the user may update the node version comment.
       If the action is create, always true.
       If the action is update, true if the user has admin authority.
       Empty comment fields are not necessarily passed, e.g. on create.
    -->

  <NodeVersionCommentSection>
    <mayUpdate/>
    <nodeVersionComment/>
  </NodeVersionCommentSection> 

  <!-- May be passed if action is create.  Describes a parent node to which the new node should be linked. -->
  <ParentNodeSection>
    <nodeVersionIdentifierParent/>
    <nodeVersionReferenceParent/>
    <nodeNameParent/>
    <nodeVersionIdentifierMemberTypeParent/>
    <nodeVersionReferenceMemberTypeParent/>
    <nodeNameMemberTypeParent/>
  </ParentNodeSection>

  <!-- Position of node extension, if present -->

  <MemberType>  <!-- Repeats for each member type -->
    <nodeVersionIdentifierMemberType/>
    <nodeVersionReferenceMemberType/>
    <nodeNameMemberType/>
    <nestedSequence/>
    <!-- If error message is present, then this member type is in error. -->
    <errorMessage/>
    <mayUpdate/>
    <nodeDescriptionMemberType/>
    <maximumCardinality/>
    <useValueIndicator/>
    <useScaleIndicator/>
    <useTargetIndicator/>
    <allowAnyTargetIndicator/>
    <TargetList>
      <Target>
        <nodeVersionIdentifierTarget/>
        <nodeVersionReferenceTarget/>
        <nodeNameTarget/>
        <nodeDescriptionTarget/>
      </Target>
    </TargetList>

    <!-- Member type display properties (see GetNode for a description) -->
    <DisplayProperties>
      <propertyName>property value</propertyName>
      : etc.  
    </DisplayProperties>

    <!-- Position of member type extension, if present -->

    <Member>    <!-- Repeats for each member -->
      <!-- The nodeMemberSequenceNew, *TargetNew, and the delete and retain indicators,
           are only returned if passed and there has not been a successful update or create.
           Fields that are not relevant are not passed.
           Target id, reference, name and description will be based on best guess, e.g. if
           a new reference is passed, they will be based on this, but in the case of errors
           the id and reference will never override what was passed in.
        -->
      <nodeMemberSequence/>
      <nodeMemberSequenceNew/>
      <nodeMemberValue/>
      <nodeMemberScale/>
      <nodeVersionIdentifierTarget/>
      <nodeVersionReferenceTarget/>
      <nodeVersionIdentifierTargetNew/>   
      <nodeVersionReferenceTargetNew/>
      <nodeNameTarget/>
      <nodeDescriptionTarget/>
      <deleteMemberIndicator/>
      <retainMemberIndicator/>
      <nodeMemberComment/>

      <!-- Position of member extension, if present -->

    </Member>
  </MemberType> 
    
</NodeEdit>

Errors

101 - Not authorised

102 - Not found

103 - Parameter error

105 - user error. If there are errors with the member data, the fields will be passed back using the form MemberType[x]/Member[y]/fieldName, where x and y are the ordinal positions fo the errant data in the structure output from SetNode.

108 - impact warning

109 - impact error

Class

com.metrici.xerula.SetNodeService