Update Node Versions

Development Guide
Services
- All Services
- Node
  - Set Node
    Set a node, i.e. create or update it, or retrieve information required to create or update it.
  - Get Node
    Get a version of a node.
  - Delete Node
    Delete a node version and everything that depends on it. If this is the only version, delete the node.
  - Copy Node
    Copies a node version to a new node, or to a new version of an existing node.
  - Change Node Reference
    Change the reference of a node.
  - Change Node Type
    Change the node type for a node.
  - Change Node Owner
    Change the owner associated with a node.
  - Node Import
    Node import is a flexible, high-performance service for loading data into Advisor.
  - Node Export
    Export nodes.
  - Get Changed Value
    Get the value of a member, but only if it has changed since it was last retrieved.
    This is used as a quick way of retrieving a piece of data, but bypassing the read if the data has not changed since the last read.
    Call the service passing it a node version reference for the node, one for the member type, and optionally a timestamp when it was last retrieved or updated.
    If the data has changed since the timestamp, the service will return changed of true, timestamp set to ...
  - List Nodes
    Return a list of node versions.
  - List Node Versions
    Lists all the versions of a node.
  - List Recent Node Types
    List the node types that the user has used recently.
  - List Contained Node Types
    List the node types that are in use within a package.
  - Update Node Versions
    The Update Node Versions service creates new versions of nodes which link to new versions of node types and member type targets, to update a node structure to later node versions.
  - Freeze Node
    Freeze a node version, and all the draft node versions on which it depends, i.e. the node version of its node type and all its target nodes.
- User
  - Create User Extended
    Create a user.
  - Get User
    Retrieve information about a user.
  - Get User Details
    Retrieve information about a different user. The user making the call is identified as usual using the userLogonReference. The user about which details are to be returned is specified in userLogonReferenceDetails.
    The user running the service must be able to grant to the user, e.g. they must be the user, or have maintain-users permission, or own-users permission.
    This is similar to GetUser, but GetUser is used for sign on processing and only returns details of the user ...
  - Get Home Node
    Return the home node for the current user.
  - User Exists
    Indicates whether a user or user group already exists.
  - List Users
    Return all the user groups and all the users to which the current user is authorised to grant, or, on the case of users, authorised to include in user groups.
  - User Search
    Search for a user.
  - List Owned Users
    Return all the users over which the current user has own-users authority.
  - List Users By Email
    Lists users for a given email address.
    This is intended to be used by a sign-in helper script. It returns the response in JSON format.
  - Update User
    Update user information, i.e. name and email address.
  - Update User Status
    Change a user's status.
  - Update Password
    Change a user's password.
  - User Property
    Service to set or get a user property, i.e. a property on the user's node.
  - Delete User
    Delete a user.
  - Change User Owning Group
    Change the owning user group for a user, i.e. move them from one owning user group to another.
    The caller must have authority to maintain the user and must have own users authority on the new group, the same permissions they would need to delete and user and create a new user in the to user group.
  - Create Session
    Creates a Metrici session.
  - Create Proxy Session
    Creates a proxy user session within a given account. The session token and a client session token are returned.
    It does not create a proxy session if:
    - The caller is not authorised.
    - The account identifier is not passed or does not exist.
    - The caller does not have a proxy user in the account.
  - Query Session
    Determine if a session token is still valid.
    This does not sign in with the session token. Single use session tokens are not consumed by using this.
  - Cancel Session
    Cancels a Metrici session.
- User Group
  - Create User Group
    Create a user group.
  - Get User Group
    Return details of a user group and its members.
  - User Exists
    Indicates whether a user or user group already exists.
  - List Users
    Return all the user groups and all the users to which the current user is authorised to grant, or, on the case of users, authorised to include in user groups.
  - Get Authorised User Groups
    Return a list of user groups that this user is authorised to administer, or over which they have own-users authority.
  - Update User Group
    Update the name and description of a user group.
  - Add User Group Member
    Add a user to a user group.
  - Remove User Group Member
    Remove a user from a user group.
  - Change User Owning Group
    Change the owning user group for a user, i.e. move them from one owning user group to another.
    The caller must have authority to maintain the user and must have own users authority on the new group, the same permissions they would need to delete and user and create a new user in the to user group.
  - Delete User Group
    Delete a user group.
- Permission
  - Create Permission
    Create permissions.
  - Get Permission List
    List the permissions the user is authorised to maintain and create.
  - Delete Permission
    Delete a permission, using the permission id.
  - Refresh Manifest Permissions
    Refreshes the permissions defined on a manifest.
- Security
  - Run Authorized
    Run another service, after checking that the user has submit service authority.
  - Hash
    Returns a secure one-way hash of a string.
    It is astronomically improbable that two strings have the same hash, or that a string can be derived from a hash by brute force.
  - User Hash
    Returns a secure one-way hash of a string in a way that only the user can calculate. Use this so that a user can "sign" a string and later check that it has not been modified.
    It is astronomically improbable that two strings have the same hash, or that a string can be derived from a hash by brute force.
    The hash is sensitive to changes in the user setup, such as password change, so this should only be used for hashing strings as part of a short-term process.
    Use ...
  - Generate Keys
    Generates a public/private key pair, using the RSA algorithm, and 2048 bit encryption.
    Keys are returned in privacy enhanced mail (PEM) format.
    This is a very simple service. It requires no authorisation, and it returns no errors.
  - Create JWT
    Create a JSON Web Token (JWT), signed with a private key. The private key should have been generated with the GenerateKeys service, and is passed in as a PEM-format PKCS#8 encoded string.
  - Verify JWT
    Verify a JSON Web Token (JWT).
    The JWT is verified against a public key passed in as a PEM-encoded string.
    In addition to verifying the JWT signature, the service performs the following checks:
    - That the jwt has not expired. If passed, the clockSkew value can be set to a number of additional seconds to allow an expired token, to make up for clockSkew, or for the time taken for a token to be passed to a service.
    - The the JWT "aud" claim, if present, ...
- Theme
  - Get User Theme
    Return theming details for a user and/or a domain.
  - Get Themes
    List the themes available to a user.
- File handling
  - Read User File
    Read all of the data in a user file and return it as a block of text. Optionally can access an entry within a zip file. Can return plain text or base64.
    The service runs without authority; if a user knows the storage key they are presumed to have authority to read the file.
  - Write File
    Write data out to a user file.
  - Get User File Info
    Returns information about a user file identified by a file storage key.
    
    By default this returns only an error number to indicate if the file storage key is valid and, if it is valid, the size of the file.
    
    Set the parameter contentType to true to return a contentType for the file.
    
    Set the parameter digest to a digest method (such as MD5) to return a digest of the content of the file. The list of permissible methods is available in the "MessageDigest ...
  - Resize User File Image
    Resizes an image held in a user file.
  - Read Excel
    Read an Excel file and return the contents using JavaScript Object Notation (JSON).
    This supports .xlxs files, as produced by Excel 2007 onwards.
  - Write Excel
    Write an Excel file using data described using JavaScript Object Notation (JSON).
  - Write FO PDF
    Write a PDF file using XSL formatting object (FO) data.
  - PDF
    Utilities for manipulating PDF files.
- Network services
  - Send User Email
    Sends an email.
  - Http Client
    The HttpClient service performs HTTP operations such as GET and POST against a remote service. It can be used to retrieve remote web pages or interact with web services.
    It supports:
    - GET, POST, PUT, DELETE and HEAD methods
    - HTTPS and port specification.
    - Authentication
    - Parameters
    - Headers
    - Data
    The service deals with basic authentication and redirects which may require more than one HTTP request. It will ...
  - SFTP Client
    SFTP client accesses files on a remote server using the SSH file transfer protocol (SFTP).
- Other
  - Echo
    Returns whatever is passed to it, minus user credentials.
  - Run Script / Execute Script
    Run a JavaScript script.
  - Schedule Service
    Schedule a service to run later.
  - Run Rules
    Run a set of rules to infer more findings from a set of input facts.
  - Parse Table Data
    Parses tabular data that typically has been pasted or saved from a spreadsheet program.
  - Translate
    Translate an HTML document or fragment of HTML into a user's chosen language.
  - Search
    Searches for nodes.
  - Set Properties
    Set the properties associated with an object.
  - Get Properties
    Get a set of properties associated with an object.

Description

The Update Node Versions service creates new versions of nodes which link to new versions of node types and member type targets, to update a node structure to later node versions.

The typical case, known as a "relink", is that the service is passed a package. The latest version of the package node and all nodes within it are examined. If the type or any targets are within the package, but are not the latest version, then these are updated to be the latest version, if necessary creating a new version of the node with the new type version and/or to hold the new version of the targets. This is repeated until there is no more relinking to be done.

Parameters control what combination of the node, its immediate contents and all its descendants are updated. Multiple nodes can be selected for the update.

Input

<UpdateNodeVersions>
  <userLogonReference>userid</userLogonReference>
  <password>password</password>
  <action>impact|update|quiet</action>
  <UpdateList>
    <Update>
      <nodeReference/>
      <updateNode>true|false/updateNode>
      <updateContents>true|false</updateContents>
      <updateAll>true|false</updateAll>
    </Update>
  </UpdateList>
  <source>true|false|node.reference</source>
  <draftSource>true|false</draftSource>
</UpdateNodeVersions>

Update repeats.

action controls what the service will do.

impact calculates and returns the impact of the update
update performs the update and returns a description of what it has done
quite performs the update but does not return a description of what it has done

Pass the references of the nodes to be updated in the update list.

The three parameters updateNode, updateContents and updateAll control what is updated. updateNode means that the node itself should be updated, updateContents means that its immediate contents should be updated, and updateAll means that the immediate contents and all lower-level contents should be updated. All three default to true. updateAll is ignored if updateContents is not true.

You can use updateNode to switch off parts of an update. For example, if you set the node reference to somecompany.mypackage with updateNode, updateContents and updateAll left to default, then set somecompany.package.subpackage with updateNode and updateContents of false, then the update would include everything in somecompany.mypackage except for somecompany.package.subpackage.

The caller must have admin authority over all the update nodes, except for those with updateNode and updateContents set to false.

By default, the node update will update to the draft versions of any nodes, though the caller must have permission to use draft nodes of any nodes outside of the update nodes. You can change this by setting source and draftSource:

Set source to false to limit looking for updates to the update nodes themselves.
Set source to a node reference to only update to a node or to any nodes in a package.
Set draftSource to false to disallow updates to draft versions.

Output

<UpdateNodeVersions>
  <errorNumber>0</errorNumber>
  <UpdateList>
    <Update>
      <nodeReference/>
      <nodeVersionNumber/>
      <nodeName/>
      <updateType>version|change</updateType>
      <typeUpdateType>none|change</typeUpdateType>
      <nodeReferenceType/>
      <nodeVersionNumberType/>
      <nodeNameType/>
      <MemberUpdateList>
        <MemberUpdate>
          <nodeReferenceMemberType/>
          <nodeVersionNumberMemberType/>
          <nodeNameMemberType/>
          <nodeReferenceTarget/>
          <nodeVersionNumberTarget/>
          <nodeNameTarget/>
        </MemberUpdate>
      </MemberUpdateList>
    </Update> 
  </UpdateList>
</UpdateNodeVersions>

The update list shows what will be updated or what has been updated, and is only returned for an action of impact or update.

Each updated node is returned in a section. The node is identified by its reference, new version number and name. updateType indicates whether a new version will be created, or the node changed without creating a new version.

If the type is updated, typeUpdateType will be set to change and the new type version number and name are given. (They are not passed if the type is not to be updated.)

The updates for each member are listed. The new version of the target is shown.

The only expected errors are parameter errors and the user not authorised to administer the update nodes.

Treatment of comments

Node member comments are retained when node versions are updated, but are not carried over when new versions are created.

Errors

101 - Not authorised

105 - user error, typically because node reference cannot be found.

Class

com.metrici.xerula.UpdateNodeVersionsService