Updating service orders

Update or create a service order. If the service order is associated with a tenant that is integrated with Maximo® Asset Management, the service order is updated in the EAM system and in Device Management Enablement by default. Alternatively, to ingest updated service order details from the EAM system into the existing service order record in Device Management Enablement for the integrated tenant, set the value of the optional NO_SYNC property to true in the request.

Method

PUT.

The PUT method acts as an UPSERT operation, and so updates or creates a service order.

Resource URL

https://web_server_hostname/ibm/water/eam/api/data/solution/SOLUTION_ID/
    model/MODEL_ID/serviceorder/EAM_ID

For example,

https://web-server.cn.example.com/ibm/water/eam/api/data/solution/Sunshine/
    model/SunshineWaterGroup/serviceorder/SO_TEST

Path parameters

Table 1. Path parameters
Name	Type	Description
SOLUTION_ID	String	The ID of the solution application.
MODEL_ID	String	The model ID.
EAM_ID	String	The Enterprise Asset Management ID for the service order.

Request properties

If your environment includes interim fix PO08130 or later, the following properties are also available: CAUSE_OF_SO, CONTEXT_OF_SO, DATE_OF_THE_ISSUE, DETAILED_LOCATION, IMPACTED_PERIMETER, KEY_CONTACT_EMAIL, KEY_CONTACT_PHONE_NUMBER, PRIORITY, PROBLEM_TYPE, REPORTER_NAME, and SECTION.

Table 2. Request properties
Name	Type	Description
ADDRESS	String	The address details for the service order.
ATTACHMENTS	String	Information to attach to the service order.
CATEGORY	String	The category of service order.
CAUSE_OF_SO	String	The reason the service order was created. The available types of causes are defined on your system.
COMPLETION_DATE	Number	The timestamp value for the service order's completion date.
COMPLETION_STATUS	Number	The percent complete value for the service order.
CONTEXT_OF_SO	String	The context of the service order in relation to asset ownership. For example, the service order might be for an asset that is owned by a third party.
CUSTOMER_ID	String	The ID of the customer that the service order relates to.
DATE_OF_THE_ISSUE	Number	The timestamp value for the date that the problem occurred.
DESCRIPTION	String	A description of the service order.
DETAILED_LOCATION	String	Optional field to specify the exact location that the service order relates to. For example, door B1 on the ground floor of the North Building.
EAM_ID	String	The Enterprise Asset Management ID for the service order. A value is required for the `EAM_ID` property in a request to create a service order only if the associated tenant is not integrated with an EAM system. If the associated tenant is integrated with an EAM system, an EAM_ID is automatically assigned when the service order is created.
EXTERNAL_ID	Number	This optional property is only included if the tenant is integrated with your EAM system. The value uniquely identifies the service order in the integrated EAM system.
GIS_ID	String	The Geographic Information System ID. This property value is not used currently in the solution, so the value can be an empty string.
IMPACTED_PERIMETER	String	The technical perimeter for the service order. For example, the service order might deal with filters or pipes.
KEY_CONTACT_EMAIL	String	The email of the third party who is responsible for the management of the service order.
KEY_CONTACT_PHONE_NUMBER	String	The phone number of the third party who is responsible for the management of the service order.
LOCATION	String	The geographical coordinates for the service order in well-known text (WKT) format. If a geocoding provider is configured and location coordinates are not specified in the request, location coordinates are generated from the value of the `ADDRESS` property and these coordinates are returned as the `LOCATION` value in the JSON response.
NAME	String	The name of the service order.
NO_SYNC		If the associated tenant is not integrated with your EAM system, the `NO_SYNC` property is not included in the request. If the associated tenant is integrated with your EAM system, you can set the value of the `NO_SYNC` property to `true` to ingest the service order from the EAM system into Device Management Enablement. Otherwise, if the `NO_SYNC` property is not included or if the property is set to `false`, the service order is created in the EAM system and in Device Management Enablement.
OPENING_DATE	Number	The timestamp value for when the service order was opened.
PRIORITY	Number	The priority level for the service order.
PROBLEM_TYPE	String	The type of problem that the service order deals with. For example, reported noise levels. The available problem types are defined on your system.
REGISTRATION_NO	String	The service order's registration number.
REGISTRATION_DATE	Number	The timestamp value for the service order's registration date.
REPORTER_NAME	String	The name of the employee who reported the issue in the integrated EAM system..
SECTION	String	The name of section or organization that is in charge of the area that relates to the service order.
SITE_ID	String	A value is required for the `SITE_ID` property only if the associated tenant is integrated with an EAM system. The value is the ID for the site that is defined in the EAM system for the tenant.
STATUS	String	The string ID for the status of the service order.
STATUS_NAME	String	The I18N string value for the status.
TENANT_ID	Number	The integer ID of the tenant in the database. You can use either `TENANT_STR_ID` or `TENANT_ID` in the request.
TENANT_STR_ID	String	The string ID of the tenant. You can use either `TENANT_STR_ID` or `TENANT_ID` in the request.
TYPE	String	This property can be used to group related service orders.

Sample request content

The following extract is a sample request where the tenant is not integrated with your EAM system. This example uses TENANT_STR_ID to identify the tenant.

{
    "TENANT_STR_ID":"SUPER_TENANT",
    "GIS_ID":"BAR",
    "NAME":"SO TEST Updated",
    "DESCRIPTION":"SO Description Updated",
    "LOCATION":"POINT (-86.2155070 41.6925244)",
    "CUSTOMER_ID":null,
    "STATUS_NAME":null,
    "Type":null,
    "REGISTRATION_NO":"SO Reg No Updated",
    "REGISTRATION_DATE":1317423600000,
    "OPENING_DATE":1317423600000,
    "COMPLETION_DATE":1317423600000,
    "COMPLETION_STATUS":1,
    "STATUS":"New",
    "CATEGORY":"Failure",
    "CAUSE_OF_SO": "FAILURE_SUSPICION",
    "CONTEXT_OF_SO": "3rd Party",
    "DATE_OF_THE_ISSUE": 1553194800000,
    "DETAILED_LOCATION": "North corner of Building 1",
    "IMPACTED_PERIMETER": "cold_water_installation",
    "KEY_CONTACT_EMAIL": "jsm@endof.com",
    "KEY_CONTACT_PHONE_NUMBER": "021451234666",
    "KIND_OF_ISSUE": "network_failure",
    "PRIORITY": 2,
    "REPORTER_NAME": "John Smythe",
    "SECTION": "ERWD"
}

The following extract is a sample request where the tenant is integrated with your EAM system. This example uses TENANT_ID to identify the tenant and, as the NO_SYNC property is not included, the service order is updated in the EAM system and in Device Management Enablement.

{
    "EXTERNAL_ID":121,
    "TENANT_ID":1001,
    "EAM_ID":"FOO",
    "GIS_ID":"BAR",
    "SITE_ID":"SWG",
    "NAME":"SO TEST Updated",
    "DESCRIPTION":"SO Description Updated",
    "LOCATION":"POINT (-86.2155070 41.6925244)",
    "CUSTOMER_ID":null,
    "STATUS_NAME":"New",
    "Type":null,
    "REGISTRATION_NO":"SO Reg No",
    "REGISTRATION_DATE":1317423600000,
    "OPENING_DATE":1317423600000,
    "COMPLETION_DATE":1317423600000,
    "COMPLETION_STATUS":1,
    "STATUS":"New",
    "CATEGORY":"Failure",
    "CAUSE_OF_SO": "FAILURE_SUSPICION",
    "CONTEXT_OF_SO": "3rd Party",
    "DATE_OF_THE_ISSUE": 1553194800000,
    "DETAILED_LOCATION": "North corner of Building 1",
    "IMPACTED_PERIMETER": "cold_water_installation",
    "KEY_CONTACT_EMAIL": "jsm@endof.com",
    "KEY_CONTACT_PHONE_NUMBER": "021451234666",
    "KIND_OF_ISSUE": "network_failure",
    "PRIORITY": 2,
    "REPORTER_NAME": "John Smythe",
    "SECTION": "ERWD"
}

Response properties

The response properties match the request properties, and also includes the properties in the following table.

Table 3. Extra response properties
Name	Type	Description
DS_END_DATE	Number	The timestamp value for the date that is used when service orders are filtered by end date. If there is a value set for `COMPLETION_DATE`, the `DS_END_DATE` is set to that value. Otherwise, `DS_END_DATE` is set to `9999-12-01`.
DS_START_DATE	Number	The timestamp value for the date is used when service orders are filtered by start date. If there is a value set for `OPENING_DATE`, the `DS_START_DATE` is set to that value. Otherwise, `DS_START_DATE` is set to the timestamp value for the date and time when the service order was created.
FORMATTED_ADDRESS	String	This property is not used.
NAME_I18N	String	The name of the service order in the locale specified in the request header.
SO_ID	Number	The integer ID of the service order.
STATUS_NAME_I18N	String	The status value in the locale specified in the request header.

Sample response content

Sample response where the tenant is integrated with your EAM system:

{
    "LOCATION": "POINT (-86.1209009 41.5225009)",
    "COMPLETION_STATUS": 1,
    "SITE_ID": "SWG",
    "REGISTRATION_NO": "SO Reg No",
    "FORMATTED_ADDRESS": null,
    "CUSTOMER_ID":null,
    "STATUS_NAME":null,
    "STATUS_NAME_I18N":null,
    "Type":null,
    "CUSTOMER_ID": null,
    "NAME": "SO TEST Updated",
    "MODEL_ID": 1,
    "STATUS": "New",
    "NAME_I18N": "SO TEST Updated",
    "DESCRIPTION": "SO Description Updated",
    "EXTERNAL_ID": null,
    "CATEGORY": "Failure",
    "TENANT_STR_ID": "SUPER_TENANT",
    "COMPLETION_DATE": 1545652800000,
    "ATTACHMENTS": null,
    "ADDRESS": null,
    "OPENING_DATE": 1514808000000,
    "TENANT_ID": 1000,
    "GIS_ID": "SO_TEST",
    "REGISTRATION_DATE": 1514808000000,
    "EAM_ID": "SO_TEST",
    "CAUSE_OF_SO": "FAILURE_SUSPICION",
    "CONTEXT_OF_SO": "3rd Party",
    "DATE_OF_THE_ISSUE": 1553194800000,
    "DETAILED_LOCATION": "North corner of Building 1",
    "IMPACTED_PERIMETER": "cold_water_installation",
    "KEY_CONTACT_EMAIL": "jsm@endof.com",
    "KEY_CONTACT_PHONE_NUMBER": "021451234666",
    "KIND_OF_ISSUE": "network_failure",
    "PRIORITY": 2,
    "REPORTER_NAME": "John Smythe",
    "SECTION": "ERWD"
}

HTTP return codes

The HTTP PUT method returns one of the following status codes:

Table 4. Return codes
Code	Description
200	OK
401	Unauthorized
500	Internal server error