Handling errors

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.
  - Force Password Change
    Set the indicator to force a user to change their password next time they sign in.
  - 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.

An error is detected in one of two ways:

If the background execution uses a "start", by a "error" callback. The callback data should contain message, and may contain errorNumber and errorDescription.
If the background execution does not use a "start", by returning an application error. This is formatted into an error callback.

The callback anchor step is passed the error to set the callback status. The "next" "error" step will be run.

The following minimal example shows a callback error step that logs the error.

[
  {
    "name": "prepare",
    "script": "stepTypeCallback",
    "next": {
      "prepare": "call",
      "complete": "complete",
      "error": "logError",
      "*": false
    }
  },
  {
    "name": "logError",
    "script": "stepTypeLog",
    "config": {
      "log": "%{attr:callbackData}"
    },
    "next": false
  }
]

Depending on the type of error and where they occur, some system-level errors may also be returned as "error" statuses (others will be handled using standard error handling).