SysAid REST API Details
    • 12 May 2025
    • PDF

    SysAid REST API Details

    • PDF

    Article summary

    🚀 Try out the New SysAid Developer Site (Beta)

    Want to explore our latest API experience? Join the beta for early access to the new SysAid Developer Site.

    Get hands-on with the new:

    • User API

    • Service Record API

    • Group APIs

    👉  Join the Beta Program

    Login

    Parameters

    Field

    Description

    account_id

     The user’s account ID.

    Example Value: cmdb

    user_name

    Required: The user’s name

    Example Value: sysaid

    password

    Required: The user’s password, url encoded (utf-8).

    Example Value: password123

    mobile_app

    Should be set to true for mobile app.

    Example Value: true

    version

    The app version

    device

    The device model

    os

    The OS type

    os_version

    The OS version

    push_id

    The id for push notifications

    Returns
    An access key, the SysAid version and the basic information of the logged-in user.

    Sample JSON return value

    {
    “language”:”en”,
    “sysaid_version”:””,
       “date_format”:”yyyymmdd hh:MM:ss”
       “user”: {
             “id”:”2”,
                      â€œname”:”ILIENT\Barby”,
                      â€œinfo”: [{“key”:”display_name”,”value”:”Barbara Straisend”},
                                 {“key”:”email_address”, “value”:”barbara@gmail.com”},
                                 {“key”:”building”, “value”:”1C”}]
                  }
    }
    

    Return values definition

    Field

    Description

    logged_in

    Whether the user is authenticated to this app. true/false.

    user_id

    The user unique id

    language

    Returns the user’s default language, as defined in SysAid server

    error_msg

    Optional. An error message to display to the user in case of failure

    sysaid_version

    The SysAid server version

    Important

    Upon successful login, the API consumer needs to retrieve the JSESSIONID cookie from the Response Header and submit it in all consequent API Request Headers.

    Users

    Get Users List

    Get a list of users in SysAid.

    Parameters

    Field

    Description

    view

    A SysAid view which defines the available fields (Mobile view is called 'Mobile').

    fields

    A list of fields to return, separated by commas. If sent together with the view parameter, returns both view's fields and the requested fields.

    type

    The user type to retrieve. Available values are: admin, user, and manager. Defaults to all user type.

    offset

    Retrieved users count is limited (see limit parameter). This parameter specifies the offset (start point) from which to retrieve values (e.g. 25). Defaults to 0. Zero base.

    limit

    The maximum number of users to retrieve per request. Defaults to 500 (configurable).

    Returns
    A list of users. For each user returns the user ID, user Name, and information as defined in the view and/or fields parameters. If none of them exist, return full user information.

    Sample JSON return value

    [
        {
    “id”:”1”,
           “name”:”ILIENT\Johnny”,
           “info”: [{“key”:”display_name”,”value”:”John Doe”},
                      {“key”:”email_address”, “value”:”john@gmail.com”},
                      {“key”:”building”, “value”:”1A”}]
       },
       {
    “id”:”2”,
           “name”:”ILIENT\Barby”,
           “info”: [{“key”:”display_name”,”value”:”Barbara Straisend”},
                      {“key”:”email_address”, “value”:”barbara@gmail.com”},
                      {“key”:”building”, “value”:”1C”}]
       }
    ]
    

    Return values definition

    Field

    Description

    Field

    Description

    id

    The user id

    name

    The user name

    info

    User information fields

    Get User

    Get information on the specified user

    Parameters

    Field

    Description

    view

    A SysAid view which defines the available fields (mobile view is called ‘Mobile’).

    fields

    List of fields to return, comma separated. If sent together with view parameter, returns both view's fields and the requested fields.

    Returns
    The user ID, user Name, and information as defined in the view and/or fields parameters. If none of them exist, return full user information.

    Sample JSON return value for /users/1?view=Mobile

     {
      â€œid”:”1”,
       “name”:”ILIENT\Moshiko”,
       “info”: [{“key”:”display_name”,”value”:”Moshe Cohen”},
                   {“key”:”first_name”,”value”:”Moshe”},
                   {“key”:”last_name”,”value”:”Cohen”},
                   {“key”:”phone”,”value”:”+972.3.6711554”},
                   {“key”:”cell_phone”,”value”:”+972.54.5453525”},
                   {“key”:”email_address”, “value”:”moshe@gmail.com”},
                   {“key”:”cubic”, “value”:”38”}]
       }
    

    Return values definition

    Field

    Description

    id

    The user id

    name

    The user name

    info

    User info fields, as defined in the User Form > Mobile Tab in SysAid.

    Search Users

    Get list of users in SysAid, according to a search criteria

    Parameters

    Field

    Description

    query

    The search criteria (Required)

    view

    A SysAid view which defines the available fields (the mobile view is called ‘Mobile’).

    fields

    List of fields to return, comma separated. If sent together with view parameter, returns both view’s fields and the requested fields.

    type

     The users type to retrieve. Available values are: {admin, user, manager}. Defaults to all user types.

    offset

     Retrieved users count is limited (see limit parameter). This parameter specifies the offset (start point) from which to retrieve values (e.g. 25). Defaults to 0. Zero base.

    limit

     The maximum number of users to retrieve per request. Defaults to 500 (configurable).

    sort

    One or more fields to sort by, from the fields that were fetched by the request. Defaults to ‘calculated_user_name’ field/

    dir

     Sort order: ascending or descending. available values: asc/desc. Default is ‘asc’. Relevant only when sort parameter is sent.

    Returns
    A list of users that matched the search criteria. For each user returns the user ID, user Name, isAdmin, isSysAidAdmin, isManager, and information as defined in the view and/or fields parameters. If none of them exist, return full user info.

    Sample JSON return value for /users/search?query=Jo&fields=display_name,email_address&limit=2

     [
    { “id”:”1”,
    “name”:”ILIENT\Johnny”,
    “isAdmin”: true,
    “isSysAidAdmin”: false,
    “isManager”: true,
    “info”: [
    {“key”:”display_name”,”keyCaption”:”Name”,
    ”value”:”John Doe”, ”valueCaption”:”John Doe”},
    {“key”:”email_address”, ,”keyCaption”:”Email Address”,
    “value”:”john@gmail.com”,
    “valueCaption”:”john@gmail.com”},
    {“key”:”building”,”keyCaption”:”Building”,
    “value”:”1B”, ”valueCaption”:”1B”}]
    },
    {
    “id”:”2”,
    “name”:”ILIENT\Barby”,
    “isAdmin”: true,
    “isSysAidAdmin”: false,
    “isManager”: true,
    “info”: [
    {“key”:”display_name”,”keyCaption”:”Name”,
    ”value”:”Barbara Straisend”, ”valueCaption”:”Barbara Straisend”},
    {“key”:”email_address”, ,”keyCaption”:”Email Address”,
    “value”:”barbara@gmail.com”, “valueCaption”:”barbara@gmail.com”},
    {“key”:”building”,”keyCaption”:”Building”,
    “value”:”1C”, ”valueCaption”:”1C”}]
    }
    ]
    

    Return values definition

    Field

    Description

    id

    The user id

    name

    The user name

    isAdmin

    Whether this user is an administrator

    isSysAidAdmin

    Whether this user is a SysAid administrator

    isManager

    Whether this user has manager permissions

    info

    User information fields array, according to requested fields (view/fields/all).

    info.key

    The id of the information field

    info.keyCaption

    The caption of the information field’s key

    info.value

    The field’s value.

    info.valueCaption

    The field’s value’s caption. A String representation of the value for display.

    Upload user's photo

    Uploads the specified user’s photo.

    Payload:

    Multiple data including the file

    Parameters

    Field

    Description

    file

    Multiplart file part

    Note

    File size limit: 500KB

    Get User Permissions

    Get user permissions

    Parameters

    None

    Returns
    User’s full permissions set.

    Sample JSON return value or /users/1/permission

    {
        â€œid”:”1”,
        â€œname”:”ILIENT\Moshiko”,
        â€œpermissions”: [{“key”:”userPermissionUserSelfService”,”value”:”false”},
                            {“key”:”userPermissionHelpDeskView”,“value”:”true”},
                            {“key”:”userPermissionHelpDeskChangeType”,“value”:”All”},
                            {“key”:”userPermissionCMDBViewType”,“value”:”All”},
                            {“key”:”userPermissionInventoryViewGroup”,“value”:”\”},
                             
.]
    }
    

    Return values definition

    Field

    Description

    id

    The user id

    name

    The user name

    permissions

    List of key-value pairs with all available permissions

    Get a User's Permission

    Check a specific user permission

    Parameters

    None

    Returns
    User’s permission for the requested permission id

    Sample JSON return value for /users/1/permission/userPermissionUserSelfService

     {“key”:”userPermissionUserSelfService”,”value”:”false”}
    

    Return values definition

    Field

    Description

    key

    The requested permission ID

    value

    The permission value

    Filters

    Get Filters List

    Get list of available filters and their values.

    Parameters

    Field

    Description

    view

    A SysAid view which defines the available filters. Defaults to SysAidMobile.

    fields

    List of filter fields to return. If not specified, returns all.

    offset

    Filter values count is limited (see limit parameter). This parameter specifies the offset (start point) from which to retrieve values (e.g. 25). Defaults to 0.

    limit

    The maximum number of filter values to retrieve per request. Defaults to 500 results (configurable).

    Returns
    A list of all filters. For each filter returns the fields requested in the fields parameter. If not specified, returns full filter information.

    Sample JSON return value for /filters?p=SysAidMobile

    [
      {
    “id”:”status”,
    “type”:”list”,
           “values”:[{“id”:”1”, “caption”:”closed”},
                        {“id”:”2”,“caption”:”awaiting”},
                        {“id”:”3”,“caption”:”reopened”}],
           “metadata”: {”limit”:”20”, “offset”:”0”,”total”:”3”}
      },
      {
    “id”:”Priority”,
    “type”:”list”,
           “values”:[{“id”:”1”, “caption”:”High”},
                        {“id”:”2”,“caption”:”Urgent”}],
           “metadata”: {”limit”:”20”, “offset”:”0”,”total”:”2”}
      },
      ...
    ]
    

    Return values definition

    Field

    Description

    id

    The filter ID, as defined in SysAid DB. Always returned. No need to specify in the Fields list.

    type

    The data type of this filter.
    Available data types are: text, numeric, boolean, date, list, nested, custom.

    values

    Array of  filter values.

    values.id

    The filter value’s ID

    values.caption

    The filter value’s caption

    metadata

    Additional metadata on the filter values. Available only when the values field is returned. See fields parameter.

    metadata.limit

    The maximum number of filter values per request

    metadata.offset

    The start index of filter values

    metadata.total

    The total number of filter values

    Get Filter

    Returns the information & available values for the specified filter.

    Parameters

    Field

    Description

    id

    The filter ID (Required)

    view

    A SysAid view which defines the available fields and filters. Defaults to SysAidMobile.

    offset

    Filter values count is limited (see limit parameter). This parameter specifies the offset (start point) from which to retrieve values (e.g. 25). Defaults to 0.

    limit

    The maximum number of filter values to retrieve per request. Defaults to 500 results (configurable).

    Returns
    The filter information, according to the requested view.

    Sample JSON return value for /filters/status?view=SysAidMobile

    {
      â€œid”:”status”,
      â€œtype”:”list”,
      â€œvalues”: [
        {“id”:”1”,“caption”:”Closed”},
        {“id”:”2”,“caption”:”Awaiting”}
        ],
     “metadata”: {”limit”:”20”, “offset”:”0”,”total”:”2”}
    }
    

    Return values definition

    Field

    Description

    id

    The filter ID, as defined in SysAid DB. Always returned. No need to specify in fields list.

    type

    The data type of this filter. Optional.
    Available data types are: text, numeric, boolean, date, list, nested, custom.

    values

     An array of  filter values

    values.id

    The filter value’s id

    values.caption

    The filter value’s caption

    metadata

    Additional metadata on the filter values

    metadata.limit

    maximum number of filter values per request

    metadata.offset

    The start index of filter values

    metadata.total

    The total number of filter values

    Service Requests

    Get Service Request List

    Returns a list of available service records (SRs). Number of SRs to return can be controlled by the Offset, Limit, and Type parameters. Returned SRs can be filtered by the available filters. Each service record, Includes the fields according to the View and Fields parameters. If none are specified, all SR fields are returned.

    Parameters

    Field

    Description

    view

    A SysAid view which defines the available fields in the list. If view is not specified, check for the fields parameter. If none is specified, returns all fields.

    fields

    List of fields to return. If specified together with the view parameter, return all view's fields together with the specified fields parameter. If none specified, return all SR fields.

    type

    The requested service record type. Available values are {incident,request,problem,change,all}. Multiple values can be sent, comma-separated.
    I.e: 
&type=incident,request.
    If not specified, it defaults to all views created on the incident list.
    Note: If the View in your SysAid App was created on the All list view, to access it from the APIs you must provide this parameter with the value 'all'.

    offset

    SR count is limited (see limit parameter). This parameter specifies the offset (start point) from which to retrieve values (e.g. 25). Defaults to 0.

    limit

    The maximum number of SRs to retrieve per request. Defaults to 500 results (configurable).

    ids

    The list of SR IDs to return, comma separated

    archive

    Whether to return archived SRs. Value can be 1 or 0

    sort

    One or more fields to sort by. Available fields are those that were fetched by the request.

    dir

    Sort order: ascending or descending. Available values: asc/desc. Default is ‘asc’.  Relevant only when sort parameter is sent.

    {filters}

    List of key-value parameters with {filter.id} as the key. and {filter.values.id} as the value. I.e.: 
&status=19&request_user=235.

    Multiple values can be sent, comma-separated. I.e.: 
&status=4,5

    Important

    • User-related fields return the user’s ID, for additional user information, call user service.

    • Dates should be sent as milliseconds in UTC/GMT (since January 1, 1970).

    • In case of a specific date match, send only this date. For example:

      • Match a date: &due_date=1398935657000

    • If a range of dates or from/to is required, send a 2-objects array of dates. If one of them is not available, set to 0. For example:

      • Between dates: &due_date=1398935657000,1399313657000

      • From date: &due_date=1398935657000,0

      • To date: &due_date=0,1399313657000

    Returns
    A list of service records. For each SR, it returns the SR ID, user permissions to update/delete/archive the SR, and information fields as defined in the view and/or fields parameters. If none of them exist, returns full user information.

    Sample JSON return value for /sr?view=SysAidMobile&fields=type,computer_id&limit=2

    [
    {
     “id”:”5433”,
     “canUpdate”:”true”,
     “canDelete”:”false”,
     “canArchive”:”false’,
     “info”: [
       {“key”:”title”,”keyCaption”:”Title”,”value”:”basic Service Request”,
                                                     ”valueCaption”:”basic Service Request”},
       {“key”:”insert_time”,”keyCaption”:”Request Time”,“value”:”13975648000”,   
                                                          valueCaption”:”2014-04-01 11:46:48”},
       {“key”:”request_user”,”keyCaption”:”Request User”,  
                        â€œvalue”:”leo@law.com”,”valueCaption”:”Leonardo Gonzales”},
       {“key”:”description”,”keyCaption”:”Description”, “value”:”Prezados Amos”,  
                                                             “valueCaption”:”Prezados Amos”},
      {“key”:”type,”keyCaption”:”Service Record Type”, “value”:”1”,
                                                            â€œvalueCaption”:”Service Request”},
        {“key”:”computer_id”,”keyCaption”:”Asset ID”,“value”:”none”,
                                                                          â€œvalueCaption”:”none”}]
    },
    {
      â€œid”:”5669”,
      â€œcanUpdate”:”true”,
      â€œcanDelete”:”false”,
      â€œcanArchive”:”false’,
      â€œinfo”: [
       {“key”:”title”,”keyCaption”:”Title”,”value”:”RelatĂłrio de ocorrĂȘncia”,
                                                   ”valueCaption”:”RelatĂłrio de ocorrĂȘncia”},
       {“key”:”insert_time”,”keyCaption”:”Request Time”,“value”:”1392026000”,   
                                                         valueCaption”:”2013-05-28 11:12:50”},
       {“key”:”request_user”,”keyCaption”:”Request User”,  
                        â€œvalue”:”leo@law.com”,”valueCaption”:”Leonardo Gonzales”},
       {“key”:”description”,”keyCaption”:”Description”, “value”:”RelatĂłrio de
                                  ocorrĂȘncia”,“valueCaption”:”RelatĂłrio de ocorrĂȘncia”},
       {“key”:”type,”keyCaption”:”Service Record Type”, “value”:”1”,
                                                            â€œvalueCaption”:”Service Request”},
       {“key”:”computer_id”,”keyCaption”:”Asset ID”,“value”:”DELL-3PXZ15J”,
                                                                â€valueCaption”:”DELL-3PXZ15J”}]
     }
    ]
    

    Return values definition

    Field

    Description

    id

    The user ID

    canUpdate

    Whether the user has permission to update this SR

    canDelete

    Whether the user has permission to delete this SR

    canArchive

    Whether the user has permission to archive this SR

    info

    User info fields. An array of key-value fields, representing the SR information

    info.key

    The ID of the info field

    info.keyCaption

    The caption of the info field’s key

    info.value

    The field’s value

    info.valueCaption

    The field’s value caption. A string representation of the value for display.

    Get Service Request Form

    Returns the information for the specified service record.

    Parameters

    Field

    Description

    id

    The service record ID (Required)

    view

    A SysAid view (tab) which defines the available fields in the service record form

    fields

    List of fields to return, comma separated. If sent together with view parameter, returns both view’s fields and the requested fields.

    Returns
    The service record ID, user permissions to update/delete/archive the SR, and info fields according to the requested view and/or fields parameters. If none specified, return full service record information. Each info field contains metadata like: whether the field is mandatory, default value, is it editable etc.

    Sample JSON return value for /sr/273?fields=type,archive,update_time,status

    {
        â€œid”:”273”,
        â€œcanUpdate”:”true”,
        â€œcanDelete”:”false”,
        â€œcanArchive”:”false’,
        â€œinfo”: [{“key”:”sr_type”,
                     ”keyCaption”:”Service Record Type”,
                     ”value”:”1”,    
                     ”valueCaption”:”Service Request”,
                     ”mandatory”:true,
                     ”editable”:true,
                     ”type”:”list”,
                     ”defaultValue”:null},
                   {“key”:”archive”,
                     ”keyCaption”:”Archive”,
                     ”value”:0,
                     ”valueCaption”:”0”,
                     ”mandatory”:false,
                     ”editable”:true,
                     ”type”:”boolean”,
                     ”defaultValue”:0},
                      {“key”:”update_time”,
                        â€keyCaption”:”Modify Time”,
                        â€value”:1391756438000,
                        â€valueCaption”:”2014-05-22 11:09:44”,
                    â€mandatory”:false,
                    â€editable”:true,
                    â€type”:”date”,
                    â€defaultValue”:null},
                  {“key”:”status”,
                    â€keyCaption”:”Status”,
                    â€value”:1,                                                                   
                    â€valueCaption”:”New”,
                    â€mandatory”:true,
                    â€editable”:true,
                    â€type”:”list”,
                     ”defaultValue”:”New”}
    }
    

    Return values definition

    Field

    Description

    id

    The service record ID

    canUpdate

    Whether the user has permission to update this SR

    canDelete

    Whether the user has permission to delete this SR

    canArchive

    Whether the user has permission to archive this SR

    info

    Service record info fields as defined in the SR Form view and/or fields requested, or all available fields if none specified.

    info.key

    The ID of the info field

    info.keyCaption

    The caption of the info field’s key

    info.value

    The field’s value

    info.valueCaption

    The field’s value caption. A String representation of the value for display.

    info.mandatory

    A boolean that specifies whether this field is mandatory

    info.editable

    A boolean that specifies whether this field is editable or read-only

    info.defaultValue

    The default value for this field if a specified value is not available (null)

    info.type

    The field’s type. See available field types in Appendix A.

    Search Service Request

    Returns a list of service requests (SR), that matched the search criteria. Number of SRs to return can be controlled by offset, limit, and type parameters. Returned SRs can be filtered by filters (See Filter Service). Each Service Request, includes the fields according to view and/or fields parameters. If none specified, all SR fields are returned.

    Parameters

    Field

    Description

    query

    The search criteria.

    view

    A SysAid view (tab) which defines the available fields in the service record form

    fields

    List of fields to return. If specified together with the view parameter, return all view's fields together with the specified fields. If none specified, return all SR fields.

    type

    The service record type. Available values are {incident,request,problem,change,all}. If not specified, returns incident type.

    offset

    SR count is limited (see limit parameter). This parameter specifies the offset (start point) from which to retrieve values (e.g. 25). Defaults to 0.

    limit

    The maximum number of SRs to retrieve per request. Defaults to 500 results (configurable).

    archive

    Whether to return archived SRs. Value can be 1 or 0

    sort

    One or more fields to sort by. Available fields are those that were fetched by the request.

    dir

    Sort order: ascending or descending. Available values: asc/desc. Default is ‘asc’.  Relevant only when sort parameter is sent.

    {filters}

    List of key-value parameters with {filter.id} as the key. and {filter.values.id} as the value.
    I.e.: 
&status=19&request_user=235.

    Multiple values can be sent, comma-separated. I.e.: 
&status=4,5

    Important

    • User-related fields return the user’s ID, for additional user information, call user service.

    • Dates should be sent as milliseconds in UTC/GMT (since January 1, 1970).

    • In case of a specific date match, send only this date. For example:

      • Match a date: &due_date=1398935657000

    • If a range of dates or from/to is required, send a 2-objects array of dates. If one of them is not available, set to 0. For example:

      • Between dates: &due_date=1398935657000,1399313657000

      • From date: &due_date=1398935657000,0

      • To date: &due_date=0,1399313657000

    Sample JSON /sr/search?query=54&view=SysAidMobile&limit=2

    [
    {
    “id”:”5433”,
    “canUpdate”:”true”,
    “canDelete”:”false”,
    “canArchive”:”false’,
    “info”: [
    {“key”:”title”,”keyCaption”:”Title”,”value”:”basic Service Request”, ”valueCaption”:”basic Service Request”},
    {“key”:”insert_time”,”keyCaption”:”Request Time”,“value”:”13975648000”, valueCaption”:”2014-04-01 11:46:48”},
    {“key”:”request_user”,”keyCaption”:”Request User”, “value”:”leo@law.com”,”valueCaption”:”Leonardo Gonzales”},
    {“key”:”description”,”keyCaption”:”Description”, “value”:”Prezados Amos”, “valueCaption”:”Prezados Amos”},
    {“key”:”sr_type,”keyCaption”:”Service Record Type”, “value”:”1”, “valueCaption”:”Service Request”}]
    },
    {
    “id”:”5469”,
    “canUpdate”:”true”,
    “canDelete”:”false”,
    “canArchive”:”false’,
    “info”: [
    {“key”:”title”,”keyCaption”:”Title”,”value”:”RelatĂłrio de ocorrĂȘncia”, ”valueCaption”:”RelatĂłrio de ocorrĂȘncia”},
    {“key”:”insert_time”,”keyCaption”:”Request Time”,“value”:”1392026000”, valueCaption”:”2013-05-28 11:12:50”},
    {“key”:”request_user”,”keyCaption”:”Request User”, “value”:”leo@law.com”,”valueCaption”:”Leonardo Gonzales”},
    {“key”:”description”,”keyCaption”:”Description”, “value”:”RelatĂłrio de ocorrĂȘncia”,“valueCaption”:”RelatĂłrio de ocorrĂȘncia”},
    {“key”:”sr_type,”keyCaption”:”Service Record Type”, “value”:”1”, “valueCaption”:”Service Request”}]
    }
    ]
    

    Return values definition

    Field

    Description

    id

    the user ID

    canUpdate

    Whether the user has permission to update this SR

    canDelete

    Whether the user has permission to delete this SR

    canArchive

    Whether the user has permission to archive this SR

    info

    Service record information fields as defined in the SR Form view and/or fields requested, or all available fields if none specified.

    info.key

    The ID of the info field

    info.keyCaption

    The caption of the info field’s key

    info.value

    The field’s value

    info.valueCaption

    The field’s value caption. A tring representation of the value for display.

    Update Service Request

    Update a service request

    Parameters

    Field

    Description

    id

    The service record ID

    Payload:
    A JSON string representing the service cords with the updated fields only.

    Field

    Description

    id

    The service record ID

    info

    Service record information fields as defined in the SR Form view and/or fields requested, or all available fields if none specified.

    info.key

    The ID of the info field

    info.value

    The field’s value

    Sample JSON input for/sr/273, update the status, add a note, change assigned to user & modify time

    {
    “id”:”273”,
    “info”:
    [{“key”:”update_time”, ”value”:1391756438000},
    {“key”:”status”, ”value”:2},
    {“key”:”notes”,”value”:[
    {“userName”:”sysaid”,”createDate”:1391756438000,”text”:”Note 123”}
    ]},
    {“responsibility”:66}]
    }
    

    Special Service Record Information Fields

    Field

    Description

    notes

    An array of Note objects. Each Note object consists of:

    {“userName”:<user_name>,”createDate”:<creation date milliseconds>,”text”:<text>}

    due_date

    Long milliseconds in UTC/GMT (since January 1, 1970). insert_time is a read only field.

    problem_type

    Updates all 3 levels of categories.

    A concatenation of the categories, with underscore delimiter: <problem_type>_<problem_sub_type>_<third_level_category>.

    To update category- send only <problem_type>

    To update sub category - send both <problem_type>_<problem_sub_type>

    To update all 3 levels, send

    <problem_type>_<problem_sub_type>_<third_level_category>

    The following object type fields can be modified through a different API call:

    • Messages

    • attachments

    • links

    • activities

    Read-only fields: history, chats, department, CI relations, computer_name

    Count Service Request

    Returns the number of SRs that are compatible with the provided filters.

    Parameters

    Field

    Description

    {filters}

    List of key-value parameters with {filter.id} as the key. and {filter.values.id} as the value.
    I.e.: 
&status=19&request_user=235.

    Multiple values can be sent, comma-separated. I.e.: 
&status=4,5

    Returns

    Sample JSON return value for**/sr/count?computer_id=1

    {
    "count": 128
    }
    

    Return values definition

    Field

    Description

    count

    Number of SRs that are compatible with the provided filters

    Close Service Request

    Close a service record. Sets the service record status to the default Close status, as defined in the Help Desk settings.

    Parameters

    Field

    Description

    id

    The service record ID

    Payload:
    A JSON string representing the solution.

    Field

    Description

    solution

    The solution

    Sample JSON input for /sr/6/close
    {“solution”:”restart the computer
”}

    Get Service Request Template

    Get a new service record template.

    Parameters

    Field

    Description

    view

    A SysAid view which defines the available fields in the form. If view is not specified, check for the fields parameter. If none is specified, returns all fields.

    fields

    List of fields to return. If specified together with the view parameter, return all view's fields together with the specified fields. If none are specified, return all SR fields.

    type

    The service record type. Available values are {incident,request,problem,change,all}. If not specified, returns incident type.

    template

    The service record template ID, according to SR type. Defaults to the first/default template.

    Returns
    The service record information, according to the requested view and/or fields parameters. If none are specified, return full service record information. Each information field contains metadata like: whether the field is mandatory, default value, is it editable, etc.

    Sample JSON return value for /sr/template?type=incident&template=39

    {
      â€œid”:”0”,
      â€œinfo”: [{“key”:”request_user”,
                  â€keyCaption”:”Request user”,
                     ”value”:149,    
                     ”valueCaption”:”shani1”,
                     ”mandatory”:true,
                     ”editable”:true,
                     ”type”:”list”,
                     ”defaultValue”:””},
                   {“key”:”impact”,
                     ”keyCaption”:”Impact”,
                     ”value”:”Low”,
                     ”valueCaption”:”Low”,
                     ”mandatory”:false,
                     ”editable”:true,
                     ”type”:”list”,
                     ”defaultValue”:null},
                      {“key”:”status”,
                        â€keyCaption”:”Status”,
                        â€value”:”New”,
                        â€valueCaption”:”New”,
                    â€mandatory”:true,
                    â€editable”:true,
                    â€type”:”list”,
                    â€defaultValue”:2},
                  {“key”:”title”,
                    â€keyCaption”:”Title”,
                   ”value”:”Cannot connect to a Wi-Fi network”,                                                                   
                    â€valueCaption”:”Cannot connect to a Wi-Fi network”,
                    â€mandatory”:true,
                    â€editable”:true,
                    â€type”:”text”,
                     ”defaultValue”:””}]
    }
    

    Return values definition

    Field

    Description

    id

    0 represents a template/new service record

    info

    Service Record information fields as defined in the SR Form view and/or fields requested, or all available fields if none specified.

    info.key

    The ID of the info field

    info.keyCaption

    The caption of the info field’s key

    info.value

    The field’s value

    info.valueCaption

    The field’s value caption. A tring representation of the value for display.

    info.mandatory

    A boolean that specifies whether this field is mandatory

    info.editable

    A boolean that specifies whether this field is editable or read-only

    info.defaultValue

    The default value for this field if a specified value is not available (null)

    info.type

    The field’s type. See available field types in Appendix A.

    Create Service Request

    Create a new service record and returns the newly created service record.

    Parameters

    Field

    Description

    view

    A SysAid view which defines the available fields in the form. If view is not specified, check for the fields parameter. If none is specified, returns all fields.

    fields

    List of fields to return. If specified together with the view parameter, return all view's fields together with the specified fields. If none are specified, return all SR fields.

    type

    The service record type. Available values are {incident,request,problem,change,all}. If not specified, returns incident type.

    template

    The service record template ID, according to SR type. Defaults to the first/default template.

    Payload:
    A JSON string representing the new service record.

    Field

    Description

    info

    Service record’s updated info fields. Each field contains a key-value pair.

    info.key

    The ID of the info field

    info.value

    The info field value

    Sample JSON input - set SR status, assigned to, due date and add a note

    {
      â€œinfo”: [{“key”:”due_date”, ”value”:1391756438000},
                {“key”:”status”, ”value”:2}
                {“key”:”problem_type”,“value”:“UserWorkstation_PC_Password” }
                {“key”:”notes”,”value”:[
                {“userName”:”sysaid”,”createDate”:1391756438000,”text”:”Note 123”}
                 ]},
                 {“responsibility”:66}]
    }
    

    Special Service Record Information Fields

    Field

    Description

    notes

    An array of Note objects. Each Note object consists of:

    {“userName”:<user_name>,”createDate”:<creation date milliseconds>,”text”:<text>}

    due_date

    Long milliseconds in UTC/GMT (since January 1, 1970). insert_time is a read only field.

    problem_type

    Use this key to add all the categories in a single value. For example: “value”:Cat1_SubCat1_ThirdCat1”. For more information, see the input example above.

    Returns
    The new service record information, according to the requested view and/or fields parameters. If none is specified, return the full service records information. Each info field contains metadata like: whether the field is mandatory, default value, is it editable, etc.

    Sample JSON return value for POST /sr?view=Mobile&type=incident&template=39

    {
      â€œid”:”45”,
      â€œinfo”: [{“key”:”request_user”,
                  â€keyCaption”:”Request user”,
                     ”value”:149,    
                     ”valueCaption”:”shani1”,
                     ”mandatory”:true,
                     ”editable”:true,
                     ”type”:”list”,
                     ”defaultValue”:””},
                   {“key”:”impact”,
                     ”keyCaption”:”Impact”,
                     ”value”:”High”,
                     ”valueCaption”:”High”,
                     ”mandatory”:false,
                     ”editable”:true,
                     ”type”:”list”,
                     ”defaultValue”:null},
                      {“key”:”status”,
                        â€keyCaption”:”Status”,
                        â€value”:”New”,
                        â€valueCaption”:”New”,
                    â€mandatory”:true,
                    â€editable”:true,
                    â€type”:”list”,
                    â€defaultValue”:2},
                  {“key”:”title”,
                    â€keyCaption”:”Title”,
                    â€value”:”Cannot connect to a Wi-Fi network”,                                                               
                    â€valueCaption”:”Cannot connect to a Wi-Fi network”,
                    â€mandatory”:true,
                    â€editable”:true,
                    â€type”:”text”,
                     ”defaultValue”:””}]
    }
    

    Return values definition

    Field

    Description

    id

    0 represents a template/new service record.

    info

    Service record info fields as defined in the SR Form view and/or fields requested, or all available fields if none specified.

    info.key

    The ID of the info field

    info.keyCaption

    The caption of the info field’s key

    info.value

    The field’s value.

    info.valueCaption

    The field’s value caption. A String representation of the value for display.

    info.mandatory

    A boolean that specifies whether this field is mandatory

    info.editable

    A boolean that specifies whether this field is editable or read-only

    info.defaultValue

    The default value for this field if a specified value is not available (null)

    info.type

    The field’s type. See available field types in Appendix A.

    After the service record is created, the following Object type fields can be added to the new service record through their different API calls:

    • Messages

    • Attachments

    • Links

    • Activities

    Delete Service Request

    Delete one or more service records

    Parameters

    Field

    Description

    ids

    A list of comma separated SR IDs to delete.

    Add Service Request Link

    Add a link to a service record

    Parameters

    Field

    Description

    id

    The service record ID.

    Payload
    A JSON string representing the link.

    Field

    Description

    name

    The new link name.

    link

    The link URL.

    Sample JSON input for /sr/6/link
    {"name":"link2","link":"http://google.co.il"}

    Delete Service Request Link

    Delete a link from a service record.

    Parameters

    Field

    Description

    id

    The service record id.

    Payload
    A JSON string representing the link name to delete

    Field

    Description

    name

    The deleted link name

    Sample JSON input for /sr/6/link
    {"name":"link2"}

    Add Service Request Attachment

    Add an attachment to a service record.

    Parameters

    Field

    Description

    id

    The service record ID.

    Payload
    File Multipart/Form data.

    Delete Service Request Attachment

    Delete an attachment from a service record.

    Parameters

    Field

    Description

    id

    The service record ID.

    Payload
    A JSON string representing the attachment file ID to delete.

    Field

    Description

    fileId

    The deleted attachment file ID.

    Sample JSON input for /sr/6/attachment
    {"fileId":"111934645_312638760"}

    Add Service Request Activity

    Add an activity to a service record.

    Parameters

    Field

    Description

    id

    The service record ID.

    Payload
    A JSON string representing the new activity.

    Field

    Description

    userId

    The new activity’s user name.

    fromTime

    The activity's start time.

    toTime

    The activity's end time.

    description

    The description of the new activity.

    Sample JSON input for /sr/6/activity
    {"userId":"sysaid","fromTime":"1378501200000","toTime":"1378846800000","description":"This is an activity from API"}

    The total time is automatically calculated.

    Delete Service Request Activity

    Delete an activity from service record

    Parameters

    Field

    Description

    id

    The service record ID.

    Payload
    A JSON string representing the deleted activity ID.

    Field

    Description

    id

    The deleted activity ID.

    Sample JSON input for /sr/6/activity
    {"id":2}

    Send Message From Service Request

    Send a message from a Service Record form.

    Parameters

    Field

    Description

    id

    The service record ID (Required)

    method

    The Send method. Can be email, SMS, broadcast, or IM (instant message). Defaults to email.

    addAttachmentToSr

    Whether to add message attachments to a service record. The value can be either true or false. The default is true.

    addSrDetails

    Whether to add the service record details to the message. The value can be either true or false. The default is true.

    Payload
    Multipart data including one or more files attached to the message, and a JSON string representing the new message.

    Field

    Description

    file

    Multipart file part. Can be one or more files to attach to the message.

    message

    A non-encoded JSON string representing the new message.

    message.fromUserId

    The sender user ID.

    message.toUsers

    The IDs of the users in the To field. A comma-separated string, with users IDs. If there's a group, the group ID should be surrounded by [ ].
    I.e.: “1,23,22,45,[3],67”.

    message.ccUsers

    The IDs of the user in the CC field. A comma-separated string, with users IDs. If there's a group, the group ID should be surrounded by [ ]. I.e.: “1,23,22,45,[3],67”.

    message.msgSubject

    The message subject.

    message.msgBody

    The message body.

    Sample JSON input for /sr/6/message

    {"fromUserId":"124","toUsers":"1,140,123,124","ccUsers":"3,125,127,[11]","msgSubject":"This is a message from API","msgBody":"Hello Hello Hello ......."}
    

    Note

    If the list of To and/or CC users include invalid email addresses or addresses that belong to disabled users, these addresses are ignored and written to the logs as invalid. Other valid addresses will receive the mail.

    Action Items

    Get action items

    Get a list of action items

    Parameters

    Field

    Description

    view

    A SysAid view which defines the available fields. If view is not specified, check for the fields parameter. If none is specified, returns all fields.

    fields

     List of fields to return. Comma-separated. If sent together with the view parameter, return both view's fields together with the specified fields. If none is specified, return all SR fields.

    type

    The service record type. Available values are {incident,request,problem,change,all}. If not specified, returns incident type.

    ids

    A list of comma-separated SR IDs to return their action items.

    {filters}

    List of key-value parameters with {filter.id} as the key. and {filter.values.id} as the value. I.e.: 
&status=19&request_user=235.

    Multiple values can be sent, comma-separated. I.e.: 
&status=4,5

    The Status filter can also be set to "active" to retrieve only active action items.

    staticFilterId

    The Static filter from the scoreboard.

    archive

    Whether to return archived action items. Values can be 1 or 0.

    query

    The search criteria

    offset

    Action items count is limited (see limit parameter). This parameter specifies the offset (start point) from which to retrieve values (e.g. 25). Defaults to 0. Zero based.

    limit

    The maximum number of action items to retrieve per request. Defaults to 500 (configurable).

    sort

    One or more fields to sort by, from the fields that were fetched by the request.

    dir

    Sort order: ascending or descending. Available values: asc/desc. Default is ‘asc’. Relevant only when sort parameter is sent.

    Returns
    A list of action item

    Sample JSON return value

    [{
    “id”:”24”,
    “tabName”:”1”,
    “subTabName”:”2”,
    “hasApproved”:”true”,
    “hasEmptyRequred”:”false”
    },
    {
    “id”:”25”,
    “tabName”:”1”,
    “subTabName”:”2”,
    “hasApproved”:”false”,
    “hasEmptyRequred”:”false”
    }]
    

    Count Action Items

    Count action items

    Parameters

    Field

    Description

    view

    A SysAid view which defines the available fields. If view not specified, check for fields parameter. If not specified, returns all fields.

    fields

    A list of fields to return. Comma separated. If sent together with the view parameter, it returns both view's fields and the requested fields. If not specified, returns all fields.

    type

    The requested service record type. Available values are {incident,request,problem,change,all}. If not specified, returns incident type.
    Multiple comma-separated values can be sent. I.e.: 
&type=incident,request. If not specified, returns all.

    ids

    A list of comma-separated SR IDs to return their action items.

    {filters}

    List of key-value parameters with {filter.id} as the key. and {filter.values.id} as the value.
    I.e.: 
&status=19&request_user=235.

    Multiple values can be sent, comma-separated. I.e.: 
&status=4,5

    staticFilterId

    The Static filter from the scoreboard.

    archive

    Whether to return archived SRs. Values can be 1 or 0.

    query

    Search criteria

    Returns
    The number of action items.

    Sample JSON return value

    {
    "count":24
       }
    

    Approve Action Items

    Approve action items

    Parameters

    Field

    Description

    id

    The action item ID

    Reject Action Items

    Reject action items

    Parameters

    Field

    Description

    id

    The action item ID.

    Complete Action Items

    Complete action items

    Parameters

    Field

    Description

    id

    The action item ID.

    Reopen Action Items

    Reopen action items

    Parameters

    Field

    Description

    id

    The action item ID.

    Assets

    Get Assets List

    Get a list of assets in SysAid.

    Parameters

    Field

    Description

    view

    A SysAid view which defines the available fields (Mobile view is called ‘SysAidMobileAssets’).

    fields

     List of fields to return. Comma-seperated. If sent together with the view parameter, return both view's fields together with the specified fields.

    offset

    Retrieved Assets count is limited (see limit parameter). This parameter specifies the offset (start point) from which to retrieve values (e.g. 25). Defaults to 0. Zero based.

    limit

    The maximum number of assets to retrieve per request. Defaults to 500 (configurable).

    Returns
    A list of assets. For each asset returns the asset ID, asset name, group name and information as defined in the view and/or fields parameters. If none of them exist, return full asset information.

    Sample JSON return value for /asset?fields=computer_type,ip_address,serial&limit=2

    [
        {
    “id”:”497db453:147bee7ec09:-7ff2”,
           “name”:”ISA-VCHER-DW7”,
           “group”:”\”,
           “info”: [{“key”:”computer_type”,”key_caption”:”Type”,  
                        â€value”:”Workstation”,”value_caption”:”Workstation”},
                      {“key”:”ip_address”,”key_caption”:”IP Address”,  
                        â€œvalue”:”10.1.10.131”,“value_caption”:”10.1.10.131”},
                      {“key”:”serial”,“key_caption”:”Serial”,
                        â€œvalue”:”3PXZ15J”, “value_caption”:”3PXZ15J”}]
       },
       {
    “id”:”9F38X-RDDTC-RHRXT-GX6XR-DDXRJ”,
           “name”:”VISTA-X64”,
           “group”:”\”,
           “info”: [{“key”:”computer_type”,”key_caption”:”Type”,  
                        â€value”:”Workstation”,”value_caption”:”Workstation”},
                      {“key”:”ip_address”,”key_caption”:”IP Address”,  
                        â€œvalue”:”10.1.10.30”,“value_caption”:”10.1.10.30”},
                      {“key”:”serial”,“key_caption”:”Serial”,
                        â€œvalue”:”4JS8L2J”, “value_caption”:”4JS8L2J”}]
       }
    ]
    

    Return values definition

    Field

    Description

    id

    The asset ID

    name

    The asset name

    group

    The asset’s group name

    info

    Additional asset info fields

    info.key

    The ID of the info field

    info.keyCaption

    The caption of the info field’s key

    info.value

    The field’s value

    info.valueCaption

    The fields' values' caption. A String representation of the value for display.

    Get Asset

    Get information on the specified asset.

    Parameters

    Field

    Description

    view

    Optional: A SysAid Asset Form view that defines the available fields.

    fields

    Optional: A list of fields to return. Comma separated. If sent together with the view parameter, it returns both view's fields and the requested fields.

    Returns
    The asset ID, asset name, group name, and information as defined in the view and/or fields parameters. If none of them exist, return full asset information.

    Sample JSON return value for /asset/497db453:147bee7ec09:-7ff2?fields=computer_type,ip_address,serial

    {
    “id”:”497db453:147bee7ec09:-7ff2”,
           “name”:”ISA-VCHER-DW7”,
           “group”:”\”,
           “info”: [{“key”:”computer_type”,”key_caption”:”Type”,  
                        â€value”:”Workstation”,”value_caption”:”Workstation”},
                      {“key”:”ip_address”,”key_caption”:”IP Address”,  
                        â€œvalue”:”10.1.10.131”,“value_caption”:”10.1.10.131”},
                      {“key”:”serial”,“key_caption”:”Serial”,
                        â€œvalue”:”3PXZ15J”, “value_caption”:”3PXZ15J”}]
       }
    

    Return values definition

    Field

    Description

    id

    The asset ID

    name

    The asset name

    group

    The asset’s group name

    info

    Additional asset info fields

    info.key

    The ID of the info field

    info.keyCaption

    The caption of the info field’s key

    info.value

    The field’s value

    info.valueCaption

    The fields' values' caption. A String representation of the value for display.

    Search Asset

    Get list of assets in SysAid, that matched the search criteria

    Parameters

    Field

    Description

    query

    The search criteria (Required)

    view

    A SysAid Asset Form view that defines the available fields.

    fields

    A list of fields to return. Comma-separated. If sent together with the view parameter, it returns both view's fields and the requested fields.

    offset

    Retrieved Assets count is limited (see limit parameter). This parameter specifies the offset (start point) from which to retrieve values (e.g. 25). Defaults to 0. Zero based.

    limit

    The maximum number of assets to retrieve per request. Defaults to 500 (configurable).

    Returns
    A list of assets that match the search criteria. For each asset the command returns the asset ID, asset name, group name, and information as defined in the view and/or fields parameters. If none of them exist, return full asset info.

    Sample JSON return value for /asset/search?query=DW7&fields=computer_type,ip_address,serial&limit=2

    [
    {
    “id”:”497db453:147bee7ec09:-7ff2”,
    “name”:”ISA-VCHER-DW7”,
    “group”:”\”,
    “info”: [{“key”:”computer_type”,”key_caption”:”Type”, ”value”:”Workstation”,”value_caption”:”Workstation”},
    {“key”:”ip_address”,”key_caption”:”IP Address”, “value”:”10.1.10.131”,“value_caption”:”10.1.10.131”},
    {“key”:”serial”,“key_caption”:”Serial”, “value”:”3PXZ15J”, “value_caption”:”3PXZ15J”}]
    }
    ]
    

    Return values definition

    Field

    Description

    id

    The asset ID

    name

    The asset name

    group

    The asset’s group name

    info

    Additional asset info fields

    info.key

    The ID of the info field

    info.keyCaption

    The caption of the info field’s key

    info.value

    The field’s value

    info.valueCaption

    The fields' values' caption. A String representation of the value for display.

    Lists

    Get All Lists

    Get all available lists and their values.

    Parameters

    Field

    Description

    entity

    A SysAid entity by which to retrieve the available lists. Defaults to SR. For a list of available entities, see Appendix B.

    fields

    A comma-separated list of fields to return. Available fields to return are: id (always returned), caption, and values.

    offset

    Retrieved values count is limited. This parameter specifies the offset (start point) from which to retrieve values (e.g. 25). Defaults to 0. Zero base.

    limit

    The maximum number of list values to retrieve per request. Defaults to 500 (configurable).

    Returns
    The available lists, including their values, per entity type. Defaults to SR.

    Sample JSON return value for list?entity=sr

    {
     { “id”:”location”,
        â€œcaption”:”Location”,
        â€œvalues”: [{“id”:”1”,”caption”:”Loc1”},
                       {“id”:”2”,”caption”:”Loc2”}]
     },
    { “id”:”impact”,
        â€œcaption”:”Impact”,
        â€œvalues”: [{“id”:”1”,”caption”:”Very High”},
                       {“id”:”2”,”caption”:”Low”}]
     },
    { “id”:”urgency”,
        â€œcaption”:”Urgency”,
        â€œvalues”: [{“id”:”1”,”caption”:”Urgent”},
                       {“id”:”2”,”caption”:”Normal”}]
     },
    { “id”:”priority”,
        â€œcaption”:”Priority”,
        â€œvalues”: [{“id”:”1”,”caption”:”Highest”},
                       {“id”:”2”,”caption”:”High”},
                       {“id”:”3”,”caption”:”Low”}]
     },
    { “id”:”change_category”,
        â€œcaption”:”Classification”,
        â€œvalues”: [{“id”:”1”,”caption”:”Minor”},
                       {“id”:”2”,”caption”:”Significant”},
                       {“id”:”3”,”caption”:”Major”}]
     },
    { “id”:”survey_status”,
        â€œcaption”:”Survey Status”,
        â€œvalues”: [{“id”:”1”,”caption”:”Not Sent”},
                       {“id”:”2”,”caption”:”Sent”}]
     },
    { “id”:”sr_type”,
        â€œcaption”:”Service Record type”,
        â€œvalues”: [{“id”:”1”,”caption”:”Change”},
                       {“id”:”2”,”caption”:”Problem”},
                       {“id”:”3”,”caption”:”Incident”},
                       {“id”:”4”,”caption”:”Request”}]
     },
    { “id”:”responsibility”,
        â€œcaption”:”Assigned to”,
        â€œvalues”: [{“id”:”3”,”caption”:”SysAid”},
                       {“id”:”124”,”caption”:”QA-LAB\Administrator”}]
     },
    { “id”:”status”,
        â€œcaption”:”Status”,
        â€œvalues”: [{“id”:”1”,”caption”:”Open”},
                       {“id”:”2”,”caption”:”Closed”}]
     },
    { “id”:”company”,
        â€œcaption”:”Company”,
        â€œvalues”: [{“id”:”1”,”caption”:”Company 1”},
                       {“id”:”2”,”caption”:”Company 2”}]
     },
    { “id”:”department”,
        â€œcaption”:”Department”,
        â€œvalues”: [{“id”:”1”,”caption”:”IT”},
                       {“id”:”2”,”caption”:”R&D”}]
     },
    { “id”:”agreement”,
        â€œcaption”:”Agreement”,
        â€œvalues”: [{“id”:”1”,”caption”:”DEFAULT SLA”},
                       {“id”:”2”,”caption”:”Agreement 2”}]
     },
    { “id”:”source”,
        â€œcaption”:”Source”,
        â€œvalues”: [{“id”:”1”,”caption”:”Administrator Portal”},
                       {“id”:”2”,”caption”:”Agent”},
                       {“id”:”3”,”caption”:”Email”},
                       {“id”:”4”,”caption”:”Chat”}]
     },
    { “id”:”cust_list1”,
        â€œcaption”:”SR Custom list 1”,
        â€œvalues”: [{“id”:”1”,”caption”:”Cust Val 1”},
                       {“id”:”2”,”caption”:”Cust Val 2”}]
     },
    { “id”:”cust_list2”,
        â€œcaption”:”SR Custom list 2”,
        â€œvalues”: [{“id”:”1”,”caption”:”Cust Val 3”},
                       {“id”:”2”,”caption”:”Cust Val 4”}]
     },
    }
    

    Return values definition

    Field

    Description

    id

    The list ID

    caption

    The list caption

    values

    An array of list values

    values.id

    The ID of the value item

    values.caption

    The caption of the value item

    Get List

    Returns the values of the specified list. Values may be filtered according to the entity (sr, asset, etc.) for which you populate the list values.

    Parameters

    Field

    Description

    entity

    A SysAid entity by which to retrieve the available lists. Defaults to SR. For a list of available entities, see Appendix B.

    entityId

    The entity's ID. For example, in SR Form lists, send the SR ID to populate additional filters on the lists. e.g. the responsibility list may be filtered by the admin group of the SR.

    fields

    A comma-separated list of fields to return. Available fields to return are: id (always returned), caption, and values.

    offset

    Retrieved values count is limited. This parameter specifies the offset (start point) from which to retrieve values (e.g. 25). Defaults to 0. Zero base.

    limit

    The maximum number of list values to retrieve per request. Defaults to 500 (configurable).

    entityType

    Numeric. for example: in sr entity, send the sr_type id, for ci entity, send the ci type id ( e.g. for getting the list of CI sub types).

    key

    Relevant for users/groups related fields. Defines whether to use the id or the name as the key for each value in the result. Available values are “name” or “id”. Defaults to id.

    Returns
    The available lists, including their values, per entity type. Defaults to SR.

    Sample JSON return value for list/responsibility?entity=sr&entityid=6

    { “id”:”priority”,
    “caption”:”Priority”,
    “values”: [{“id”:”1”,”caption”:”Highest”},
    {“id”:”2”,”caption”:”High”},
    {“id”:”3”,”caption”:”Low”}]
    }
    

    Return values definition

    Field

    Description

    id

    The list ID

    caption

    The list caption

    values

    An array of list values

    values.id

    The ID of the value item

    values.caption

    The caption of the value item

    Add-ons

    List application add-ons

    Get a list of all available add-ons.

    Parameters

    This API doesn’t receive any parameters.

    Returns
    Return a list of available add-ons.

    Sample JSON return value for add-ons

    [
     {
       "name": "sage",
       "title": "Sage ERP X3",
        "description": "The Sage Identity Management System(AIMS) Ticketing Integration app allows AIMS to create, update and automate",
       "logoFileName": "images/bomgarLogo.png",
       "version": 1,
       "addonType": "Remote Control",
       "link": "http://www.sysaid.com/doc/installSage.html",
       "linkText": "Sage installation instructions",
       "active": false,
       “implemented”: true,
       “params”: null
     },
     {....}
    ]
    

    Return values definition

    Field

    Description

    name

    The name of the add-on

    title

    The title of the add-on

    description

    A short description of the add-on

    logoFileName

    A relative URL to a small logo image of the add-on

    version

    The add-on version

    addonType

    A string representing the add-on category/group

    link

    Link for getting more information about this add-on

    linkText

    Optional: A text to be displayed to the user when the above link is displayed.

    active

    Is this add-on active (true/false)?

    implemented

    Is this add-on have a packed implementation? (add-ons that are not implemented are delivered through the PS)

    params

    Always null when receiving a list of add-ons

    Get add-on parameters

    Returns the full information about an addon with all it’s parameters.

    Parameters

    Field

    Description

    add-on name

    The name of the add-on

    Returns
    The add-on with all its parameters.

    Sample JSON return value for /addons/bomgar

    {
       "name": "bomgar",
       "title": "Bomgar",
       "description": "Bomgar i a provider of secure remote support solutions that enable technology professionals",
       "logoFileName": "addons/bomgar/images/bomgarLogo.png",
       "version": 1,
       "addonType": "Remote Control",
       "link": "https://www.sysaid.com/tools/third-party-integrations",
       "linkText": "",
       "active": true,
       "implemented": true,
       "params": [
           {
               "name": "bomgar_url",
               "description": "Bomgar RC integraton URL",
               "value": "https://sysaid.bomgar.com",
               "type": "text",
               "mandatory": true,
               "editable": true,
               "encrypted": false
           },
           {
               "name": "bomgar_user_name",
               "description": "Bomgar User Name",
               "value": “MyBomgarUserName”,
               "type": "text",
               "mandatory": true,
               "editable": true,
               "encrypted": false
           },
           {
               "name": "bomgar_password",
               "description": "Bomgar Password",
               "value": “MyPassword”,
               "type": "text",
               "mandatory": true,
               "editable": true,
               "encrypted": true
           }
       ]
    }
    

    Return values definition

    Field

    Description

    name

    The name of the add-on

    title

    The title of the add-on

    description

    A short description of the add-on

    logoFileName

    A relative URL to a small logo image of the addon

    version

    The version of the add-on

    adonType

    A string representing the add-on category/group

    link

    Link for getting more information about this add-on

    linkText

    A text that needs to be displayed to the user when the above link is displayed (Optional)

    active

    Is this add-on active (true/false)?

    implemented

    Does this add-on have a packed implementation (add-ons that are not implemented are delivered through the PS)?

    params

    An array list of parameters

    params.name

    The name of the parameter

    params.description

    A description of the parameter

    params.value

    The value of the parameter

    params.type

    The parameter type

    params.mandatory

    Is this a mandatory parameter?

    params.editable

    Can the user edit the value of this parameter?

    params.encrypted

    Should the display of this parameter value act like a password field (show to the user starts instead of real value)

    Update add-on parameters

    Update an add-on parameters

    Parameters

    Field

    Description

    addon name

    The name of the add-on

    Payload:

    A JSON string representing the add-on parameters with the update values. The list below will contain only the fields that can be updated. Any changes to other fields are ignored.

    Field

    Description

    active

    Is this addon active (true/false)

    params.value

    The updated parameter value

    Sample JSON input /addon/bomgar, update the user name and password fields

    {
       "name": "bomgar",
       "active": true,
       "params": [
           {
               "name": "bomgar_url",
               "value": "https://sysaid.bomgar.com",
           },
           {
               "name": "bomgar_user_name",
               "value": "MyUserName",
           },
           {
               "name": "bomgar_password",
               "value": "MyPassword",
           }
       ]
    

    Returns
    New http header with success message or error text.

    Test add-on connection

    Test the add-on parameters.

    Parameters

    Field

    Description

    addon name

    The name of the addon

    Payload
    A JSON string representing the add-on parameters to test. The list below will contain only the fields that can be checked. Any changes to other fields are ignored.

    Field

    Description

    active

    Is this add-on active (true/false)

    params.value

    The updated parameter value

    Sample JSON input /addon/bomgar/testConnection, test the parameters for bomgar addon

    {
       "name": "bomgar",
       "active": true,
       "params": [
           {
               "name": "bomgar_url",
               "value": "https://sysaid.bomgar.com",
           },
           
    
               "name": "bomgar_user_name",
               "value": "MyUserName",
           },
           {
               "name": "bomgar_password",
               "value": "MyPassword",
           }
       ]
    }
    

    Returns
    New http header with success message or error text.

    Refresh Add-ons List

    Refresh the addons list immediately.

    Parameters

    None

    Returns
    Upon successful refresh return a message and a success status.

    CIs

    Create CI

    Create a CI

    Payload

    A JSON string representing the CI with the updated fields only.



    info

    CI’s updated information fields. An array of key-value fields

    info.key

    The id of the information field

    info.value

    The field's value

    Sample JSON post params for POST/ci

    {
       "info": [
                {"key":"ci_name","value":"Test CI from api 1"},
                {"key":"ci_type", "value":"69"},
                {"key":"company", "value":"3"},
                {"key":"ci_cust_text_1","value":"test short text entry"},
                {"key":"ci_cust_date_1", "value":"1636282614000"}
                ]
    }

    Get CI List/Form

    Returns a list of CIs that can be filtered by the available filters.
    The Number of CIs to return can be controlled by the Offset and Limit parameters.

    Returned CIs can be filtered.

    Each CI Includes the fields according to the View and Fields parameters. If none are specified, all CI fields are returned.

    Parameters

    Field

    Description

    view

    A SysAid view which defines the available fields in the list. If view is not specified, check for the fields parameter. If none is specified, returns all fields.

    fields

    List of fields to return. If specified together with the view parameret, return all view's fields together with the specified fields. If none are specified, return all CI fields.

    offset

    CI count is limited (see limit parameter). This parameter specifies the offset (start point) from which to retrieve values (e.g. 25). Defaults to 0.

    limit

    The maximum number of CIs to retrieve per request. Defaults to 500 results (configurable under serverConf>apiConf>maxChunkSize).

    ids

    The list of CI IDs to return, comma separated.

    sort

    One or more fields to sort by,  from the fields that were fetched by the request.

    dir

    Sort order: ascending or descending. Available values: asc/desc. Default is ‘asc’.  Relevant only when sort parameter is sent.

    {filters}

    List of key-value parameters with {filter.id} as the key. and {filter.values.id} as the value.
    I.e.: 
&status=19&request_user=235.

    Multiple values can be sent, comma-separated. I.e.: 
&status=4,5

    supportBarcode

    Flag to indicate that the CI supports barcodes.

    Important

    • User-related fields return the user’s ID, for additional user information, call user service.

    • Dates should be sent as milliseconds in UTC/GMT (since January 1, 1970).

    • In case of a specific date match, send only this date. For example:

      • Match a date: &due_date=1398935657000

    • If a range of dates or from/to is required, send a 2-objects array of dates. If one of them is not available, set to 0. For example:

      • Between dates: &due_date=1398935657000,1399313657000

      • From date: &due_date=1398935657000,0

      • To date: &due_date=0,1399313657000

    Returns
    A list of CIs. For each CI, an ID is returned with the info fields defined in the view and/or fields parameters. If no fields are specified, it returns the full CI information.

    Sample JSON return value for /ci/barcode?view=SysAidMobile&fields=ci_name,location&limit=2

    [
    {
     “id”:”5433”,
    

.
     }
    ]
    

    Return values definition

    Field

    Description

    id

    The user ID

    info

    CI fields. An array of key-value fields, representing the CI information

    info.key

    The ID of the info field

    info.keyCaption

    The caption of the info field’s key

    info.value

    The field’s value

    info.valueCaption

    The field value’s caption. A string representation of the value for display.

    info.mandatory

    A boolean that specifies whether this field is mandatory

    info.editable

    A boolean that specifies whether this field is editable or read only

    info.defaultValue

    The default value for this field is not available (null)

    info.type

    The field’s type. See available field types in Appendix A.

    Update CI

    Update a CI.

    Parameters

    Field

    Description

    id

    The CI ID

    Payload
    A JSON string representing the CI with the updated fields only.

    Field

    Description

    Field

    Description

    id

    The user ID

    info

    CI’s updated info fields. An array of key-value fields.

    info.key

    The id of the info field

    info.value

    The field’s value

    Sample JSON input /ci/273, update the status, change owner & accept date

    {
      â€œid”:”273”,
      â€œinfo”: [{“key”:”accept_date”, ”value”:1391756438000},
                {“key”:”status”, ”value”:2},
                 {“owner”:”sysaid”}]
    }
    

    Get CI Types

    Returns the available CI types.
    If the barcode flag is requested, returns only CI types with barcode support (if the add-on is available).

    Parameters

    Field

    Description

    barcode

    Whether to retrieve only CI types with barcode support. Available options: true/false.

    Returns
    A list of CI types. Each type includes its ID, name, description, and whether the type is predefined.

    Sample JSON return value for ci/type

    [
        {
    “id”:”53”,
           “name”:”Administrator”,
           “description”:””,
           “predefined”: “true”
       },
        {
    “id”:”1”,
           “name”:”Asset”,
           “description”:”System Asset
                             (Workstation,Server,Laptop,Printer,PDA,Other)”,
           “predefined”: “true”
       },
        {
    “id”:”6”,
           “name”:”Business Process”,
           “description”:””,
           “predefined”: “false”
       },
        {
    “id”:”7”,
           “name”:”Catalog”,
           “description”:”System Asset Catalog”,
           “predefined”: “true”
       },
        {
    “id”:”52”,
           “name”:”End User”,
           “description”:””,
           “predefined”: “true”
       }
    ]
    

    Return values definition

    Field

    Description

    id

    The CI type ID

    name

    The CI type name

    descriptions

    The CI type description

    predefined

    Whether the CI type is predefined

    Get CI View

    Returns the fields contained in the specified view.

    Parameters

    Field

    Description

    view

    The name of the view to retrieve.  A combination of view name and CI type id will determine the fields that will be returned.

    Returns
    A list of fields with the requested view.

    Note

    The returned list always contains the ID field. If the ID field is a part of the view, it appears in its correct place. If it isn’t a part of the view then it appears at the end of the list.

    Sample JSON return value for /ci/view/180?view=barcode_book

    [
       {
           "key": "ci_type",
           "value": null,
           "mandatory": false,
           "editable": false,
           "type": "list",
           "defaultValue": null,
           "displayOrder": 1,
           "keyCaption": "CI Type",
           "valueCaption": null
       },
       {
           "key": "owner",
           "value": null,
           "mandatory": false,
           "editable": true,
           "type": "list",
           "defaultValue": null,
           "displayOrder": 2,
           "keyCaption": "Owner",
           "valueCaption": null
       },
        {
    
         



        },
       {
           "key": "id",
           "value": null,
           "mandatory": false,
           "editable": true,
           "type": "numeric",
           "defaultValue": null,
           "displayOrder": 14,
           "keyCaption": "#",
           "valueCaption": null
       }
    ]
    

    Return values definition

    Field

    Description

    key

    The ID of the info field

    keyCaption

    The caption of the info field’s key

    value

    The field’s value

    valueCaption

    The field values' caption. A string representation of the value for display.

    mandatory

    A boolean that specifies whether this field is mandatory

    editable

    A boolean that specifies whether this field is editable or read-only

    defaultValue

    The default value for this field if value is not available (null)

    type

    The field’s type. See available field types in Appendix A.

    Get CI Relation Types

    An API for retrieving CI relation type definitions.

    Returns
    Returns all the valid CI relation types defined in SysAid database and their ID numbers.

    Note

    A returned CI relation type element uniquely identified by the “relationTypeId” field.

    Sample JSON return value for ci/relationtypes

    [
       {
        "relationTypeId": 5,
        "relationName": "Accessed by",
        "oppositeRelationName": "Can access"
       },
       {
        "relationTypeId": 4,
        "relationName": "Connected to",
        "oppositeRelationName": "Connected to"
       }
    ]
    

    Return values definition

    Field

    Description

    relationTypeId

    The CI Relation Type ID

    relationName

    Textual description of the CI relation type

    oppositeRelationName

    Textual description of the way the given CI relation type is presented from the destination CI’s point of view (a textual description of another CI relation type that exists in the SysAid system)

    Get CI Relation

    An API to retrieve all the destination CIs and their relation types, which are associated to a given CI Id.

    Returns
    Returns a list that contains all the destination CI and their prospective CI relationship types associated to the CI ID.

    Sample JSON return value for /ci/9/relation

    [
       {
          "src": 9,
          "dest": 1,
          "ciRelationType": 2
       },
       {
         "src": 9,
         "dest": 2,
         "ciRelationType": 3
    },
        {
         



        },
       {
        "src": 9,
        "dest": 5,
        "ciRelationType": 5
       }
    ]
    

    Return values definition

    Field

    Description

    src

    The source CI ID (the same as the CI ID passed by the Path Parameter call of the API)

    dest

    The target CI ID that the CI ID is associated to

    ciRelationType

    The CI Relationship Type ID that describes the Source CI’s association to the destination CI ID

    Create CI Relations

    API for creating one or more relations for a given CI ID.

    Parameters

    An array of one or more objects comprising of the following fields in each element

    Field

    Description

    dest

    The CI ID of a pre-existing Ci in the system that the CI ID needs to be associated to

    ciRelationType

    The CI relation type that describes this CI’s association with the destination CI ID (must be a valid CI relation type ID - use Get Ci/Relationtypes API to retrieve the available relation types in the system

    Returns
    OK if all relations in the list have been generated successfully, or if the relations already exist in the system (does not generate duplicates in the database)
    An exception is thrown, containing a parsable (.csv format) string of the relations in the list that failed the creation process.

    Sample JSON post params for /ci/9/relation

    [
     {
        "dest":2,
        "ciRelationType":3
     },
     {
        "dest":1,
        "ciRelationType":2
     },
     {
        "dest":3,
        "ciRelationType":11
      }
    ]
    

    Sample error message for a partially failed list

    {
     "status": 400,
     "message": "Ci:9 Invalid CI id 100,Ci:9 Invalid CI Relation type 11"
    }
    

    Delete CI Relations

    API for deleting one or more relations for a given CI ID.

    Parameters

    An array of one or more objects comprising of the following fields in each element

    Field

    Description

    dest

    The CI ID of a pre-existing Ci in the system that the CI ID needs to be associated to

    ciRelationType

    The CI relation type that describes this CI’s association with the destination CI ID (must be a valid CI relation type ID - use Get Ci/Relationtypes API to retrieve the available relation types in the system

    Returns
    Always Returns OK (unless the user is not logged in or is not authorized to perform the call), even if non-existent CI relations or CI destinations were passed to the API

    Sample JSON post params for /ci/9/relation

    [
     {
        "dest":2,
        "ciRelationType":3
     },
     {
        "dest":1,
        "ciRelationType":2
     },
     {
        "dest":3,
        "ciRelationType":11
      }
    ]
    

    Resource Bundle

    Get RB Translated Keys

    Get array of translated keys according to the account location.

    Parameters

    None.

    Payload
    A JSON string representing array of Resource Bundle keys.

    Field

    Description

    key

    Resource Bundle key

    Sample JSONinput /rb

    [
     {
       "key":"dir"
     }
    ]
    

    Returns
    A list of translated keys.

    Sample JSON return value for /rb

    [
     {
         key: "dir"
         value: "LTR"
     }
    ]
    

    Return values definition

    Field

    Description

    key

    Resource Bundle key

    value

    The value according to the account's location.

    Get RB Translated Keys With Given Location

    Get array of translated keys according to the given location.

    Parameters

    Field

    Description

     locale

    The location to display the translated keys.

    Payload
    A JSON string representing array of Resource Bundle keys.

    Field

    Description

    key

    Resource Bundle key

    Sample JSON input /rb

    [[
     {
       "key":"dir"
     }
    ]
    

    Returns
    A list of translated keys.

    Sample JSONreturn value for /rb/{locale}

    [
      {
        key: "dir"
        value: "LTR"
      }
    ]
    

    Return values definition

    Field

    Description

    key

    Resource Bundle key.

    value

    The value according the given location in the path.

    Password Services

    Get LDAP Domains

    Get LDAP domains.

    Parameters

    None.

    Payload

    None.

    Returns
    A list of LDAP domains.

    Sample JSON return value for /ps/domain

    ["ILIENT-HQ","PM-TEST","QA-LAB"]

    Return values definition
    List of domains as an array of strings.

    Get Password Services Permission

    Retrieves a llist all Password Services permissions.

    Parameters

    None.

    Payload

    None.

    Returns
    JSON representing Password Services permission.

    Sample JSON return value for /ps/permission

    {
    enableUserSelfServices: true
    enableUnlockAccount: true
    enableResetPassword: true
    enableLdapSupport: true
    enableUserReset: false
    }
    

    Return values definition

    Field

    Description

    enableUserSelfServices

    True - if the PS module is enabled.

    enableUnlockAccount

    True - if the Unlock Account is enabled.

    enableResetPassword

    True - if the Reset Password is enabled.

    enableLdapSupport

    True - if we have LDAP support.

    enableUserReset

    True - if the reset password method is “user”.

    Get Security Question

    Get a list of all security questions for a given user.

    Parameters

    Field

    Description

    method

    reset/unlock

    Payload
    A JSON string representing the userName and domain name.

    Field

    Description

    userName

    userName in the system

    domainName

    user’s domain

    Returns
    JSON representing Security Questions object.

    Sample JSON return value for /ps/reset/question

    {
       "userRefId": 842,
       "userId": "QA-LAB\\test11",
       "userSecurityQuestionsList": [
           {
               "id": 1,
               "question": "In which city were you born?"
           },
           {
               "id": 2,
               "question": "In which state were you born?"
           },
           enableCaptcha: true
       ]
    }
    

    Return values definition

    Field

    Description

    userRefId

    Auto generated from system per user.

    userSecurityQuestionsList

    Array of objects represent questions.

    userSecurityQuestionsList.id

    Question ID

    userSecurityQuestionsList.question

    Question to display the user.

    enableCaptcha

    True

    Unlock Account

    Unlock an account for a specific user upon answering security questions.

    Parameters

    None.

    Payload
    A JSON string representing the user’s answers.

    Field

    Description

    userRefId

    Fetch in the previous step

    userSecurityQuestionsList

    An array of the user’s questions

    userSecurityQuestionsList.id

    Question ID

    userSecurityQuestionsList.question

    Question

    userSecurityQuestionsList.answer

    Answer

    Returns
    JSON representing unlock action response.

    Sample JSON return value for /ps/unlock

    {
       “actionMessage” : Unlock user account succeeded! \\n Please use your current password to login
    }
    

    Return values definition

    Field

    Description

    actionMessage

    Success message to the user

    Reset password

    Reset a user's password upon answering security questions.

    Parameters

    None.

    Payload
    A JSON string representing the user’s answers.

    Field

    Description

    userRefId

    Fetch in the previous step

    userSecurityQuestionsList

    An array of the user’s questions

    userSecurityQuestionsList.id

    Question ID

    userSecurityQuestionsList.question

    Question

    userSecurityQuestionsList.answer

    Answer

    Returns
    JSON representing the reset action response.

    Sample JSON return value for /ps/reset/ with reset method = “email”

    {
       "actionMessage": "Reset user password succeeded!\\nWithin the next few moments, you will receive an email with your new temporary password.\\nThis password is only valid for 20 minutes, so please log in with it immediately.\\nUpon login, you will be asked to choose a new, permanent password.",
       "settings": {
           "temporaryPasswordValidity": 20,
           "resetPasswordMethod": "email"
       }
    }
    

    Return values definition

    Field

    Description

    actionMessage

    Success Message to the user

    settings

    Password services settings object

    settings.temporaryPasswordValidity

    Password expiration in minutes

    settings.resetPasswordMethod

    Reset password method(email/sms/user)

    Sample JSON return value for /ps/reset with reset method = “user”

    {
       "policy": {
           "complexity": true,
           "minLength": 7,
           "historyLength": 24
       },
       "token": "9f5641643c7f49b9920823ba18381a05"
    }
    

    Return values definition

    Field

    Description

    policy

    Password Services policy

    policy.complexity

    True - if the policy enforce password complexity

    policy.minLength

    Password minimum length

    policy.historyLength

    Password history

    token

    One time token

    Update Password

    Manually update a user's password upon verifying the user's token

    Parameters

    None.

    Payload
    A JSON string representing update password request object.

    Field

    Description

    userRefId

    Fetch in the previous step

    newPassword

    New password for the user

    token

    Fetch from the previous step

    Returns
    JSON representing the Update Password action response.

    Sample JSON return value for /ps/reset/update

    {
    actionMessage: "Reset user password succeeded!"
    }
    

    Return values definition

    Field

    Description

    actionMessage

    Success Message to the user.

    Non-Resource scenarios

    API calls that send a response that's not necessarily a resource.

    Download File

    Download a file from the server. For example: download a user’s photo.

    Parameters

    Field

    Description

    file

    The URL of the file

    Returns
    TBD

    Sample JSON return value for /users/1?view=Mobile

     
    

    Return values definition

    Field

    Description

    field

     

    id

     

    name

     

    info

     

    Translate Key

    Translate a key for display in the specified language.

    Parameters

    Field

    Description

    key

    The key of the String, as defined in the sysaid resources file

    language

    The required language

    Returns
    The translated string.

    Sample JSON return value for a file

    {
       “key”:”welcome”,
       “value”:”Bienvenue”
    }
    

    Return values definition

    Field

    Description

    key

    The requested key for translation

    value

    The translated string