Http Effect is currently the single official method to communicate to ServiceNow server via REST API’s using Seismic UI framework.

Note: information is up to date as of latest Orlando release.

To install it:

npm install @servicenow/ui-effect-http

Import it to your js file:

import { createHttpEffect } from '@servicenow/ui-effect-http';

They are typical REST API endpoints and options that can be found via REST API explorer, docs or by navigating SN pages and inspecting chrome developer tools network tab.

With batch you define and use same REST API endpoints, but they get converted to /api/now/v1/batch endpoint with encoded request and response payloads.

Batching is set to true by default, batching comes with performance improvement in certain cases when 2 or more API calls are required. Batching single API call has worse performance than not using batch. Batching too many API calls together might have worse end user experience if users can be presented with something first, rather than everything at once. Encoded payload makes payload debugging harder.

Encodes the call with percent encoding removing all non-alpha numerical characters (# becomes %23 for example). Should be left default at true.

This is used to build Request Payload (body), usually for POST calls. Second parameter of dispatch function holds single JSON object for the Call parameters. In this case object name is data and in the Effect it is defined as ‘data’ string. Only the names should match, it could be called anything. Below will create a user with provided details.

Action:

dispatch(USER_CREATED, {
    data: { "active": "true", "user_name": "E1325", "first_name": "John", "last_name": "Doe" }
});

Action handler:

USER_CREATED: createUserEffect,

Effect:

const createUserEffect = createHttpEffect('/api/now/table/sys_user', {
    method: 'POST',
    dataParam: 'data',
});

Second parameter of dispatch function holds JSON object for the Call parameters that are in pairs. URL maps to JSON object by putting : in front of object name.

Action:

dispatch(USER_FETCHED_QUERY_PARAMS, {
    table: 'sys_user',
    sysparm_query: 'active=true',
    sysparm_limit: 10
})

Action handler:

USER_FETCHED: fetchUsersEffect,

Effect:

const fetchUsersEffect = createHttpEffect('/api/now/table/:table', {
    batch: false,
    method: 'GET',
    pathParams: ['table'],
    queryParams: [
        'sysparm_query',
        'sysparm_limit'
    ],
    successActionType: USER_FETCH_SUCCESS,
});

Note: you can mix pathParams with queryParams within single Effect, however you cannot mix dataParams option.

This option looks similar to REST API Explorer in SN options. It holds a JSON object with and maps exactly.

Action:

dispatch(USER_FETCHED, {
    "id": "E1324", "first_name": "Abel"
});

Action handler:

USER_FETCHED: fetchUsersEffectQueryParams,

Effect:

const fetchUsersEffectQueryParams = createHttpEffect('/api/now/table/sys_user?sysparm_query=user_name=:id^ORfirst_nameLIKE:first_name', {
    method: 'GET',
    queryParams: ['id', 'first_name']
});

Gets triggered right at the start of API call execution.

Used when on progress event is triggered by API call, useful when uploading large attachments to give feedback about upload state. Hovewer, this does not seem possible with current state of HTTPEffect, so I have not found any actual uses yet. Would be interested to hear other experiences.

Gets triggered right when API call is done successfully.

Gets triggered right when API call is completed with failure.

Coeffects variable holds everything that is available for the action handler. In below case ‘result’ variable will hold the response payload (this is same as coeffects.action.payload.result). Response headers are not available yet.

UpdateState will update the initialState with the result payload:

USER_FETCH_SUCCESS: (coeffects) => {
    const {action: {payload: {result}} } = coeffects;

    for (var a in result) {
        coeffects.updateState({
            path: 'records.users',
            value: result[a],
            operation: 'push'
        });
    }
}