PUT operation not supported by SAI360 (EHS&S)

Supported Basic Operations

For the Task of ...

Use the following REST call (URL)

To update a single record on a given component.

CALL:

To update a single record on a component, you need to include the record's UniqueId in the call the follows:

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

For example:

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

PAYLOAD:

In the payload, include all the fields and values which need to be updated. The field/value pairs need to be comma separated, for example:

{
"action_description": "Please service and replace bulb if necessary",
"reported_date": "2019-07-03"
}

Referencing the Field(s) which needs updating

The key for any field to be updated is the Component Field Name (e.g. Priority), rather than the Lookup Name (e.g. Action Priority).

Updating Date Fields

Updating Date fields requires a fixed format: yyyy-mm-dd

For example:

{
"reported_date": "2020-01-09"
}

The API will return a "400 Bad Request" error if incorrect values and/or incorrect formats are being supplied in the call.

Updating Time Fields

The API does accept all of these formats: HH:mm, HH:mm:ss or HH:mm:ss.SSS

Example:

{
"reported_date": "17:30"
}

The API will only read and store the HH:mm values provided in a call, seconds and milliseconds will be ignored.

Updating Decimal or Integer Fields

Decimal or Integer fields can be updated as follows:

{
"total_cost": 249.99
"items": 100
}

The API will return a "400 Bad Request" error if the number of decimal fields provided in the call exceeds the limit as defined in Component Management.

Updating Single Lookup Fields

Lookups can be updated by using either the

• lookup value as Text, or as Enum:
  - when using Text, no prefix is necessary
  - when using Enum, use the "lk_" prefix
• or the bms_ID: as key, use the "li_" prefix

For example, these calls will have the same outcome:

{
"priority": "Low"
}

or:

{
"lk_priority": "lk_low"
}

Note that the values are case sensitive! When using the Text format, the value has to be provided in exactly the same case as in the database (e.g. "low" would be rejected), whereas in the Enum format the value will always be in lower case.

or:

{
"li_priority": "0000001_103"
}

Updating Multi Lookup Fields

Lookups can be updated by using either the

• lookup value: as key, use the field name with the prefix of "lk_"
• or the bms_ID: as key, use the "li_" prefix

For example, these two calls will have the same outcome:

{
"lk_consequences":
[
"lk_equipment_damage_or_loss",
"lk_injury_or_illness",
"lk_quality"
]
}

or:

{
"li_consequences":
[
"li_9999999_101",
"li_9999999_103",
"li_9999999_104"
]
}

The API will return a "400 Bad Request" error if incorrect values are being supplied in the call.

IMPORTANT:
This call will REPLACE existing values in a multi-lookup with the values sent by the payload, it WILL NOT add to the existing values.

If an external system needs to ADD entries to an existing record, it will be necessary to

• First retrieve the existing target record and identify the existing entries in the lookup.
• Add those entries to those which are to be added.
• Use all those values in the PATCH call.

Updating Relationships - single select.

To link two existing records (for example link a person as 'Reported by' to an 'Incident', use the following generic template:

{
"<name_of_relationship>":
{
"@id":"<name_of_component>('UniqueID')"
}
}

For example:

{
"reported_by":
{
"@id":"person('AFBWkBchDUVscgjWnUlM_sr0')"
}
}

Updating Relationships - multi select

To link two existing records (for example link several persons as 'People to be notified' to an 'Incident', use the following generic template:

{
"rel_<relationship_name>":
[
{@id":"<name_of_component>('UniqueID')"},
{@id":"<name_of_component>('UniqueID')"},

...
]
}

For example:

{
"rel_people_notified":
[
{"@id":"person('AFBWkBchDUVscgjWnUlM_sr3')"},
{"@id":"person('AFBWkBchDUVscgjWnUlM_sr0')"},
{"@id":"person('AFBWkBchDUVscgjWnUlM_sr9')"}
]
}

Adding a Related Record - single select

You can ADD a related record as part of a PATCH call to the main record (e.g. create a 'Person' record while updating an 'Audit' record.

The generic template is:

{
"rel_<relationship_name>":
{
"<field_name_1>": "<value_1>",
"<field_name_2>": "<value_2>",
...
}
}

For example:

{
"rel_auditor":
{
"first_name":"John",
"last_name":"Smith",
"email_address":"john.smith@acme.com"
}
}

Restrictions for Questionnaires:
You can set or update the Questionnaire Name/Template (linked to a record) via Rest API. However, you cannot modify the actual content of the Questionnaire itself.

Adding a Related Record - multi select

You can ADD multiple related record as part of a PATCH call to the main record (e.g. create multiple 'Action' records while updating an 'Audit' record.

The generic template is:

{
"rel_<relationship_name>":[
{
"<record_1_field_name_1>": "<value_1>",
"<record_1_field_name_2>": "<value_2>",
...
},
{
"<record_2_field_name_1>": "<value_1>",
"<record_2_field_name_2>": "<value_2>",
...
} ]
}

For example:

{
"rel_actions":[
{
"action_summary": "Replace all incandescent globes with LED",
"date_raised": "2019-10-04",
"due_date": "2019-10-30",
"priority": "medium",
"status": "Open"
},

{
"action_summary": "Improve roof insulation in office areas",
"date_raised": "2019-10-04",
"due_date": "2019-10-30",
"priority": "medium",
"status": "Open"
}
]
}

Updating Matrix Fields

The generic naming convention for a Matrix field is as follows:

{
"<field_name>_<name_of_x_axis>": "value",
"<field_name>_<name_of_y_axis>": "value"
}

For example:

{
"inherent_risk_assessment_likelihood": "rare",
"inherent_risk_assessment_consequence": "minor"
}

Please note:

• You must provide BOTH axis values in the call. Calls with just a single value will be ignored.
• You cannot 'clear' a matrix via the API.
• The API only supports 2-d matrices.
• It only can update the axis values, and not the results. The matrix values will be calculated by the system.