Relationship Between Order Properties in AFLS and Entity Fields in ServiceNow

To perform the integration it is necessary to relate the fields where we will obtain the AFLS and ServiceNow information through the “workOrder” section of the configuration file.

JSON Structure

{
  "workOrder": [
      {
      "table": "",
      "reference": "",
      "dataSource":"",
      "definition": {
        "note": {
          "type": "",
          "key": ""
        },
        "subject": {
          "type": "",
          "key": ""
        },
        "description": {
          "type": "",
          "key": ""
        },
        "service": {
          "type": "",
          "searchBy": "",
          "key": "",
          "defaultValue": {
            "id": 0,
            "value": ""
          },
          "onError": [
            {
              "action": "",
              "message": "'{0}'"
            }
          ]
        },
        "priority": {
          "type": "",
          "defaultValue": {
            "id": 0,
            "value": ""
          },
          "onError": [
            {
              "action": "",
              "message": ""
            }
          ],
          "key": ""
        },
        "client": {
          "type": "",
          "searchBy": "",
          "searchAfls": "Email,Name",
          "defaultValue": {
            "id": 0,
            "value": ""
          },
          "onError": [
            {
              "action": "",
              "message": ""
            }
          ],
          "key": ""
        },
        "company": {
          "type": "",
          "searchBy": "",
          "defaultValue": {
            "id": 0,
            "value": ""
          },
          "onError": [
            {
              "action": "",
              "message": ""
            }
          ],
          "key": ""
        },
        "location": {
          "type": "",
          "key": ""
        }
      }
    }
  ]
}

Properties :

Definition

To perform the integration it is necessary to relate the fields of the work order in Aranda AFLS with the fields in ServiceNow using the “definition” section of the configuration file.

Properties:

Internal properties

{
  "key": "",
  "searchBy": "",
  "searchAfls": "",
  "type": "",
  "defaultValue": {
    "id": 0,
    "value": ""
  },
  "onError": [
    {
        "action": "",
        "message": ""
    }
  ]
}

Detail for string fields

• String fields in ServiceNow are those that allow you to store alphanumeric information, such as names, descriptions, or any other type of text. When relating these fields to the equivalent fields in AFLS, it is important to ensure that the selected association type is compatible with the string data type to ensure correct synchronization and updating of the information between both platforms.
• The type of association they support is FieldValue.
• Cannot relate choice or reference fields.
• It does not support defaults.
• It does not support the onError property.
• It does not support the searchBy property.
• It does not support the searchAfls property.

Service Field Detail

• Allows synchronization with string, choice, reference, and numeric fields in ServiceNow.
• The type of association they support is FieldValue, NotMapped and Mapper.
• Supports defaults.
• Supports the onError property.
• It does not support the searchAfls property.
• It is always recommended to have a default value to assign as it is a required property.

Customer field detail

• Allows synchronization with string, choice, reference, and numeric fields in ServiceNow.
• The type of association they support is FieldValue, NotMapped and Mapper.
• Supports defaults.
• Supports the onError property.
• The property searchAfls determines the value (Name, Email) that will be sent to search in ServiceNow to find the client, if it does not find the client in ServiceNow the assigned action in the onError property will be executed
• It is always recommended to have a default value to assign as it is a required property.

Field Detail

• Allows synchronization with string, choice, reference, and numeric fields in ServiceNow.
• The type of association they support is FieldValue and Mapper.
• Supports defaults.
• Supports the onError property.
• It does not support the searchAfls property.
• For the “priority” property, if a value is not added, it defaults to 0.

Detail for the Address field

• In ServiceNow the locations are registered in the “cmn_location”, the field associated with this property must be associated with it.
• The type of association they support is FieldValue.
• Fields other than reference (cmn_location) cannot be related.
• It does not support defaults.
• It does not support the onError property.
• It does not support the searchBy property.
• It does not support the searchAfls property.
• The location will be searched by latitude and longitude, if it is not found it will create a record in the entity (cmn_location).

Types of relationship or association of fields

You can then display information about how types work in the type property described in the table above.

Property “onError”

1. The array onError allows you to execute an action if the item is not found on the platform; repeating an action generates error.

2. The actions you can take if you do not find the item you are looking for on the platform are:

   “Create a note on the platform” (createNote), on the property onError.message Allows you to customize the message that will be displayed in the note. It is recommended that you add the following characters “{0}” which will be replaced by the ID of the item being searched.

   “Return Error Consuming Integration API” (returnError), on the property onError.message allows you to customize the message that will be displayed in the error message, it is recommended to add the following characters “{0}” which they will replace with the ID of the item that is being searched.

Property “defaultValue”

1. The property defaultValue allows you to add default values, if you add this property with the value of true, the system asks to add the default value within the properties intended for the value relationship.
2. For the “project, service, category” fields, you will not be able to add a default value because they are required values for case creation and you need to establish a relationship with the ServiceNow values.
3. A default value can only be added if the mapping type is “Mapper” or “FieldValue”.

Example:

1. Set the value “wm_order” on the property table:
2. In the definition of the workOrder take the property Customer (client)
3. “type”: Assign the association type as FieldValue:
4. “key”: Name the property in ServiceNow as Caller, the properties can be of type Reference, Choice, Data ( Type of properties in ServiceNow):
5. “defaultValue”: Assign the defaultValue:

{
  "workOrder": [
    {
      "table": "wm_order",
      "definition": {
        "client": {
          "type": "FieldValue",
          "key": "caller",
          "defaultValue": {
             "id": 222,
             "value": "sys_id_client"
          }
        }
      }
    }
  ]
}

⚐ Note: It is recommended to write the sys_id (if it is a Reference) or the “value” (if it is a Choice) of the user to be related.***

Property “dataSource”

The property “dataSource” allows the integration to determine which platform will be the source of information, by default its value is “Both”:

Type example NotMapped

1. Set the value “wm_order” on the property table:
2. In the definition of the workOrder Take Property Service (service) and assign the association type as NotMapped:

{
    "workOrder": [
        {
            "table": "wm_order",
            "definition": {
                "service": {
                    "type": "NotMapped"
                }
            }
        }
    ]
}

1. The relationship implies that a default value must be assigned for all Work Orders, this is achieved by using the “defaultValue” property, as shown below:

{
    "workOrder": [
        {
            "table": "wm_order",
            "reference": "reference_1",
            "definition": {
                "service": {
                    "type": "NotMapped",
                    "defaultValue": {
                        "id": 222
                    }
                }
            }
        }
    ]
}

⚐ Note: The Work Orders assigned to class “wm_order” in AFLS will be assigned service with ID 222.

Type example Mapper>

1. Set the value “wm_order” on the property table:
2. In the definition of the workOrder take the property Customer (client)
3. “type”: Assign the association type as Mapper:
4. “key”: Name the property in ServiceNow as Caller, the properties can be of type Reference, Choice, Data (Type of properties in ServiceNow):
5. “searchAfls”: Assign the value (Name, Email) that will be sent to search ServiceNow to find the client:

{
    "workOrder": [
        {
            "table": "wm_order",
            "reference": "reference_1",
            "definition": {
                "client": {
                    "key": "caller",
                    "type": "NotMapped",
                    "searchAfls": "Email"
                }
            }
        }
    ]
}

1. The relationship implies that AFLS customers must be associated with ServiceNow customers; It is recommended to write the sys_id of the customer to be related, as shown below:

{
    "workOrder": [
        {
            "table": "wm_order",
            "reference": "reference_1",
            "definition": {
                "client": {
                    "key": "caller",
                    "type": "NotMapped",
                    "searchAfls": "Email"
                }
            }
        }
    ],
    "client": [
        {
            "id": 5,
            "value": "sys_id_client_servicenow",
            "reference": "reference_1"
        }
    ]
}

⚐ Note: AFLS Client ID “5” is related to client “sys_id_client_servicenow” in ServiceNow***

Type example FieldValue>

1. Set the value “wm_order” on the property table:
2. In the definition of the workOrder Take Ownership Company (company)
3. “type”: Assign the association type as FieldValue:
4. “key”: Name the property in ServiceNow as Company; properties can be of type Reference, Choice, Data (Type of properties in ServiceNow); the assigned property is of type Reference; This type of property requires that the searchBy assigned a value (name by which the referenced entity will be searched):
5. “searchBy”: Name the property to be searched against in the referenced entity:

{
  "workOrder": [
    {
      "table": "wm_order",
      "definition": {
        "company": {
          "type": "FieldValue",
          "key": "company",
          "searchBy": "name"
        }
      }
    }
  ]
}

⚐ Note: Properties referenced to other classes (tables) in ServiceNow are composed of different properties. To allow the item to be searched, it is necessary to specify the name of this field. In the item search, the AFLS item name/display is used to third parties; the ID or other property is not used; if there are many items with the same name in ServiceNow, select the relationship type as “Mapper”, to relate the items by IDs - sys_id.***

↩ Back to Settings