Get Client Service
The Get Client service is a DISQ service used to retrieve a single client's fixed and dynamic client fields and fixed and dynamic address fields. DISQ services in general allow an external application to access data in the OIPA system by using requests, which utilize a formal XML schema that is both easy to understand and flexible in its application.
In OIPA, a client is an entity that represents an individual or an organization. Client is one of several entities supported in the DISQ model. The Client entity is a child entity with respect to the Company entity, and is a parent entity with respect to the Address entity.
Using the Get Client DISQ request, the user can retrieve a single client's data stored in the following database tables:
- AsClient
- AsClientField
- AsAddress
- AsAddressField
- AsAddressRole
Field names used in DISQ requests are case sensitive, and any field included in the request must be configured in OIPA at the context where the request is being sent.
Get Client Elements/Attributes Table
Element/Tag | Definition | Attribute | Element/Attribute Value and Description |
---|---|---|---|
<DisqRequest> |
Required element: The parent element of a DISQ request. |
||
<Header> |
Optional element: Container element for the <Message ID> and <TimeStamp> elements. |
|
|
<MessageId> |
Optional element: Designates a message ID for the DISQ request. |
A string value. | |
<TimeStamp> |
Optional element: Designates a timestamp for the DISQ request. |
A string representing a timestamp. | |
<Context> | Optional element:
The Context is the DISQ means of identifying the resource of an entity. Since Context is tied to the Action being requested, it is essential that the Context uniquely identifies a single resource. For the Get Client service, <Context> is optional. But, if <Context> is not specified, <ClientGuid> must be present in the <Get> Action element. Company is the only context allowed for the Get Client service. Note: If both the <Context> and <ClientGuid> elements are omitted from the request, an exception will be returned. |
||
<Company> |
Required element: Establishes the resource from which the client is found. |
||
<CompanyName> |
Required element: Holds the name of the company to which the client belongs. |
The name of a company to which a client belongs. | |
<Get> |
Required element: The parent element of the Get action. Get is a data retrieval action that can retrieve resources for a single, unique entity in the system. From the client context, the Get action retrieves the resources of a single, unique client. |
||
<Client> |
Required element: Holds child elements that specify the entity whose data is to be retrieved. Note: Dynamic fields are not supported for the Get action. Only fixed fields can be used to identify the entity. Note: Only one <Client> element is processed. If multiple <Client> elements are provided, only the first will be processed. |
||
<ClientGuid> | Optional element:
Holds the GUID for the client whose information is being requested. If a client GUID is provided, the individual client is directly identified, and no other identifying criteria will be recognized. Note: If the <Context> element is omitted, then the <ClientGuid> element must be present within the <Get> element in order to identify the specific client. |
A client GUID. | |
<[Client fixed field]> |
Optional, repeatable element: The name of each of these elements should be the name of a client fixed field, such as LastName, FirstName or TaxID. These elements and their values are used to uniquely identify the client. When multiple client fixed field elements are used within the <Get> action, the request will only retrieve clients that satisfy all of the specified client criteria. If multiple elements reference the same fixed field, only the last element is recognized. |
The value to search for. See the Client Fixed Fields section below for a complete list of client fixed fields that can be used in a DISQ request.
For example: <LastName>Smith</LastName> <FirstName>John</FirstName> |
|
<Addresses> |
Optional element: A container element for the <Address> sub-element. This element should be used when a client's address information can aid in identifying the specific client. If there are multiple <Addresses> elements, only the last element is recognized. |
||
<Address> |
Optional element: This element is used to list the address criteria to be used in identifying the client. If more than one <Address> element is present, only the first will be recognized. |
||
<[Address fixed field]> |
Required, repeatable element: The name of each of these elements should be the name of an address fixed field, such as <City> or <CountryCode>. If one or more clients have addresses that satisfy the criteria specified within these elements, the clients will be returned from the service. When multiple address fixed field elements are used within the <Get> action, the request will only retrieve clients that satisfy all of the specified address criteria. |
The value to search for. See the Address Fixed Fields section below for a complete list of address fixed fields that can be used in a DISQ request.
For example: <City>Philadelphia</City> <CountryCode>US</CountryCode> |
|
<ResponseFormat> | Optional element:
The <ResponseFormat> section allows the requestor to specify what should be included in the response from the DISQ request. The responses returned from a Get Client service can contain fixed and dynamic field data for both client and address fields. Note: If <ResponseFormat> is omitted, then only client fixed fields are returned, as that is the default response type. |
||
<ResponseType> |
Optional element: This element specifies whether only client fixed fields should be returned from the request, or if other field data should be returned as well.
|
Default: Only client fixed fields will be returned from the request. Custom: The user can specify client dynamic fields, address fixed fields and address dynamic fields to be returned along with client fixed fields. |
|
<Client> | Optional element:
This element allows client dynamic fields to be returned when valid child elements are present. This element also provides the specification to filter Address resources and indicate the Address data to return. If there are multiple <Client> elements, only the last element is recognized. |
||
<Fields> |
Optional element: This is the container element for the client dynamic field data that should be returned from the request. If this element is empty, data for all client dynamic fields will be returned. If there are multiple <Fields> elements, only the last element is recognized. |
||
<[Client dynamic field]> |
Optional, repeatable element: The name of each of these elements should be the name of a client dynamic field. Data will be returned for each dynamic client field specified. If the same dynamic field is referenced in multiple elements, the output will contain one instance of the field’s data. |
|
|
<Addresses> | Optional element:
The presence of this element indicates that address data should be returned. Its child elements specify which addresses should be returned and which fixed and dynamic field data to include. If this element is repeated, only the last element is recognized. |
||
<Address> |
Optional, repeatable element: This is the container element for the address filters, as well as fixed and dynamic field data, to be returned from the request. If this element is empty, all fixed field data for all addresses will be returned. Note: When more than one <Address> element is provided, the request will return all of the client's addresses that satisfy any one of the conditions specified across all the <Address> elements. |
||
<[Address fixed field]> |
Optional, repeatable element: The name of each of these elements should be the name of an address fixed field, such as <City> or <CountryCode>. These elements provide the criteria that filter the address data to return in the response. If multiple address fixed fields are provided, client addresses that satisfy all criteria will be returned. |
The value to search for. See the Address Fixed Fields section below for a complete list of address fixed fields that can be used in a DISQ request.
For example: <City>Philadelphia</City> |
|
<Fields> |
Optional element: This is the container element for the address dynamic field data that should be returned from the request. If this element is empty, data for all address dynamic fields will be returned. If this element is repeated, only the last element is recognized. |
||
<[Address dynamic field]> |
Optional, repeatable element: The name of each of these elements should be the name of an address dynamic field. Data will be returned for each dynamic address field specified. If an address dynamic field is repeated, the output will contain one instance of the field’s value. |
|
Client Fixed Fields
Below are all of the client fixed fields that can be used to identify a client.
- AdditionalPrefix
- AdditionalSuffix
- AlternateName1
- AlternateName2
- AlternateName3
- AlternateName4
- AlternateName5
- BirthCountryCode
- BirthRegionCode
- CheckBox1
- CheckBox2
- CitizenshipCountryCode
- ClientGuid
- Combo1
Address Fixed Fields
Below are all of the address fixed fields that can be used to identify a client.
|
|
|
XML Schema
<DisqRequest>
<Header>
<MessageId>[message id]</MessageId>
<TimeStamp>[time stamp]</TimeStamp>
</Header>
<Context>
<Company>
<CompanyName>[company name]</CompanyName>
</Company>
</Context>
<Get>
<Client>
<ClientGuid>[ClientGUID]</ClientGuid>
<[client fixed field 1]>[client fixed field 1 value]</[client fixed field 1]>
<[client fixed field 2]>[client fixed field 2 value]</[client fixed field 2]>
. . .
<[client fixed field n]>[client fixed field n value]</[client fixed field n]>
<Addresses>
<Address>
<{address fixed field 1]>[address fixed field 1 value]</[address fixed field 1]>
<[address fixed field 2]>[address fixed field 2 value]</[address fixed field 2]>
. . .
<[address fixed field n]>[address fixed field n value]</[address fixed field n]>
</Address>
<Address>. . .</Address>
</Addresses>
</Client>
</Get>
<ResponseFormat>
<ResponseType>[Default|Custom]</ResponseType>
<Client>
<Fields>
<[client dynamic field 1]></[client dynamic field 1]>
<[client dynamic field 2]></[client dynamic field 2]>
. . .
<[client dynamic field n]></[client dynamic field n]>
</Fields>
<Addresses>
<Address>
<[address fixed field 1]></[address fixed field 1]>
<[address fixed field 2]></[address fixed field 2]>
. . .
<[address fixed field n]></[address fixed field n]>
<Fields>
<[address dynamic field 1]></[address dynamic field 1]>
<[address dynamic field 2]></[address dynamic field 2]>
. . .
<[address dynamic field n]></[address dynamic field n]>
</Fields>
</Address>
<Address>
. . .
</Address>
</Addresses>
</Client>
</ResponseFormat>
</DisqRequest>