Supported Basic Operations

For the Task of ...

Use the following REST call (URL)

Returning all records, and all fields from a component/table.

To return a complete list of records in a particular component. use the following:

http://<WebApp-URL>/<WebApp URL>/restapi/component/<component_name>

Should the component name consists of more than one word, you need to replace any <blank> with '_':

For example:

http://<WebApp-URL>/<WebApp URL>/restapi/component/hazard_identification

Note

If the API call returns data with lookup items, you will notice 3 different information

• The actual lookup in text format (e.g. "position_status": "Current")
• The lookup item id denoted by "li_" (e.g. "li_position_status" : "li_9999999_101")
• Lookup value in Enum denoted by "lk_" (e.g. "lk_position_status" : "lk_current")

To only return a single record from a component.

To return a single record from a component, you need to include the record's UniqueID in the call the follows:

http://<WebApp-URL>/<WebApp URL>/restapi/component/<component_name>('UniqueID')

For example:

http://<WebApp-URL>/<WebApp URL>/restapi/component/action('AFBWkBch5FPXNAjWnVZLWxD0')

Including related records in a call.

To include related entities in the payload which is returned by the call, you can use the $expand query option.

Each relationship needs to be prefixed with "rel_":

http://<WebApp-URL>/<WebApp URL>/restapi/component/<component_name>?$expand=rel_<relationship_name_1>,rel_<relationship_name_2>,...

For example:

http://<WebApp-URL>/<WebApp URL>/restapi/component/action?$expand=rel_assigned_by,rel_assigned_to

To include ALL relationships in the call you can use the * wild-card, like in this example:

http://<WebApp-URL>/<WebApp URL>/restapi/component/action?$expand=*

The expand option can be used

• for all cardinalities
• when the main call returns a single, or multiple records.

Note: the $expand option can only be used for 1 level deep.

Use of Special Characters inside a Query String

Special characters (e.g. ampersand [&], or single quote ['] are not supported within a query string of an URL. Instead, you must use the URL-encoded value. For example:

• Invalid: ...$filter=action_source eq 'Visa & License Requirements'
• Valid: ...$filter=action_source eq 'Visa %26 License Requirements'

An example for Encoding Reference can be found here:

https://www.w3schools.com/tags/ref_urlencode.ASP

Supported Operations

For the Task of ...

Use the following REST call (URL)

Applying a filter to a Decimal and Integer fields.

The generic format for filtering Decimal and Integer fields is:

...?$filter=field_name <operator> <value>

Supported operators for Decimal fields are:

• eq (= is equal to)
• ne (<> is not equal to)
• lt (< is less than)
• le (<= is equal to or less than)
• gt (> is greater than)
• ge (>= is greater than or equal to)

(Note that the operators are case sensitive!)

Example:

http://<WebApp URL>/restapi/component/incident?$filter=total_cost gt 5000

Applying a filter to a Date field.

The generic format for filtering Date fields is:

...?$filter=field_name <operator> <yyyy-mm-dd>

Supported operators for Date fields are:

• eq (= is equal to)
• ne (<> is not equal to)
• lt (< is before)
• le (<= is on or before)
• gt (> is after)
• ge (>= is on or after)

(Note that the operators are case sensitive!)

Example:

http://<WebApp URL>/restapi/component/action?$filter=due_date lt 2020-04-01

Applying a filter to a Time field.

The generic format for filtering Time fields is:

...?$filter=field_name <operator> <HH:mm:ss>

As SAI360 does not record 'seconds' the following format is equally valid:

...?$filter=field_name <operator> <HH:mm>

The supported operators are the same as for the Date fields.

Example:

http://<WebApp URL>/restapi/component/incident?$filter=incident_time gt 06:30 and incident_time lt 14:30

Applying a filter to a DateTime field (e.g. 'LastModified')

The generic format is:

...?$filter=field_name <operator> <yyyy-mm-ddTHH:mm:ss:SSZ>

Example:

http://<WebApp URL>/restapi/component/action?$filter=bms_lastmodified gt 2019-09-13T07:25:45.41Z

The supported operators are the same as for the Date fields.

Date and time for the bms_LastModified field are always reflecting the Tomcat Server time - so please ignore the 'Z' notation.

Applying a filter to a Single Lookup field.

Please note:
Lookups are represented in three different ways, and you can choose whichever suits your purposes.

• Value Text
• Enumerated Value
• Lookup ID

Search by Lookup Value - Value Text

The generic format is:

...?$filter=<field_name> <operator> '<value>'

Supported operators for Single Lookup fields are:

• eq (= is equal to)
• ne (<> is not equal to)

Example:

http://<WebApp URL>/restapi/component/action?$filter=action_source eq 'Audit'

Search by Lookup Value - Enumerated Value

The generic format is:

...?$filter=lk_<field_name> <operator> E360.lk_<lookup_name>'lk_<value>'

Supported operators for Single Lookup fields are:

• eq (= is equal to)
• ne (<> is not equal to)

Note that the operators and values are case sensitive! In Enum mode, all values will be lower case.

Example:

http://<WebApp URL>/restapi/component/action?$filter=lk_action_source eq E360.lk_action_source'lk_audit'

Search by Lookup ID

The supported operators are identical, and the generic format is as follows:

...?$filter=li_field_name <operator> E360.li_<lookup_ID>'li_<ID_of_value>'

Example:

http://<WebApp URL>/restapi/component/action?$filter=li_action_source eq E360.li_action_source'li_9999999_110'

Applying a filter to a Multi Lookup field.

Lookups are represented in three different ways, and you can choose whichever suits your purposes.

• Value Text, represented as a String
• Enumerated Value, represented as an Array
• Lookup ID, represented as an Array

Search by Lookup Value - Value Text

Supported operators for Single Lookup fields are:

• eq (= is equal to)
• ne (<> is not equal to)

The generic format is:

...?$filter=<field_name> <operator> '<value>'

Example:

http://<WebApp URL>/restapi/incident?$filter=consequences ne 'Security'

Search by Lookup Value - Enum

The only operator supported for multi lookups is HAS:

...?$filter=lk_<field_name> has E360.lk_<lookup_name>'lk_<value>'

Example (note the 'lk_' prefix before the field value):

http://<WebApp URL>/restapi/incident?$filter=lk_consequences has E360.lk_incident_consequence'lk_security'

In many cases, the <field_Name> and the <lookup_name> are identical. If necessary, you can use the Metadata call to check for details.

Search by Lookup ID

You can also filter by the ID of the lookup item (e.g. '999999_111') instead for a value (e.g. 'security').

The only operator supported for multi lookups is HAS:

...?$filter=li_<field_name> has E360.li_<lookup_name>'li_<ID_of_value>'

Example (note the 'li_' prefixes):

http://<WebApp URL><WebApp URL>/restapi/incident?$filter=li_consequences has E360.li_incident_consequence'li_9999999_111'

Applying a filter to a String field.

The generic format for filtering String fields is:

...?$filter=<operator>(field_name,'string to match')

The only supported operator for String fields is:

• contains (the target field needs to contain the provided string)

Example:

http://<WebApp URL><WebApp URL>/restapi/component/action?$filter=contains(action_summary,'east exit')

Applying a filter to a Matrix Result field.

The generic format is:

...?$filter=field_name eq/ne <value>'
or
...?$filter=contains(field_name,'<value>')

Supported operators for Matrix Result fields are:

• eq (= is equal to)
• ne (<> is not equal to)
• contains

(Note that the operators are case sensitive!)

Example:

http://<WebApp URL><WebApp URL>/restapi/component/risk_register?$filter=inherent_risk_assessment eq '05 - medium'

Filtering on related records.

The system allows to filter on one, or several related records:

...?$expand=rel_<relationship_1>($filter=field_name <operator> 'string to match'),rel_<relationship_2>(filter=field_name <operator> 'string to match'),...

Example:

http://<WebApp URL><WebApp URL>/restapi/component/audit?$expand=auditor($filter=first_name eq 'Bethany'),audit_team_members($filter=first_name eq 'Hayley')

Using and/or in a filter

Filter conditions can be linked using the and/or operators.

...?$filter=<condition_1> <and/or> <condition_2>

(Note that the operators are case sensitive.)

Example:
http://<WebApp URL>/restapi/component/action?$ filter=contains(action_summary,'vehicle') or (contains(action_summary,'emergency') and contains(action_summary,'exit'))

The supported operations are $select, $count and $filter

$top, $search and $skip are not supported