LogoLogo
Click to Submit Feedback!
  • Welcome to ASM HERMES!
    • HERMES 10.6.8 Release Notes
      • 10.6.8.14379 AUG 24 MR Release Notes
      • 10.6.8.14627 SEPT 24 MR Release Notes
      • 10.6.8.14701 OCT 24 MR Release Notes
      • 10.6.8.14800 OCT 24 2 MR Release Notes
      • 10.6.8.14879 NOV 24 MR Release Notes
      • 10.6.8.14901 N0V 24 2 MR Release Notes
      • 10.6.8.15038 DEC 24 MR Release Notes
      • 10.6.8.15097 JAN 25 MR Release Notes
      • 10.6.8.15121 JAN 2 25 MR Release Notes
      • 10.6.8.15289 FEB 25 MR Release Notes
      • 10.6.8.15348 FEB 2 25 MR Release Notes
      • 10.6.8.15509 MAR 25 MR Release Notes
      • 10.6.8.15572 APRIL 25 MR Release Notes
    • HERMES 10.6.9 RC Release Notes
      • 10.6.9.14735 OCT 24 RC Release Notes
    • ASM Video Library
  • ITSM Solutions
    • Example Solutions - Best Practices for a Successful Outcome
      • Managing Changes to your ASM Application
      • Business Continuity Planning
      • Capacity Planning
      • Change Management
        • Planning Change Management
        • Build Your Workflow
      • Dynamic Ticket Routing
      • Environmental Impact Analysis (for TBL Accounting)
      • Knowledge Management
        • Planning Knowledge Management
      • Major Incident Management
        • Configure Major Incident Management
        • Allow Users to Subscribe to MI
      • Project Management
        • ASM Project Management How-To Videos
      • Service Validation and Testing
        • Example Configuration
      • User Survey Systems
        • Planning and Implementing Surveys
        • Survey Fields and Configuration
      • Workforce and Talent Management
        • Example Configuration
      • 2-Part Call Close Process
      • Incident Management
        • Planning Your Incident Management Implementation
        • Setup IPK Management
        • Build Screens to Support IPK
  • Use ASM
    • About the Alemba Service Manager Family
      • URLs and Access Parameters
        • System Access URLs
        • ASM Self Service Portal URLs
        • Pre-Populating Search Fields
    • Using the Self Service Portal
      • Logging on to Self Service Portal
        • Forgotten User ID and Password (Self Service Portal)
        • Password Expiry
      • Self Service Portal Home Page
      • Self Administration in Self Service Portal
        • Updating Your Contact Details
        • Changing Your Password
        • Delegating Work
      • Logging and Reviewing Tickets and Tasks/Approvals
        • Using the Logging Forms in Self Service Portal
        • Suggested Knowledge in the Self Service Portal
        • Reviewing Your Tickets in the Self Service Portal
          • Cloning Tickets in Portal
          • Chasing Ticket or Request
        • Off-Line Conversations with Support
        • Closing Your Tickets
        • Reopening Your Tickets
        • Cloning Your Tickets
      • Following Tickets
      • Self-Help/Self-Diagnosis in Portal: Scripts
      • Searching the Knowledge Bank in Self Service Portal
      • Chat
        • Alembot - Chatbot
      • Service Request Catalog
      • Your Surveys
    • Using Nano
      • Nano Feature List
      • NANO Video Tutorial - Quick Start
      • Nano Application
        • Viewing Your Workload in NANO
        • Viewing Bulletins
        • Nano Matching Panel
        • Using the Call, Request, and Task Details window
        • Working with Entities in Nano
          • Followers
        • Using Resource Manager in NANO
        • Viewing Your Outstanding Tasks
        • Keyboard Shortcuts
    • Using ASM Core
      • Getting Started
        • The ASM Core Window
          • The Information Panel
          • The View Option
          • The New Option
          • Configuring search results
        • Changing your Password
        • Generating an ASM statistics report
        • Printable Reports from within Core
        • Searching for Items
          • Using Wildcards in Search
          • Outstanding Item Searches
          • Saved searches
          • Viewing Search Results in Graphs
          • Creating Reporting Views from Search Results
        • Indicators - Icons
      • View Your Consolidated Workload
      • Viewing Daily Stats
      • Chat
      • Managing Followers
      • Managing Your Tickets - Calls and IPK
        • Working with Calls
          • About the Call Details Window
          • Cloning Option
          • Log New Request from Call
          • Watch Call
          • Change a Call from an Incident to a Problem, Known Error, Major Incident, or Service Request
          • About the Service Window
          • About the Call Information Panel
          • About the Matching Panel
          • Add Notes - Updating Your Tickets
            • Notes: Offline Conversations with the User
          • Managing and Using Call Activities
          • Assigning Work Based on Skills
        • Call Details Explorer Options
          • Call Activities Explorer Option
          • Linking Explorer Option
          • Forum Analysts Explorer Option
          • AI Ops Explorer Option
          • Viewing Event Transactions from a Call or Request
          • Email All Explorer Option
        • Overview of CTI in Alemba Service Manager
          • Storing Telephone Numbers for CTI
        • Logging a Call
        • Using Quick Solutions
        • Using Quick Forms
        • Deferring a Call
        • Reassigning/Forwarding a Call(s) Internally
        • Forwarding a Call Externally
        • Creating an Outage from a Call
        • Closing a Call
        • Global Updates
        • User Chased Tickets
        • Escalating Tickets
      • Sending Ad-Hoc Surveys
      • Requests and Tasks
        • Viewing your Request Workload
          • Viewing Outstanding Requests
          • Searching for Requests
        • Submit a New Request
        • Escalate a Request
        • Searching for Tasks
        • Suspending a Task
        • Completing a Task
        • Sending email from a task
        • Forwarding a Task Internally - Reassignment
        • Completing an Approval
        • Managing Change Calendars
        • Managing Resources
          • Preparing to Use Resource Manager
          • Using Resource Manager
          • Allocating Tasks in Resource Manager
      • Ordering Service Actions within ASM Core
      • Adding Attachments
      • Managing your CMDB
        • Managing CMDB Items
          • Cloning CMDB Items
          • Completing CMDB Item Details
          • CMDB Linking Diagram
          • Freezing CMDB Items
          • Linking CMDB Items
        • Managing Your Assets
          • Managing Inventory Items
          • Managing Software Products
          • Thresholds Explorer Option
          • Managing Transactions
            • Purchasing Items
            • Reserving Items
            • Allocating Items
            • Transferring Ownership of Items
            • Retiring Items
            • Changing Availability Status of Items
            • Adding an order from a search field
          • Specifying Usage Criteria
        • Managing your Service Portfolio
          • Managing Services
          • Managing Service Actions
            • Defining the Outcome of Selecting a Service Action
          • Managing Service Bundles
        • Managing Organizations
        • Managing Locations
        • Managing Cost Centers
        • Managing Jurisdictions
        • Managing Subscriber Groups
        • Managing Stakeholders
        • Options in the CMDB Items Explorer Pane
        • Allocating Change Windows to CMDB Items
        • Managing People
        • Managing Contracts
        • Managing Availability
          • Managing Outages
          • Impact Criteria
          • Displaying Outages
        • SLM - Managing Agreements
          • Defining Agreement Thresholds
          • Linking Service Items to an Agreement
          • Attaching Selection Criteria to Agreements
          • Agreement Measurements
      • Configuring AI Ops
        • Using the AI Ops Wizard
        • Managing AI Ops Rules
      • Knowledge Management
        • Managing Knowledge Entries
        • The Knowledge Bank Explorer
        • Viewing Knowledge Entries
        • Knowledge Administration
      • Configuring Reminders
      • Using IPK Workflow Rules
        • Part 1 - Building the Workflows
        • Part 2 - Defining Workflow Criteria Rules
          • Defining Call Fields for IPK Rules
        • Part 3 - Assigning Workflows to Rules
        • Configuring Call Auto Close Rules
        • Running Multiple Workflow Types on a Call
      • The Bulletin Board
        • Viewing Bulletins
        • Managing Bulletins
      • Using Timesheets
      • Scheduling Calls and Requests
      • Using Quick Forms
      • Using Call Scripts in Core
      • Instant Messaging/Internal Messages
      • Sending an Email
        • Finding Recipients
      • Delegation Setup
      • Purging Data
  • SetUp & Configure ASM
    • Licensing
      • Licensing model
      • ASM Person Licenses
    • Installation and Patching
      • Alemba Service Manager On-Premise Architecture
      • HERMES Installation Guide
        • HERMES Prerequisites
        • Upgrading/Installing ASM to HERMES Step by Step Guide
      • Installation PowerShell Parameters
        • Administration Using PowerShell Scripts
      • Installation Guide for Syncfusion Dashboards
        • Part 1-Syncfusion Dashboard Server Installation
        • Part 2-Syncfusion Server Check HTTPS Binding has been Configured
        • Part 3-Syncfusion Server User Management Server (UMS) Configuration
        • Part 4-Syncfusion Server Configure the Dashboard Server
        • Part 5-Syncfusion Server Patching the Scheduler Service
      • Upgrading from vFire 9.2 or Below
      • Installing and upgrading on Multiple Web Servers
      • Patching where downloading files is not possible
        • Installation Using Setup.exe
      • Configuring external network access to ASM
      • About the Polling Services
      • Uninstalling ASM Core
    • Setting Up your System
      • On-Premise: System Console Configuration Settings
      • Logging in as Administrator
      • ASM Nano
        • Enabling Nano
        • Request Phases
      • Setup IM (Internal Messaging)
      • Setup Email
        • Setting Up Incoming and Outgoing Email
          • Email Server Configuration
          • Methods of Authentication for Mail Servers
          • Incoming Email
            • Recognized Incoming Email Subject Headings
            • Incoming POP3, and IMAP Email Server Settings
            • Incoming Email via API
            • How the Logging Analyst is Determined on an Incoming Email
          • Outgoing SMTP Email Server Settings
          • Outgoing Email via Webhooks
          • Configure Azure MS Graph API
          • Configuring Exchange Web Services (EWS)
            • Prerequisites
              • Web Redirect URL Configuration
              • Creating an Azure Client Secret
            • EWS - Configure Outgoing Email
            • EWS - Configure Incoming Email
            • EWS - Authorize the Connection
            • EWS - Troubleshooting
        • Mail Message Access (MMA)
      • Setup Chat
    • Configuring your System
      • Accessibility Features
      • ASM Solutions
      • Call Template Administration
      • Configuration Post Go-Live
        • Preparing Production for Sys Admins and Developers
        • ASM Application Configuration Change Management
          • ASM Application Configuration Change Screens
          • ASM Application Change Workflow Template
      • Configuration Post Go-Live using SDLC
      • Configuring Escalations and Chase
      • Configuring the Data Purge Service
      • Configuring Screens
        • Creating New Screen Sets
        • Screens Available for Configuration using ASM Designer
        • Building Screens in ASM Designer
          • Configuring Fields
          • Creating a Custom Field
          • Deleting & Unlinking Fields
            • ASM System Fields for Call Screens
            • ASM System Fields for Request Screens
            • ASM System Fields for Task Screens
            • ASM System Fields for Approval Screens
            • ASM System Fields for CMDB Item Screens
          • Screen Widgets
            • Data-Grid Widgets
            • Self Service Portal System Widgets
          • Knowledge Article Screens
          • Configuring Message Templates
          • Importing/Exporting Screens
          • Troubleshooting Screens: The Screen's Dead Zone
        • Dynamic Screens
          • Deep Linking Field Data Across Screen Sets
          • Field Calculations
          • Using Rules
          • Adding Images and Progress Indicators to your screens
        • Deleting a Custom Screen
        • Configuring Button Labels
      • Conversation History Widget For Nano
      • Customizing Options for the Self Service Portal
        • Add Me: Set up "Add-Me" for Subscribing to or Following Issues
        • Styling the Self Service Portal
        • Enable Request Correction and Resubmission
      • System Administration Settings
        • Custom Global Profile Fields
        • System Settings Menu
          • Your Organization
          • Partitioning
            • Configuring Partitions
            • Partition Settings
          • System Settings
          • Security Profiles
          • Server Time Zone
            • Storing Time Zone Information
            • Time Zone Settings
          • Defining Working Hours
          • Defining public holidays
          • Reset References
          • System Source Titles
          • Browse Limits
          • Messaging
          • Message Types
            • Message Type Definitions
          • Pager Settings
          • Pager Types
          • Activity Log
          • Stored Procedures
          • System Titles
          • Quick Launch
          • Quick Notes
          • Auditing
            • Administration Audit Trail
          • User and Analyst Search Field Settings
          • Email Header and Footer
        • Security
          • Security Settings
          • Security Settings (Partitioned)
          • IPK Groups
          • Workflow Management Groups
          • Controlling log in
          • Email and Pager Options for IPK and Workflow Groups
        • Security Roles
          • General Access Security Role
            • Admin Tab
            • Timesheets Tab
          • IPK Management Security Roles
            • IPK Management Role: Options Tab
            • IPK Management Security Role: Groups Tab
            • IPK Management Security Role: IPK Streams Tab
            • IPK Management Security Role: IPK Statuses Tab
            • IPK Management Security Role: Forms Tab
            • IPK Management Security Role: Quick Launch Tab
            • IPK Management Security Role: Fwd Groups Tab
          • Workflow Management Security Roles
            • Workflow Management Security Role: Shared Tab
            • Workflow Management Security Role: Requests Tab
            • Workflow Management Security Role: Tasks Tab
            • Workflow Management Security Role: Processes Tab
            • Workflow Management Security Role: Groups Tab
            • Workflow Management Security Role: Request Screen Sets Tab
            • Workflow Management Security Role: Task Screen Sets Tab
            • Workflow Management Security Role: Appr. Screen Sets Tab
            • Workflow Management Security Role: User Approval Screen Sets Tab
            • Workflow Management Security Role: External Supplier Screen Sets Tab
            • Workflow Management Security Role: Closure Task Screen Sets Tab
            • Workflow Management Security Role: Forms Tab
            • Workflow Management Security Role: Template Tab
            • Workflow Management Security Role: Request Quick Launch Tab
            • Workflow Management Security Role: Task Quick Launch Tab
          • Configuration Management Security Roles
            • Configuration Management Security Role: CMDB Items Tab
            • Configuration Management Security Role: People Tab
            • Configuration Management Security Roles: Organizations Tab
            • Configuration Management Security Role: Locations Tab
            • Configuration Management Security Role: Contracts Tab
            • Configuration Management Security Role: Subscriber Groups Tab
            • Configuration Management Security Role: Cost Centers Tab
            • Configuration Management Security Role: Jurisdictions Tab
            • Configuration Management Security Role: Forms Tab
          • Service Level Management Security Roles
            • Service Level Management Security Role: Options Tab
            • Service Level Management Security Role: Forms Tab
          • Availability Management Security Roles
          • Knowledge Management Security Roles
            • Knowledge Management Security Role: Options Tab
            • Knowledge Management Security Role: Content Access Tab
            • Knowledge Management Security Role: Statuses Tab
          • Bulletin Board Security Roles
          • Dashboard Management Security Role
          • Integration Security Role
        • IPK and Workflow
          • Incident, Problem & Known Error (IPK) Management
            • Configuring IPK Settings
            • IPK Settings (Partitioned)
            • Action Type
            • Call Attributes
            • Call History Types
            • Call Impact
            • Call Physical Statuses
            • Call Priority
            • Call Screen Sets
            • Stakeholder Roles
            • Call States
            • Call Status Titles
            • Call Urgency
            • Closure Groups
            • Custom Call Profiles
            • User Survey
            • User Survey Screen Set
            • IPK classes
            • IPK Streams
            • IPK Statuses
            • Link Stream/Status to Call Screen Set
            • Link Type/Stream/Status to Call Screen Set
            • Link Screen Set to Reasons
            • Link Type to Reason
            • Limit Type by IPK Status
            • Link Type to Call Screen Set
            • Priority Matrix
            • Quick Forms
            • Quick Solutions
            • Reasons
            • Call Scripts: Scripting
            • Type Tiers
          • Workflow Management
            • Workflow Management Settings
            • Workflow Attributes
            • Approval Types
            • Request Action Types
            • Request Implementation Profiles
            • Request Implementation States
            • Request Link Types
            • Request Physical Statuses
            • Request Phases (Nano)
            • Request Priority
            • Request Risks
              • Request Risk Assessment
              • Request Impact
              • Request Complexity
              • Request Risk Assessment Matrix
            • Screen Sets for Requests, Tasks and Approvals
            • Request Stakeholder Roles
            • Request Completion Statuses
            • Request Types
            • Task Action Types
            • Task Phases
            • Task Physical Statuses
            • Task Priority
            • Task Status Titles
            • Task Types
            • Workflow Management History Types
            • Request History Filters
            • Workflow Processes
            • Workflow Export and Import - Workflow Porting
            • Linking Approval Screens to Partitions
        • Service Level Management
          • SLM Settings
          • Agreement Attributes
          • Agreement Selection Priority
          • CMDB Selection Priority
          • Agreement Stakeholder Roles
          • Agreement Statuses
          • Exclusion Reasons
          • Agreement Types
          • Event Activity Types
          • Agreement Matrices
          • Measurement Types
          • Payment Types
        • CMDB (Configuration Management Database)
          • CMDB Settings
          • CMDB Service Levels
          • CMDB Item Classes
          • CMDB Item Criticality
          • CMDB Item Physical Statuses
          • CMDB Item Types
          • CMDB Link Status
          • CMDB Link Types
          • Contract Support Type
          • Contract Types
          • Cost Center Category
          • Custom CMDB Profiles
          • Person Profile
          • External Contact Type
          • User VIP Statuses
          • Disposal Methods
          • Financial Statuses
          • Financial Category
          • Freeze Statuses
          • Link Manufacturer to Model Type
          • Manufacturers
          • Model Types
          • Organization Profiles
          • External Supplier Statuses
          • Purchase Method
          • Service Link Types
          • Service Portfolio Statuses
          • Service Cost Types
          • Service Periods
          • Asset Management - Asset Lifecycle Status
          • Asset Management - License Type
          • Asset Management - Transaction Status
          • Self Service Portal Display Categories
          • Stakeholder Roles
          • Auditing Configuration Items
        • Availability
          • Configuring Availability Management
          • Outage Types
          • Schedule Definition
        • Depreciation
          • Batch Run Parameters
          • Depreciation by CMDB Item Type
          • Depreciation Methods
          • Depreciation Schedules
        • Knowledge Bank
          • Knowledge Bank Settings
          • Knowledge Base Types
          • Knowledge Entry Types
          • Knowledge Profiles
          • Knowledge Ratings
          • Knowledge Statuses
          • Knowledge Document Import
        • Bulletin Board
          • Configuring the Bulletin Board
          • Bulletin Board Priorities
          • Bulletin Stakeholder Roles
        • Text Retrieval
          • Common Words
          • Keywords
          • Synonyms
        • Analytics
          • Analytics Settings
          • Classic Syncfusion Dashboard Server Configuration
        • Self Service Portal
          • Self Service Portal Settings
          • Self Service Portal Settings (Partitioned)
          • Self Service Portal Roles
            • Options Tab
            • CMDB Tab
            • Content Access Tab
            • Workflow Templates Tab
            • Call Templates Tab
            • IPK Status Tab
            • Dashboard Management Tab
          • Self Service Portal Systems
          • Self Service Portal My Options
          • Self Service Portal Tables
          • Service Order Status Titles
          • Question Mappings
          • Catalog Promoted Items
          • Suggested Knowledge in the Self Service Portal
          • Creating Custom Pages
          • Link Organization to Portal Key
        • Nano
        • Preview Features/Advanced Options
          • Settings
            • Multi Language
              • Languages
                • Portal Label Language Updates
                • Service Title Language Updates
            • Call Activities
            • Enable Active Directory Mappings to Sub Groups
            • CTI
              • Setting up the Alemba Service Manager CTI
            • SignalR Scale Out Options
            • External Chat tool Integrations
          • Portal Settings
          • Global Search
          • Chat Bot
      • Workflow Template Administration
        • Basic Process for Building a Workflow
          • Task List for Workflow (Request Template) Creation
            • Create a Service Action and Attach a Workflow to it
        • Managing Tasks - Adding Tasks to the Dependency Diagram
          • About Tasks - General
          • Task Types in the Task Palette
            • Defining Request Start Details
            • Creating a Standard Task
            • Create Request Task
            • Creating an Approval Task
            • Creating a User Approval Task
            • Conditional Branching Tasks
              • Defining a Dependency Rule
              • Defining Dependency Actions
            • Creating a Messaging Task
            • Creating a Delay Task
            • Creating a Manage CMDB Task
              • Recursive CMDB Task
              • Adding Transactions to a Manage CMDB task
              • Asset Management Transactions in a Manage CMDB Task
              • Mapping Fields to be Updated by a Transaction
            • Creating an Outbound Action Task
            • Creating an SLM Start Clock/Stop Clock Task
            • Creating an External Supplier Task
            • Creating a Run External Procedure Tasks
            • Creating a Change Window Task
            • Creating a Closure Task
            • Creating an Activation Task
        • Component Workflows
        • Setting Up Amendable Requests
        • Troubleshooting Workflow and Service Action Linking
        • Sharing Parent Request Items with Child Requests
    • Dashboards and Reporting
      • Dashboard Configuration and User Learning Guide
      • Descriptions of Default Reports and Dashboards (SDI Classifications)
        • 8.3 Number of Incidents and Service Requests
        • 8.4 Average Time to Respond
        • 8.6 Average time to resolve incidents or fulfill service requests
        • 8.7 First Contact Incident Resolution and Request Fulfilment Rate
        • 8.8 First Level Incident Resolution and Request Fulfillment Rate
        • 8.9 Reopned Incident Rate
        • 8.10 Backlog Management
        • 8.11 Percentage of hierarchic escalations
        • 8.21 Percentage of Functional Escalations copy
        • 8.23 Average incident resolution time by priority
        • 8.24 Average request fulfilment time by priority
        • 8.25 Average resolution time by incident category
        • 8.26 Average fulfilment time by service request type
        • 8.27 Comparison of service level targets to performance
        • 8.28 Service Desk Knowledge Usage
        • 8.29 Customer Facing Knowledge Usage
        • 8.30 Service Desk Knowledge Quality and effectiveness
        • 8.31 Customer facing knowledge quality and effectiveness
        • 8.33 Monitoring Incidents caused by changes measured against target
        • 8.34 Total cost of service delivery
        • 8.35 Average cost per incident by channel
        • 8.36 Average cost per service request by channel
        • 8.43 Problem records created through proactive problem management
        • 8.44 Incident reduction through problem management
      • Install SDI Reporting Pack
      • Dashboards and Reports (.sydx Files)
      • Connecting to Other Data Sources
      • Sample SQL Queries
      • Migrating your Syncfusion Dashboards to a New Server
    • FAQ
      • Limited Support/End of Life Capabilities
        • Configuration Portability
          • Overview & Best Practices
          • Porting Configuration Data
          • Viewing the Export and Import Logs
        • Server Console
          • Accessing the Server Console
          • Creating a New ASM System
          • Server Console system tasks
          • Customization nodes
          • SQL Server and Table Ownership
          • Updating Scripts
          • ASM Core Registry Keys
        • Concurrent Licensing
          • License Corrals
        • Alemba Classic API
          • Programming with the Classic API
            • WCF Client
          • Code Examples
          • Return Values
          • API Message Types
          • API Lookups
          • API Transactions
            • Availability Transactions
            • Call Transactions
            • CMDB Item Transactions
            • Contract Transactions
            • Cost Center Transactions
            • Jurisdiction Transactions
            • Location Transactions
            • Organization Transactions
            • Person Transactions
            • Subscriber Group Transactions
            • Knowledge Transactions
            • Bulletin Transactions
            • System Transactions
              • Session Transactions
              • Add Note Transactions
              • Attribute Transactions
              • Development Transactions
              • Message Transactions
              • Object Transactions
              • Stakeholder Transactions
            • Workflow Transactions
              • Workflow (Request) Transactions
              • Task Transactions
          • API Classes
          • API WSTester Application
      • Configuration or Customization
  • Integrate
    • Integration Overview
    • Managing Integration
      • Setting Up the Integration Platform
        • Defining Connectors
        • Defining Sources
        • Configuring an Integration Source
        • Resource Mapping
        • Defining Property Transforms
        • Defining Profile Maps
        • Defining Resolution Rules
        • Defining Link Type Mapping
      • Single Sign-On using SAML
        • Integrated Security vs. Single Sign On
        • Technical and Access Requirements
        • Configuring ASM for Single Sign-On
        • Importing Identity Provider Metadata
        • Service Provider Signing Certificate
        • Configuring the Service Provider
        • Exporting Service Provider Metadata
        • Importing Service Provider metadata into the Identity Provider
        • SSO Troubleshooting
        • SSL Binding
        • Creating a Self Signed Certificate
        • Extending the Single Sign-On Connector
      • Configuring Azure Active Directory discovery
      • Azure Multi-factor Authentication
      • Viewing Integration Activity
        • Viewing Integration Log
      • Connectors to ASM Core
        • Connector Matrix
        • Installing Connectors
        • CMDB Connectors
          • Altiris Network Discovery Connector
          • CA Cohesion Connector
          • Centennial Discovery/FrontRange Connector
          • EMC Smarts NCM Connector
            • Service Assurance Manager Connector
          • LANDESK Connector
          • Microsoft Azure Connector
          • Microsoft SCOM Connector
          • Microsoft SMS and SCCM Connector
          • Snow Connector
          • SolarWinds Connector
          • VMware Application Discovery Manager Connector
          • VMware vCenter Configuration Manager Connector
          • VMware vCloud Director Connector
          • vRealize Orchestrator Connector
        • LDAP Connectors to ASM Core
          • Microsoft Active Directory Server Connector
          • Novell eDirectory Server Connector
        • Generic Connectors to ASM Core
          • Email Event Connector
          • External Process Connector
          • Stored Procedure Connector
          • ASM to ASM Connector
          • Jira Connector
            • Developer Notes for the Jira ICNF
          • CSV File Connector
          • MS Azure DevOps Connector
          • Connector Suite for MS SQL Server Tables
          • Resource Databases Connector
            • Tutorial for Configuring the Database Resources Connector
        • Microsoft Alemba ITSM Connector
      • Build your Own Connector
        • Microsoft Entra ID (Azure Active Directory) - Connector Builder
        • Microsoft Intune - Connector Builder
      • Managing the Federated CMDB
        • Managing Scheduled Integration Scans
        • Auditing Configuration Items
      • Managing External Resources
      • Selecting Fields for Mapping
      • Managing Inbound and Outbound Actions
        • Configuring Inbound and Outbound Actions
          • Configuring Outbound Actions
            • Using Outbound Actions
          • Configuring Inbound Actions
        • Inbound or Outbound Action Source Parameters
      • Managing Events
        • Configuring Event Management
          • Event Management Source Parameters
          • Viewing Event Types
          • Managing Event Type Mappings
        • Using Events
      • Webhooks
        • Webhook Payloads
      • Canvas App Widgets
      • Microsoft Teams Chat Integration
      • Microsoft Project Integration
      • Connector Diagnostics
    • API's
      • Alemba RestFul API
        • Alemba API Architecture
        • Installing the Alemba API
        • Logging In to the Alemba API Explorer
        • Navigating the Alemba API Explorer
        • Alemba API Programmers’ Guide
        • Alemba API Programmers' Cookbook
          • Recipes
        • Alemba API Related Database Tables
        • Using API Reporting Views
        • Authentication
          • Configuring Authentication for the Alemba API
          • Configuring Windows Authentication for the Alemba API
          • Configuring Single Sign On using SAML for the Alemba API
      • Azure/ Web API/Logic Apps
      • ASM API Quick Reference Guide
        • Getting Started: The ClientId
        • Postman for Testing
        • Search for Existing Calls
        • Locking and Updating Calls
        • Creating New Calls
  • Earlier Versions of ASM
Powered by GitBook
On this page
  • API structure
  • Languages
  • Authentication
  • Logging in
  • Login Responses
  • Logging out
  • Logout Responses
  • Base RESTful API methods
  • A Programmatically Discoverable API
  • Root Level Information on API Scope
  • ​Metadata
  • HREF Templated
  • Discovering the entity actions
  • Searching
  • Paging
  • $top
  • $orderby
  • $skip
  • $count
  • $inlinecount
  • ​Paging Best Practice
  • Selecting columns​
  • $select
  • Filtering
  • $filter
  • Equality Operators and Methods
  • Boolean data types
  • DateTime data type filters
  • @Now
  • @NowOffset
  • Text and RichText data types
  • Contains
  • StartsWith
  • EndsWith
  • ​Number Data Types
  • Combining Expressions
  • Sorting
  • $order
  • Joining
  • $leftjoin & $innerJoin
  • Case sensitivity
  • Security
  • Handling partitions
  • Data Types
  • Display Types
  • Augmenters
  • Useful Augmenters
  • Error Handling
  • SubStatus Values

Was this helpful?

  1. Integrate
  2. API's
  3. Alemba RestFul API

Alemba API Programmers’ Guide

The RESTful API is built on top of a schema that encompasses the primary data entities in the ASM System.

PreviousNavigating the Alemba API ExplorerNextAlemba API Programmers' Cookbook

Was this helpful?

API structure

Additionally, a number of logical entities have been added that allow similar entities to be grouped together. The hierarchical structure allows sub-entities to inherit common properties, allowing for consistent meaning and behavior.

The structure is indicated in the Alemba API Entity Details Pane in the API explorer.

Languages

The API is platform independent - it can be accessed from any kind of web client, using a range of languages. The API Explorer provides language neutral examples of the structures sent and received as part of a web request/response, for each action, for each entity.

Authentication

The API uses standard oAuth 2.0 authentication, via /alemba.web/oauth/login.

The authentication workflow issues a short-lived (10 minutes) Access Token and a longer-lived (24 hours) Refresh Token on Login. The Access Token is used for authentication on the REST API. The Refresh Token is used to renew the Access Token and therefore maintain the session. The Refresh Token allocates a ASM Core Session and consumes a licence.

The process is illustrated as follows, flowing from the top downwards.

When the Refresh Token is used to renew an Access Token, a new Refresh Token is also issued, and the ASM Core Session is extended. The used Refresh Token becomes invalid and should be discarded. Clients should store the new Refresh Token for subsequent usage. If the ASM Core Session expires or is removed, the Refresh Token will become invalid. If the Refresh Token expires, the ASM Core Session is terminated.

The single use Refresh Token and short lived Access Token ensures that compromised tokens quickly become invalid - protecting the security of individual users, and preventing unauthorized Access Token reuse.

The Access Token must be presented in the Authorization header of the HTTP request:

Authorization: Bearer <Access Token>

Note that the Authorization service supports the following oAuth 2.0 Grant Types:

  • authorization_code – Authenticate using Single Sign On (SSO), for Windows authentication and SAML

  • client_credentials – Authenticate using integrated security for anonymous access to the API, not full access

  • password – Authenticate using a username and password

  • refresh_token – Authenticate using an existing Refresh Token

Logging in

UserName and Password

Below is an example of the code used to login with a username and password.

For more information on client ids, see Configuring Authentication for the Alemba API.

function passwordLogin() {
var args = {
client_id: "clientid",
grant_type: "password",
scope: "scope",
password: "username",
username: "password"
var xhr = $.ajax({
url: 'alemba.web/oauth/login',
type: "POST",
data: args,
contentType: 'application/x-www-form-urlencoded'
});
xhr.done(onGrantSuccess).fail(function (err) { return onGrantFailure(err, "password"); });
return xhr;
}

Access Token

Or, to refresh your access token:

function refreshTokenLogin(refreshToken) {
var args = {
client_id: "clientid",grant_type: "refresh_token",scope: "scope",refresh_token: refreshToken
};
var xhr = $.ajax({
url: 'alemba.web/oauth/login',
type: 'POST',
data: args,contentType: 'application/x-www-form-urlencoded'
});
xhr.done(onGrantSuccess).fail(function (err) {
if (err.status == 401) {
}
else {
onGrantFailure(err, "refresh_token");
}
});
return xhr;
}

scope should be set to session-type:Analyst or session-type:User. It is case sensitive.

Login Responses

For successful Logins the response will be:

{
expires_in: number, // number of seconds until access_token expiry
access_token: string, // token used for data access
refresh_token: string, // token used for access_token renewal
scope: string, // The actual scope of the token
}​

Note that there is a new refresh_token in the response. The old one will no longer work and must be discarded. It is acceptable to renew your access_token before it is due to expire, but you must not do so with every request.

Login Response Errors

If the authorization request is not successful, clients can expect to receive a suitable HTTP response code and JSON formatted data containing an error code.

The response data may also include error_description, which gives the developer a clue as to the precise cause of the failure.


{
error: string, // one of the oauth 2.0 error codes
error_description: string, // a description of the error if applicable
}

In these cases, the response is deliberately vague so as to protect the integrity of the authorization server.

HTTP Status Code

Error Code

Reasons

401

invalid_client

The client_id is incorrect or the client is not enabled

​400

invalid_grant

The credentials are not correct, the user is not allowed to login

If you receive a 401 response, it is because your access token has expired, and you must refresh it using the refresh token. If you receive a 401 response when using a refresh token, you must login again with username and password.

Logging out

You can logout as follows:

function logout() {
var deferred = $.Deferred();
var args = {
token: exports.grant.refresh_token
};
var xhr = $.ajax({
url: 'alemba.web/oauth/logout',
type: "POST",
data: args,
contentType: 'application/x-www-form-urlencoded',
headers: {
"Authorization": "Bearer " + exports.grant.access_token
}
});
xhr.done(function () {
//Logout success
deferred.resolve();
}).fail(function (err) {
switch (err.status) {
case 404:
deferred.resolve();
break;
case 400:
deferred.reject("Invalid token");
break;
case 401:
refreshTokenLogin(exports.grant.refresh_token).done(function () {
//We've successfully refreshed the access token
//Now we can try to invalidate the refresh token again
logout().done(function () {
deferred.resolve();
}).fail(function (err) {
//Logout is still not working.
//The session may still be active and may still be consuming a license.
//The session can be terminated by an administrator from logon control, so this error should be reported
deferred.reject(err);
});
}).fail(function () {
//If you cant log in its because the refresh token has expired.
//This can be considered a successful logout
deferred.resolve();
});
break;
case 403: //Not allowed, probably because the refresh token is not related to the access token
default:
deferred.reject(err.responseJSON.Message);
break;
}
});
return deferred.promise();
}​

Logout Responses

Logout will give one of the following responses:

Response
Meaning

200

Logged out successfully

400

Token invalid or missing

401

Not authorized because it’s not been possible to validate your ownership of the refresh token. In this case you must refresh the access token and try again

403

That refresh token doesn’t belong to you

404

The refresh token is valid but has already been removed. Maybe you logged in elsewhere

Base RESTful API methods

The following HTTP verbs are used by the API to perform the listed actions.

Create
POST

Read

GET

Update

PUT

Delete

DELETE

The API supports delete where it is appropriate, including delete for attachments and person images (avatars)

A Programmatically Discoverable API

The API can be used to return information about itself, in the form of hypermedia – machine readable descriptions and links to further similar information, allowing a developer to progressively explore the breadth and depth of the API for themselves. What is more, these descriptions are used by the API itself, guaranteeing that this “documentation” is always current.

Root Level Information on API Scope

For example, to discover root level information on the scope of the API, invoke

http://localhost/alemba.api/api?$metadata&$options

Note that this response will also be returned for any request which does not specify a resource, for example:

GET http://localhost/alemba.api
GET http://localhost/alemba.api/api
GET http://localhost/alemba.api/api/v1

​Metadata

The metadata will be returned in JSON format and will contain links to the metadata for top level entities exposed by the API, for example:

{
"_links": {
"Approval": [
{
"_self": "api:v1/approval/$metadata"
}
],
"Call": [
{
"_self": "api:v1/call/$metadata"
}
],
...
},
"description": "A description of the API, the links at this level and the ResourceDescriptor response type."
}

​All metadata responses may include the following properties:

children

An array of descendant types for the current response

Call may list children including Incident

The metadata for each child only includes "_self"

description

A description of the current metadata response

name

The name of the entity that is the subject of the metadata response

properties

An array of property descriptions for the subject entity. These properties provide the minimum information required to understand the data model and basic constraints.

Each entry in the array may include the following properties:

name

The name of the entity property

displayName

The default display name of the property. This could be used in table column headers or form fields

type

A description of the data type of this property. The type property is a complex type which has the following properties:

displayTypes

The suggested display types for this property

dataType

The type of data this property represents

class

The kind of property

description

A description of the purpose of the property

usage

Internal when the property is used for internal business logic, otherwise Public

isKey

The property represents the unique identifier (primary key) for the entity

noSearch

When true, this property is not supported in searches

defaultValue

An indication of the default value for this property

length

The maximum length of this field. Text fields only

uppercase

When true, this indicates that the Text value will be capitalized.

Non capitalized input may cause validation errors in a future release.

status

Indicates the current release status of the subject entity. "Alpha", "Beta", "GA"

_actions

A hash map of action name and an array of action metadata

_context

A reference to the entity metadata of a record or of the metadata of the parent of the subject entity

_links

A hash map of name and an array of link metadata. These links must be requested using the http verb GET

_self

A reference to the current response link and action metadata will always include a link to _self and will often include an "href" property

HREF Templated

The "href" may be templated, as denoted by the syntax {id}. The templated values must be replaced by the client.

{id} in "api:v1/call/{id}" should be replaced with the Ref of a call.

{id} always indicates the primary key field for the target entity. All other entity properties may also be referenced in the template. e.g. {Partition} where Partition is the name of the property in the entity referenced by "_context".

"_context" and "_self" will always define a medialink to an API resource. For brevity, the links are prefixed with "api:"

Clients should replace this prefix with the actual API base url

Given an api base url of http://web-server/core-system/alemba.api/api, api:v1/call/$metadata should be interpreted as http://web-server/core-system/alemba.api/api/v1/call/$metadata

All API medialinks can be invoked using the $options suffix.

These links can then be followed to explore further details about the entity, what it is and what it can do.

All API entities support simple and predictable RESTful actions.

"api:v1/call" supports GET for searching and POST for create
"api:v1/call/1​" supports PUT for update and GET to get that instance of a call.

Discovering the entity actions

Many entities also support more complex actions, such as forward.

These actions are typically accessed using "api:v1/call/1/forward"

Details of the required inputs and supported HTTP method can be found in the metadata for that action.

For example the Call Create action metadata can be accessed with

http://localhost/alemba.api/api/call/$create?$options

This metadata gives you info about the Create action, including a list of mandatory and optional properties and parameters. $create in the above example can be substituted with any action that is supported by the Call entity.

What is more, you can use the same principles not just as an aid to programming, but at runtime too. The metadata that is returned about a specific object contains links for the list of actions for that object instance in its current state. (An exception is the Search action, which will only return links to the relevant Get action for each record.) For example you will only see the Reopen action if a Call is in a closed state.

Searching

The Rest API supports expressive searching of most entities

The query parameters and syntax applies to all Search actions for all entities.​

To start, it is possible to simple request a resource using HTTP GET.

​GET api:v1/call

This will return a reference to all accessible calls in JSON format

{
"results": [
{
"_context": "api:v1/call/$metadata",
"_self": "api:v1/call/3"
},
{
"_context": "api:v1/incident/$metadata",
"_self": "api:v1/incident/4"
}
],
"_self": "api:v1/call?$top=2147483647",
"__count": 275
}

The response contains the following properties

  • "results": This is an array of search results. Each result will always include a _context url (so you know what it is) and a _self url (so you know how to get that item).

  • ​"_self": This is a url refering to the current response​

Notice that the _self url includes a query string parameter

$top=2147483647​

The search actually ran without any row limit. It will try to return every row (accessible to the current session).

This query string parameter is added to the response as a hint.

Paging

The Rest API supports flexible paging of search results.

$top

$top accepts a positive signed integer value (Int32) and is used to define a row count.

// SGET api:v1/call​?$top=30

This will limit the response to the top 30 records. If you don’t explicitly specify the row count, then it will default to $top=100.

$orderby

$orderby accepts a comma separated list of property names and optional sort direction (see $select for more details on property names) and is used to define the order of the results​

GET api:v1/call​?$orderby=Ref​

​This will return all Calls ordered by Ref

By default the orderby clause will be applied in ascending order, but this can be overridden

//GET api:v1/call​?$orderby=Ref​ asc

​​​This will return all Calls ordered by Ref in ascending order

GET api:v1/call​?$orderby=Ref​ desc

This will return all Calls ordered by Ref​ in descending order

$skip

$skip accepts a positive signed integer value (Int32) and is used to define a number of rows to skip

GET api:v1/call​?$top=30

This will limit the response to the top 30 records

and GET api:v1/call​?$skip=30&$top=30

This will skip the first 30 records and return the next 30 (ie rows 31 to 60)

These parameters can be combined (in any order) to control page size and contents

GET api:v1/call​?$top=30&$skip=30&$orderby=Ref​ desc

This will return the top 30 Calls ordered by Ref in descending order

$count

The API also supports counting, which can be used to calculate the total number of pages

$count must be set to true and is used to instruct the api to return a count only

GET api:v1/call​?$count=true

This will return a text/plain response containing a number which represents the total number of rows.

$inlinecount

Alternatively, $inlinecount can be used to have the count be returned with a set of results

GET api:v1/call​?$top=30&$inlinecount=true
{
"results": [
{
"_context": "api:v1/call/$metadata",
"_self": "api:v1/call/3"
},
{
"_context": "api:v1/incident/$metadata",
"_self": "api:v1/incident/4"
}
],
"_self": "api:v1/call?$top=2147483647",
"__count": 275
}

Note that "__count" is included in the response body.​

​Paging Best Practice

Use of these paging features is critical for individual client and application wide performance and should be utilized by all API consumers for all searches.

Even where it is assumed that there are only a handful of records.

Using $inlinecount results in two executions of the database query; one to get the count; and one to get the result set. Therefore it is important that this parameter is not added to every request.​

Selecting columns​

The Rest API supports configurable column selection in search results.

$select

$select accepts a comma separated list of property paths to include in the search results

// SGET api:v1/call​?$select=Ref,Description​

​This instructs the API to include Ref and Description in the search results​

{
"results": [
{
"Ref": 3,
"Description": "Microsoft Windows 2000 needs to be installed across all client machines.",
"_context": "api:v1/call/$metadata",
"_self": "api:v1/call/3"
},
{
"Ref": 4,
"Description": "Cannot access intranet.",
"_context": "api:v1/incident/$metadata",
"_self": "api:v1/incident/4"
}
],
"_self": "api:v1/call?$select=Ref,Description&$top=2147483647"
}

Note that as well as retrieving properties from the entity, you can directly retrieve properties from related entities. This is extremely powerful.

In the Classic WCF API, you would first need to get the raw foreign key ref from the main entity and then do a lookup on the related one, or you would have to write your own custom query, including joining objects and ensuring that the related object is not locked.

The RESTful API is built on an underlying schema that takes care of these complexities and allows you to get the data you need in the simplest possible way.

In fact you can traverse the entity relationships as far as you need, so getting a call priority’s name can be achieved with:

GET api:v1/call​?$select=Ref,Description​​,Priority.Name
{
"Ref": 4,
"Description": "Cannot access intranet."​,
"Priority": {
"Name": "Priority 3",
"_context": "api:v1/call-priority/$metadata",
"_self": "api:v1/call-priority/3"
},
"_context": "api:v1/incident/$metadata",
"_self": "api:v1/incident/4"
}

Linked Fields from Linked Relations

Notice that the linked entity includes metadata links. This also applies to linked fields from linked relations.

GET api:v1/call​?$select=Ref,Description​​,Service.Location.Name

​Returns

{
"Ref": 4,
"Description": "Cannot access intranet.",
"Service": {
"Location": {
"Name": "San Francisco",
"_context": "api:v1/location/$metadata",
"_self": "api:v1/location/9"
},
"_context": "api:v1/service/$metadata",
"_self": "api:v1/service/1"
},
"_context": "api:v1/incident/$metadata",
"_self": "api:v1/incident/4"
}

Property paths in $select can be aliased using a prefix to simplify the response

GET api:v1/call​?$select=Ref,Description​​,LocationName:Service.Location.Name​
{
"Ref": 4,
"Description": "Cannot access intranet.",
"LocationName": "San Francisco",
"_context": "api:v1/incident/$metadata",
"_self": "api:v1/incident/4"
}

$select will also accept named Extension Augmenters

GET api:v1/call​?$select=Ref,@AssignmentState

This will add the computed assignment state to the response ​​

{
"Ref": 4,
"AssignmentState": "Assigned to Me",
"_context": "api:v1/incident/$metadata",
"_self": "api:v1/incident/4"
}

To help with orientation during development, $select will also accept *. This will return all properties for the entity.

$select=*

Best Practice $select=*

$select=* is only intended for development and should not be used in production.

Selecting values from extension fields is supported, but carries a significant overhead and so should be avoided.

Filtering

​The Rest API supports expressive filtering of search results.

$filter

$filter accepts a C# LINQ style predicate which is translated to parameterized SQL and applied as a search filter

GET api:v1/call​?$filter=Priority==1

This would return all accessible calls where the Priority is equal to 1

Equality Operators and Methods

All data types support basic equality comparison

==

Is equal to

=

Is equal to

!=

Not equal to

Binary data types support basic equality comparison but in practice, this can only be used to compare the property value with null.

GET api:v1/call/1/attachment​?$filter=BinaryData!=null

Boolean data types

Boolean data types support basic equality operators

When comparing with true or false, the right hand side of a boolean property equality expression can be omitted.

Binary equality expressions can also be negated with !

GET api:v1/person​?$filter=IsLoggedIn==true

is equivalent to

GET api:v1/person​?$filter=IsLoggedIn

or

GET api:v1/person​?$filter=IsLoggedIn==false

is equivalent to

GET api:v1/person​?$filter=!IsLoggedIn

DateTime data type filters

DateTime data type filters must be used with one of the applicable augmenters

GET api:v1/call​?$filter=CreatedDate>@DateTime(2017-01-01T00:00:00.000+1)

This will return all Calls which were created after Midnight on January 1st 2017 (UTC+1)

Note that the date value must be expressed in ISO8601 format

@Now

The @Now augmenter can be used to compare a date value with the current time.

GET api:v1/call​?$filter=CreatedDate==@Now

This is most useful where a query will be designed and then subsequently reused.

@NowOffset

The @NowOffset augmenter can be used to compare a date value with the current time and an offset expressed in days hours and minutes

GET api:v1/call​?$filter=CreatedDate>@NowOffset(0,-1,-30)

This will return Calls created in the last 0 days, 1 hours and 30 minutes (in the last hour and a half).

As with all filters, the expressions can be combined using logical And (&&) and Or (||) operators

GET api:v1/call​?$filter=CreatedDate>=@DateTime(2017-01-01T00:00:00.000+1)&&CreatedDate<=@NowOffset(0,0,-30)​​

This will return Calls created between Midnight on January 1st 2017 (UTC+1)​ and half an hour ago.

Dates do not have to be defined in UTC format, but MUST include the timezone.

If no timezone is supplied, dates are assumed to be in local server time.

Text and RichText data types

Text and RichText data types support basic equality and can also be used with some string comparison methods

Contains

The Contains method can be used to match records where a string property contains a word or phrase

GET api:v1/call​?$filter=ShortDescription.Contains("email")

StartsWith

The StartsWith method can be used to match records where a string property starts with a word or phrase​

GET api:v1/call​?$filter=ShortDescription.StartsWith("email")

EndsWith

​The EndsWith method can be used to match records where a string property ends with a word or phrase​​

GET api:v1/call​?$filter=ShortDescription.EndsWith("email")

As with all filters, the expressions can be combined using logical And (&&) and Or (||) operators​

GET api:v1/call​?$filter=hortDescription.Contains("email")||ShortDescription.StartsWith("outlook")

​Number Data Types

Number data types support more complex equality comparison operators

>

Greater than

<

Less than

>=

Greater than or equal to

<=

Less than or equal to

GET api:v1/call​?$filter=Number1>=3

Combining Expressions

Filter expressions can be combined using logical And (&&) and Or (||) operators​​ and can be grouped using ​parentheses ( and )

GET api:v1/call​?$filter=((Number1>=3​||Number2==1)&&(Priority==3||Priority==1))||(CreatedDate>@NowOffset(0,0,-30)​​​&&@IsAssignedToMe)

​Note that query string parameter values must be url encoded

GET api:v1/call​?$filter=((Number1%3E%3D3%E2%80%8B%7C%7CNumber2%3D%3D1)%26%26(Priority%3D%3D3%7C%7CPriority%3D%3D1))%7C%7C(CreatedDate%3E%40NowOffset(0,0,-30)%E2%80%8B%E2%80%8B%E2%80%8B%26%26%40IsAssignedToMe)

Sorting

$order

The API supports sorting using $order, and you can use several qualifiers, as illustrated in the following examples.

$orderby=FirstName would sort the result by the FirstName property in descending (a-z) order.

$orderby=FirstName desc would also sort the result by the FirstName property in descending (a-z) order.

$orderby=FirstName asc would sort the result by the FirstName property in ascending (z-a) order.

It is also possible to specify multiple order properties:

$orderby=FirstName, LastName asc would sort the result by the FirstName property in descending (a-z) order and then sort by the LastName property in ascending (z-a) order, e.g. Andrew Anderson, John Smith, John Jones

Joining

$leftjoin & $innerJoin

You can use $leftJoin and $innerJoin to link to entities that are not already linked as part of the schema definition. This is the case with entities that have multi-column keys e.g. CallHistory, which has a composite key of Ref and LastHistoryOrder. Once you create such a join, you will want to refer to properties of that joined entity, so part of the definition of the join is an alias for that join, in the format

Alias:TargetEntity(TargetProperty==SourceProperty)

… where the clause in brackets can occur multiple times. For example:

&$leftJoin=LastAction:CallHistory(TicketId==Ref && Order==LastHistoryOrder)

You can then use the alias in your select clause just as if it were a property of the entity with a Data Type that is the target entity, e.g. LastAction.Description.

Note that this technique should be used sparingly, because as with extension fields the relationship is not indexed and so may result in reduced performance.

Case sensitivity

Everything after any of the $ functions above is case sensitive.

Security

Handling partitions

Where entities are Partitioned, the results returned are automatically limited to those in partitions accessible to the current session. Therefore it is not necessary to apply partition filtering, however if desired, a specific partition can be specified in one of two ways.

  • $filter=Partition==1 will return records where the Partition Ref equals 1. The filter will be applied even if the entity is not partitioned

  • $partition=1 will work as above, but will only apply the partition filter if the entity is actually partitioned. This will also account for variable partitioning of Asset types, e.g api/v1/asset?$partition=1 will return a combination of Services, ConfigurationItems, etc. where Service may be partitioned, but ConfigurationItem is not.

$partition=1 is the recommended method.

Data Types

The following data types are exposed by the API:

RESTful API

Equivalent in Classic (WCF) API

Binary

Byte Array

Boolean

Boolean, Yes/No

DateTime

Date/Time

Integer

Integer

Long

Long

Float

Float

Double

Double

Decimal

Decimal

Short

Short

Text

String

RichText

String

Data types can also be entities. For example, the Service properties on a Call has a Data Type of Service (Lookup in the metadata json). This means that it contains the key value of the associated object – click on the circle icon in the API Explorer to see what that is. (This is equivalent to the WCF data type “Lookup”.)

Note that Boolean property standardizes underlying data inconsistencies. Across various tables, flags are stored as "Y", "YES", "T", "TRUE", "ON", "1", "P", "A" – for all of these, the API will return true, and conversely will convert true to appropriate values on PUT and POST.

Display Types

The following table shows the types that are supported, and the related data types.

Display Type

Data Type

Checkbox

Boolean

DatePicker

DateTime

DateTimePicker

DateTime

Lookup

entity

MultiLookup

entity

MultiSelect

entity

ListBox

entity

Numeric

Integer, Long, Float, Double, Decimal, Short

Password

Text

RichText

RichText

Select

entity

Text

Text

TextArea

RichText

TieredSelect

Entity

Augmenters

The API includes a set of inbuilt functions that simplify the retrieval of complex data using Search actions. This allows API users to easily select, view and manipulate data using business-level concepts, rather than dealing with the low level data that sometimes needs gathering from many sources to provide that information. These functions are known as augmenters. These can be used as virtual variables, for example in a filter clause. So if you only want to see calls that have breached, you would say:

SGET http://…/api/v1.0/call?$filter=@SlmBreached

There are a number of different types of Augmenters:

  • Condition Augmenters – for use with $filter, encapsulating complex search conditions (including joins).

  • Function Augmenters – provide additional functionality to the queries and are entity-independent

  • Token Augmenters – return simple values for use in query filters and are entity-independent

  • Extension Augmenters – computed properties, properties selected from other tables with join, etc.

Useful Augmenters

The table below lists some of the most useful augmenters. They are used for all entity types, and apply to calls, requests and tasks.

To find the other augmenters appropriate for an entity, examine the entity in the API explorer.

Augmenter
Application
Example

@IsDeleted

Entities that have been deleted

$filter=@IsDeleted

$filter=!@IsDeleted

@DateTime

Creates a value from a date/time string in ISO 8601 format, for use in query filters

$filter=LoggedDate > @DateTime(2000-01-01T00:00:00.000Z)

@Guid

Creates a value from a GUID string, for use in query filters

$filter=Id = @Guid(75f7a7d5-652f-4e30-bd92-dc6e9594b28b)

@Now

Current date

$filter=LoggedDate <= @Now

@NowOffset

Offsets the current date by days, hours and minutes Filter logged date within last 7 days, 2 hours, 30 minutes

$filter= LoggedDate > @NowOffset(-7,-2,-30)

@OrganizationId

Current users Organization id

$filter=User.OrganizationId == @OrganizationId

$filter=User.Organization == @OrganizationId

$filter=User.Organization.Ref == @OrganizationId

@UserId

Current user's id

$filter=User == @UserId

$filter=UserId == @UserId

$filter=User.Ref == @UserId

Error Handling

The API will return errors with an appropriate HTTP Status Code and a message with the following structure:

Message:
string - This is the error message

Type:

string - This is the type of the error – usually just the Exception type name

SubStatus:

string - This is a string which will help to narrow down the reason for the HTTP Status Code

SubStatus Values

Current SubStatus values are:

None, ResourceNotFound, RecordNotFound, LinkedRecordNotFound, NotSupported, NotImplemented, NotAllowed

Programmatically, you should rely upon the HTTP Status Code and the SubStatus.

The HTTP Status Codes that are explicitly returned are: 200, 304, 400, 401, 403, 404, 405, 415 and 500.

Often a 404 response will include a message body (as described above). This is so that you can tell the difference between a badly formed url and a non-existent record.

displayTypes

The suggested display types for this property

dataType

The type of data this property represents

class

The kind of property

description

A description of the purpose of the property

usage

Internal when the property is used for internal business logic, otherwise Public

isKey

The property represents the unique identifier (primary key) for the entity

noSearch

When true, this property is not supported in searches

defaultValue

An indication of the default value for this property

length

The maximum length of this field. Text fields only

uppercase

When true, this indicates that the Text value will be capitalized.

Non capitalized input may cause validation errors in a future release.

status

Indicates the current release status of the subject entity. "Alpha", "Beta", "GA"

_actions

A hash map of action name and an array of action metadata

_context

A reference to the entity metadata of a record or of the metadata of the parent of the subject entity

_links

A hash map of name and an array of link metadata. These links must be requested using the http verb GET

_self

A reference to the current response link and action metadata will always include a link to _self and will often include an "href" property