Domain Entities in a Webservice Context

The domain entity configuration script controls how a domain entity interacts with webservices. It can define the source endpoints used to retrieve data and optional functions to customize data retrieval or REST operations. For the full function reference, see the Domain Entity configuration script reference.

Overview: Recommended configuration order

Configure the domain entity in the following order.

Define the attributes that map the webservice response to the domain entity, including the key attribute used to identify each entity.
Configure the source find and list endpoints that XDM needs. The default request is HTTP GET, so no custom function is needed when the endpoints accept GET requests and return data in a format XDM can process.
Add fetch(url) only if the source requires a different request, such as HTTP POST with a payload. The function receives the URL resolved from the endpoint configuration and returns the response content.
Add preProcessResponse(response) only if the response must be transformed into valid JSON before XDM can process it.
If the entity is used as a target in an Entity Copy task, configure the target create and search endpoints and implement create(data, url) and search(data, url). These are required for the Webservice Target capability.
Define update(data, url) or delete(data, url) only if the target webservice requires behavior different from the default HTTP PUT or DELETE request.
Add displayName(attributes) only if the default entity name is not suitable.

Configuration functions are optional customizations in general. Declare only the functions needed for the webservices and behavior in your integration. Some XDM capabilities require specific functions, as described below.

Capability checks

XDM evaluates domain entity capabilities when the configuration script is saved or updated. It records whether the entity meets the requirements for supported scenarios and reports reasons when a requirement is missing. Task pre-checks use the relevant capability for the selected scenario.

Webservice Source is checked when the entity is used as a source in an Entity Copy task or for Webservice Indexing. Each attribute must define a path, and both the find and list endpoints must be configured.
Webservice Target is checked when the entity is used as a target in an Entity Copy task. Each attribute must define a path, the create and search endpoints must be configured, and the create() and search() functions must be declared.
Generation is checked when the entity is used by an Entity Scenario Generator. Each entity referenced through a mapsTo mapping must have a key attribute.

These capability requirements are specific to the corresponding XDM scenarios. Other configuration functions, such as fetch(), preProcessResponse(), update(), delete(), and displayName(), remain optional unless your integration needs their behavior.

Source endpoints

The endpoints configuration can define source and target endpoints:

find describes the endpoint path used to retrieve one entity.
list describes the endpoint path used to retrieve entities as a collection. It can also specify paging parameters (pageParameter, sizeParameter, and pageSize) and itemPath, the path to the entities in the list response.
create describes the target endpoint used to create an entity.
search describes the target endpoint used to find a matching entity.

Endpoint definitions can also declare responseCodes as a mapping of accepted HTTP status codes to descriptions.

These endpoint definitions use the default fetch behavior, which retrieves data with an HTTP GET request. To use a source that requires a different request, such as an HTTP POST with a payload, define the optional String fetch(String url) function. The url is the resource URL resolved from the endpoint configuration. The function must return the response content for further processing. Defining fetch replaces the default HTTP GET behavior; without it, the default remains unchanged.

Optional configuration functions

The following optional functions can be declared in the domain entity configuration script:

create(Map data, String url) creates an entity in a target REST webservice. If omitted, XDM sends an HTTP POST request. The custom function returns the response as a string, map, or list.
delete(Map data, String url) deletes an entity from a target webservice. If omitted, XDM sends an HTTP DELETE request to the entity URL.
displayName(Map<String, String> attributes) returns the display name for an entity.
fetch(String url) customizes source data retrieval, for example to issue a POST request with a payload. It returns the response content and replaces the default GET request.
preProcessResponse(response) pre-processes each REST response before XDM processes it and must return valid JSON.
search(Map data, String url) searches for a matching entity in the target webservice and returns that entity.
update(Map data, String url) updates an entity in a target REST webservice. If omitted, XDM sends an HTTP PUT request. The custom function returns the response as a string, map, or list.

The find endpoint is used to retrieve an entity from the source. The search() function instead locates a matching entity in the target webservice; these have different purposes.

Example: Configuring an employee webservice source and target

This example defines an Employee entity with source and target endpoints. The source find and list endpoints use the default HTTP GET behavior. The target create() and search() functions use the POST and GET helpers to call the configured target endpoints. The create() and search() functions are required for the Webservice Target capability.

attributes = [
    [ name           : "Employee ID",
      path           : "employeeId",
      type           : "STRING",
      key            : true
    ]
]

endpoints = [
    find: [
        path: "/employees?employeeId={employeeId}",
        responseCodes: [
            200: "OK"
        ]
    ],
    list: [
        path: "/employees",
        responseCodes: [
            200: "OK"
        ]
    ],
    create: [
        path: "/employees",
        responseCodes: [
            201: "Created"
        ]
    ],
    search: [
        path: "/employees/search",
        responseCodes: [
            200: "OK"
        ]
    ]
]

Map create(Map payload, String baseUrl) {
    return POST(baseUrl + endpoints.create.path, payload, endpoints.create.responseCodes)
}

Map search(Map payload, String baseUrl) {
    return GET(baseUrl + endpoints.search.path, payload)
}

String fetch(String url)
    return restTemplate.postForObject(url, ["id": 5], String.class);
}