You can integrate Case IQ into your broader case management ecosystem with Case IQ's lookup functionality, which allows you to search for data in an external source system, such as your organization's human resources information or ticketing system, and populate it into Case IQ fields. This means you can pull data already in another system into Case IQ in real time, so you do not need to manually enter it.

A lookup integration will look like a search bar on a form when adding or editing a record. When you type key words in the lookup search bar, Case IQ sends an HTTP request to your source system to retrieve data. Case IQ's lookup integration accepts serialized JSON and can automatically handle responses in XML or CSV format.

You can configure a lookup integration for either a section or form. The next section in this article, Choosing a Section or Form Lookup Integration, provides guidance on which option to choose for your use case. If you decide to configure a section, see Add a Data Lookup Section. For a form integration, see Activate Form Lookup Integration instead. After adding or activating your lookup integration, you can configure the settings for the integration following the Configure a Lookup Integration section.

Choosing a Section or Form Lookup Integration

While data lookup integrations for both sections and forms use the same lookup functionality, we recommend each option in different scenarios.

Data lookup sections are ideal if you need to configure multiple integrations with different source systems for one record type. For example, suppose investigators need to document employee and client information for cases, which are stored in two different applications your organization uses. You could add two data lookup sections to the Case IQ case form so that investigators can pull data from each source system: one for employee information and another for client information.

On the other hand, we recommend a form lookup integration if you need to populate source data into static party or profile fields. While you can add data lookup sections to the party and profile forms, the integration will only be able to populate source data into "dynamic" fields in the lookup section, which are fields you have added and configured for the record type with the Form Builder. With a form lookup integration, you can map source data to static fields on the party and profile forms, such as "First Name", "Last Name", and "Party Type". 

See the chart below for more information on lookup section and form integrations to help determine the best integration for your purposes.

Add a Data Lookup Section

To add a lookup integration for a section on a record type:

1. In Settings, navigate to the Forms page under the Forms tab. 
2. In the Forms grid, select the form to which you want to add the data lookup section. You can add a lookup section to any standard or custom form type.  
   1. If you want to create a new custom form type, see the Add and Edit a Custom Form Type article for details.
3. Click the Edit button on the Form Builder to put the form into edit mode.
4. Click the + Insert Fields section or the right arrow icon to open the Field Type sidebar.
5. Search for "Data Lookup Section" in the Field Type sidebar.
6. Click and hold "Data Lookup Section" in the Field Type sidebar, drag it to the Form Builder, and let go of your cursor. 
7. The Data Lookup Section pop-up will be displayed, where you can configure the integration's settings. See the Configure a Lookup Integration section of this article for details on filling in the integration settings. 
8. When you have completed configuring the integration, click Save on the pop-up. The data lookup section will now appear on the Form Builder. 
9. You can now add fields to the section that you want to be populated via the lookup integration. Click the + Insert Fields button in the data lookup section or the right arrow icon to open the Field Type sidebar again.
10. Search for the field types you want to add to the data lookup section. See the Supported Fields Types for Lookup section in this article for a full list of the fields that Case IQ can populate via a lookup integration. 
11. When you have found a field type you want to add to the section, click and hold it in the Field Type sidebar, drag it to the data lookup section, and let go of your cursor. 
12. Add all the fields you want to populate in the section via lookup.
13. You can now map your source data to the fields you added to the data lookup section. See the Simple Mapping Method or Expression Mapping Method sections of this article depending on the mapping method you chose.  
    1. If you selected "Automatically detect mappings" when configuring your lookup integration, you can skip this step.
14. When you have finished configuring your lookup integration and mappings, click the Publish button on the Form Builder to make the data lookup section available for your users. 

Activate a Form Lookup Integration

To turn on a lookup integration for a record type's form:

1. In Settings, navigate to the Forms page under the Forms tab. 
2. In the Forms grid, select the form for which you want to set up a lookup integration.
   1. If you want to create a new custom form type, see the Add and Edit a Custom Form Type article for details.
3. Click the Edit button on the Form Builder to put the form into edit mode.
4. Click the Edit icon beside the form's name.
5. In the Form Properties sidebar, turn on the "Lookup" toggle. 
6. You will now see the fields to configure the integration's settings in the Form Properties sidebar. See the Configure a Lookup Integration section of this article for details on filling in the integration settings. 
   1. Below the "Lookup" toggle, you will also see the "Lookup Label" field, in which you can enter the text to display beside the search bar for the lookup integration. For example, suppose you are configuring a Workday HR lookup integration for your party form. You could label the lookup "Workday HR employee search", so your users know that the data will be pulled from Workday HR.
7. You can now map your source data to the fields on the form. See the Simple Mapping Method or Expression Mapping Method sections of this article depending on the mapping method you chose.
   1. If you selected "Automatically detect mappings" when configuring your lookup integration, you can skip this step.
8. When you have finished configuring your lookup integration and mappings, click the Publish button on the Form Builder to make the lookup integration available for your users. 

Configure a Lookup Integration

After adding a lookup section or activating a form integration, fill in the following settings to configure your lookup integration. You will see the same configuration options regardless if you are setting up a section or form lookup integration.

• Mapping method: choose how to map your source data to the Case IQ fields in the section or form. You can choose one of the following options:
  • Simple: manually map the source data for each target field in the section or form. You can set the field mapping after saving the integration settings, see steps in the Simple Mapping Method section.
  • Expression: map the source data to Case IQ target fields by an ISEL expression, so you can define complex data mapping. Selecting this option displays an "ISEL Expression" field. See the Expression Mapping Method section for guidance on writing expressions.
• Automatically detect mappings: if you select "Simple" as the "Mapping method", you can choose to turn on "Automatically detect mappings". By turning this option on, Case IQ will automatically map fields by comparing the names of your source system fields passed in the request and Case IQ field names in the section or form. The system will map source data to Case IQ fields with matching names, ignoring case and removing symbols.
• Lookup method: select "HTTP Request".
• Endpoint: enter the endpoint URL provided by your source system, which tells Case IQ where to send the data lookup request. Use the following format for the endpoint URL and end it with the dynamic value by which to search for data: https://end.point/route?q={dynamicValue}.
  • You can use "{searchValue}" as a placeholder for the dynamic value entered in the lookup search box on the form. For example, if you type "Daniel" in a lookup search box, the {searchValue} is "Daniel" and Case IQ will send a request to your source system to pull data containing "Daniel".
  • You can also use one of the record type's fields as the dynamic value by using the following format: "{<recordTypeName>.<fieldName>}". For example, suppose you are adding a data lookup section to the case form. By entering "{case.caseType}" in the endpoint, Case IQ will send a request to your source system to pull data containing the case type selected for the current case.
• HTTP Method: choose if Case IQ should send a GET, POST, or PUT request to fetch data from the source system. Select the HTTP method based on your source system's requirements. 
  • Your source system's API may only be designed to accept certain request methods. While GET is the most common method of retrieving data, some systems may require POST or PUT, especially when the request needs to include a body with specific parameters.
• HTTP Body: if you select "POST" or "PUT" as the "HTTP Method", the "HTTP Body" field is displayed, so you can enter an expression that returns a serialized object into the HTTP request body. See the following example HTTP bodies for POST and PUT.
  • POST example:

{
  "caseId": "12345",
  "caseType": "Fraud Investigation"
}

• PUT example:

{
  "searchCriteria": {
    "caseId": "12345",
    "status": "Open"
  }
}

• Authentication Method: select how your source system authenticates requests from the following options: “None”, “Basic Authentication”, or “OAuth Authentication”.

• Collection Property: if necessary, you can use the "Collection Property" to specify the path to the array in your source system's API response, which tells the Case IQ where to find the data in your source system. To determine the collection property:
  1. Look at your source system's API response and find the array containing the data you need.
  2. Identify the key that holds the array.
  3. Enter that key in the Collection Property field.

For example, suppose your source system's API returns the following JSON object. You would enter "users" in the "Collection Property" field, so that the integration pulls the user data.

{
  "users": [
    {
      "id": 1,
      "firstName": "John"
    }
  ]
}

Simple Mapping Method

If you choose "Simple" as the "Mapping method" when configuring your lookup integration, see the following steps to map source data to Case IQ fields:

1. For a data lookup section, click the Add Field Mapping () button in the section header. For a form lookup integration, click the Add Mapping button in the Form Properties sidebar.
2. In the Add Field Mapping pop-up, you can tell Case IQ the data from your source system to populate in the fields. In each "Source" field, enter the name of a field that your source system will send to Case IQ as part of the integration.
3. In the "Target" dropdown, select the matching field in the data lookup section or form into which Case IQ should populate the source data. 
4. When you have mapped all target fields, click the Save button on the pop-up. 
5. If you have completed configuring your integration, click the Publish button on the Form Builder to make the lookup integration available for your users.

Expression Mapping Method

If you choose "Expression" as the lookup integration's "Mapping Method", you can write an ISEL expression to tell Case IQ what source system data to populate in Case IQ fields. The basic format for mapping expressions is: 

{caseIqFieldName1: result.sourceSystemName1, caseIqFieldName2: result.sourceSystemName2, ...}

In place of result.sourceSystemName, you can use ISEL functions to create dynamic mapping expressions, see Case IQ Expression Language for all ISEL functions. In addition to these functions, you can also use result, this, and lookupFields in mapping expressions:

• result or this: the context object, meaning the record in your source system from which you are pulling data. For example, if you are creating a data lookup section to pull information from your HRIS about employees into Case IQ, result and this would refer to the employee records in your HRIS. 
• lookupFields: a context variable that contains an array of the Case IQ field names in the data lookup section or form. For example, suppose the data lookup section contains three fields: firstName, lastName, and active. In an expression, lookupFields would be an array of these fields, i.e. [firstName, lastName, active].

Below is an example mapping expression to map employee information from the source system to Case IQ party fields: 

{firstName: result.employeeFirstName,lastName: result.employeeLastName, primaryEntity: result.type == "Subject" ? true : false}

This expression maps the firstName, lastName, and primaryEntity fields in Case IQ with the employeeFirstName, employeeLastName, and type fields in the source system respectively. The system will populate the values in employeeFirstName and employeeLastName into firstName and lastName. For the primaryEntity field, the system will check the result's type field first before populating data. If the type is "Subject", the system will set the party's "Primary" field to "Yes". If it is not "Subject", Case IQ will leave the "Primary" field as "No".

Supported Fields Types for Lookup

The following field types are supported for Case IQ's lookup integration. This means that you can map source data to these field types, so that users can populate them with data from your source system.

• Checkbox
• Date Time
• Email
• Integer
• Money
• Number
• Picklist
• Picklist Multiple
• Radio
• Text Area
• Text Editor
• Textbox