3.1.4.2.2.2 GetEntityInstancesResponse

  • Article

The GetEntityInstancesResponse element specifies the result data for the GetEntityInstances WSDL operation.

 <xs:element name="GetEntityInstancesResponse" xmlns:xs="http://www.w3.org/2001/XMLSchema">
   <xs:complexType>
     <xs:sequence>
       <xs:element minOccurs="1" maxOccurs="1" name="GetEntityInstancesResult" type="xs:unsignedInt"/>
       <xs:element minOccurs="0" maxOccurs="1" name="columnNames" type="tns1:ArrayOfString"/>
       <xs:element minOccurs="0" maxOccurs="1" name="localizedColumnNames" type="tns1:ArrayOfString"/>
       <xs:element minOccurs="0" maxOccurs="1" name="showInPicker" type="tns1:ArrayOfBoolean"/>
       <xs:element minOccurs="0" maxOccurs="1" name="values" type="tns1:ArrayOfString"/>
       <xs:element minOccurs="1" maxOccurs="1" name="hasEntityMetadata" type="xs:boolean"/>
       <xs:element minOccurs="0" maxOccurs="1" name="message" type="xs:string"/>
       <xs:element minOccurs="1" maxOccurs="1" name="success" type="xs:boolean"/>
     </xs:sequence>
   </xs:complexType>
 </xs:element>

GetEntityInstancesResult: The number of EntityInstances returned.

columnNames: an ordered list of strings indicating the names of the Fields returned for the identified Entity. The first string MUST be set to "___identities". The second string MUST be set to "___entityInstanceReference". The third string MUST be set to "___displayName". The remaining strings MUST be the names of the Fields of the identified Entity.

localizedColumnNames: an ordered list of strings indicating the locale-specific names of the Fields returned for the identified Entity. The first, second and third strings MUST be ignored by the protocol client. The remaining strings MUST be the locale-specific names of the Fields of the identified Entity. The protocol server MUST use an implementation-specific algorithm to determine the locale to which the localizedColumnNames will conform.

showInPicker: an ordered list of Boolean flags. The list MUST contain the same number of elements as the columnNames list. The first, second and third flags in this list MUST be ignored by the protocol client. Each of the remaining flags MUST indicate whether the Entity Field, identified by the name in the corresponding position in the columnNames list, is to be shown in the UI presented to the user by the protocol client. The value MUST be set to true if the corresponding field (2) is to be shown in the UI presented to the user by the protocol client; otherwise, the value is false.

values: an ordered list of string values. The list MUST contain a number of elements equal to the length of the columnNames multiplied by the value of GetEntityInstancesResult. The values list MUST be a concatenation of GetEntityInstanceResult sublists, where each of these sub lists MUST correspond to one of the identified EntityInstances and MUST contain a number of elements equal to the length of the columnNames list. Each of the elements of the values list MUST be encoded according to [XML10].

Each sub list MUST have the following structure:

The value of the first element of the sub list MUST be the encoded data values of the EntityInstance Identifiers corresponding to the EntityInstance. The format of the encoded data values of the EntityInstance Identifiers MUST be the encoded data values of the EntityInstance Identifiers. The data values of the EntityInstance Identifiers MUST be encoded according to the following scheme:

  • The first character MUST be an underscore (_).

  • The second character MUST be an underscore (_).

  • The next character MUST be in the range "b" through "z". This character MUST correspond to the number of data values of EntityInstance Identifiers that are encoded in this input. If the number of encoded data values of EntityInstance Identifiers is one, this character MUST be "b". If the number of encoded data values of EntityInstance Identifiers is two, this character MUST be "c". Larger numbers of encoded data values of EntityInstance Identifiers MUST be similarly encoded in an upwards increasing manner, with "z" corresponding to 25 encoded data values of EntityInstance Identifiers. The number of encoded data values of EntityInstance Identifiers MUST be less than or equal to 25.

  • The remaining characters MUST be encoded as follows:

    • The list of characters MUST be the concatenation of the encodings of each individual data value of the EntityInstance Identifier. Each individual data value of an EntityInstance Identifier MUST be encoded as a series of characters, in the manner described in the following.

    • If the data value of the EntityInstance Identifier is NULL, the first character MUST be ‘p’. Otherwise, the first character MUST indicate the CLR type of the data value of the EntityInstance Identifier. The CLR type of the data value of the EntityInstance Identifier MUST be equal to one of the values in the first column of the following table. The first character MUST be the character in the same row as the CLR type of the data value of the EntityInstance Identifier.

      CLR type of the data value of the EntityInstance Identifier

      Corresponding encoding character

      System.Boolean

      a

      System.Byte

      b

      System.DateTime

      c

      System.Decimal

      d

      System.Double

      e

      System.Int16

      f

      System.Int32

      g

      System.Int64

      h

      System.SByte

      i

      System.Single

      j

      System.String

      k

      System.UInt16

      l

      System.UInt32

      m

      System.UInt64

      n

      System.Guid

      o

      System.Char

      p

      System.TimeSpan

      q

    • The remaining characters of this encoded data value of the EntityInstance Identifier MUST represent a hexadecimal-encoded representation of the serialized representation of each data value of the EntityInstance Identifier, as follows:

      • The serialized representation of the data value of the EntityInstance Identifier MUST be represented as follows:

        • If the data value of the EntityInstance Identifier is NULL, the serialized representation MUST be "null"

        • If the CLR type of the data value of the EntityInstance Identifier is System.DateTime, the serialized representation MUST be the string representation of the Ticks represented by the data value of the EntityInstance Identifier. The Ticks represented by a value of CLR type System.DateTime MUST be the number of 100-nanosecond intervals that have elapsed since 12:00:00 midnight, January 1, 0001.

        • If the data value of the EntityInstance Identifier is not NULL and not of CLR type System.DateTime, the serialized representation MUST be the CLR-provided serialization of the data value of the EntityInstance Identifier.

      • The serialized representation of the data value of the EntityInstance Identifier obtained MUST be hexadecimal-encoded as follows:

        • If the CLR type of the data value of the EntityInstance Identifier is "System.Guid", the serialized representation MUST be encoded as follows:

          • The first four characters MUST be the hexadecimal encoding of the integer that represents the string length of the serialized representation of the data value of the EntityInstance Identifier. The integer MUST be hexadecimal-encoded according to the same rules as if it were a character (see the following).

          • The remaining characters MUST be the string representation of the data value of the EntityInstance Identifier.

        • If the CLR type of the data value of the EntityInstance Identifier is not "System.Guid", the serialization representation MUST be hexadecimal-encoded as follows:

          • The first four characters MUST be the hexadecimal encoding of the integer that represents the string length of the serialized representation of the data value of the EntityInstance Identifier, multiplied by 4.

          • The remaining characters MUST be the hexadecimal encoding of the serialization. Each group of four characters MUST represent the hexadecimal encoding of a single character in the serialized representation. Each single character MUST be hexadecimal-encoded as detailed in what follows.

      • The hexadecimal encoding of a single character MUST be represented as follows:

        • The character MUST be represented by four characters in the hexadecimal encoded representation of the ASCII value of the character. These characters MUST be obtained as indicated here.

        • The first character MUST correspond to the lowest-order four bits in the two-byte representation of the unencoded character. The correspondence MUST be obtained according to the following table.

        • The second character MUST correspond to the second-lowest-order four bits in the two-byte representation of the unencoded character. The correspondence MUST be obtained according to the following table.

        • The third character MUST correspond to the third-lowest-order four bits in the two-byte representation of the unencoded character. The correspondence MUST be obtained according to the following table.

        • The fourth character MUST correspond to the fourth lowest-order (that is, the highest-order) four bits in the two-byte representation of the unencoded character. The correspondence MUST be obtained according to the following table.

      Value to be encoded

      Corresponding encoding character

      0

      0

      1

      1

      2

      2

      3

      3

      4

      4

      5

      5

      6

      6

      7

      7

      8

      8

      9

      9

      10

      a

      11

      b

      12

      c

      13

      d

      14

      e

      15

      f

      • As an example, if the input to be specified consists of two data values corresponding to two EntityInstance Identifiers, first of CLR type System.Int32 and value 4, second of CLR type System.String, with a value of "ab", the corresponding encoded EntityInstance Identifiers would have the following value: __cg40004300k800016002600

    The value of the second element of the sub list MUST be the serialized reference to the EntityInstance. The format of the reference to the EntityInstance MUST be the same as that of the bstrEntityInstanceId input to the DecodeEntityInstanceId operation.

    The value of the third element of the sub list MUST be the display name value identified for the EntityInstance.

    The values of the remaining elements of the sub list MUST be the serialized values of the Fields of the EntityInstance.

hasEntityMetadata: If the specified Entity can be found in the metadata store, the protocol server MUST set this value to true. Otherwise, the protocol server MUST set this value to false. The value MUST be present.

message: Contains errors or warnings resulting from the process  of resolving or searching for the EntityInstances according to the provided input, if any. The message MUST be encoded as specified in [XML10].

success: true if the operation finished without any unexpected errors; false otherwise. This value MUST be present.