SOAP Message Schema Messages

The schema-namespace for the XML-messages returned by the BWS operations EnrollVerifyIdentify, LivenessDetection and QualityCheck currently is 
http://schemas.bioid.com/2012/02/BWSMessages (XSD file).

Such an XML-message contains information about the performed operation itself, such as a unique ID, a flag indicating whether the operation succeeded and a list of operation specific errors. It also contains information about each sample that has been received by the operation, including sample specific errors that might have occurred. The XML-structure of the message, starting with the root element  OperationResults  is as follows:

  • JobID  contains a so called GUID that uniquely identifies the operation to which this message belongs. Using this ID, the operation can later be identified, for example in the monthly settlement.
  • Command  names the executed operation.
  • Succeeded  simply repeats the return-value of the operation.
  • Face  is a boolean value that is only set by the enrollment operation indicating whether a template for the trait face is available or not.
  • Periocular  is a boolean value that is only set by the enrollment operation indicating whether a template for the trait periocular is available or not.
  • Voice  is a boolean value that is only set by the enrollment operation indicating whether a template for the trait voice is available or not.
  • Samples  lists all samples received by the operation:
    • Sample  describes a single sample in the samples collection by providing a
      • Trait  attribute, specifying the trait the sample belongs to, and a
      • Suitalble  attribute, a flag indicating whether this sample was suitable for the operation. If set to false, a list of errors follows:
      • Errors  lists sample specific errors if Suitable is set to false or warnings in case Suitable is set to true:
        • Error  describes a single error by providing a
          • Code, a string identifying the error, the error-
          • Message  itself, and some optional
          • Details, which might describe the error message a bit more.
      • Tags  is an optional element and may contain tags associated with the sample like:
        • RightEye  providing in its attributes X and Y the cartesian coordinates of the right iris center (or eye center if iris was not found).
        • LeftEye  providing in its attributes X and Y the cartesian coordinates of the left iris center (or eye center if iris was not found).
        • HeadMovementDirection  reports the degree of head rotation between the previous image sample and this image sample. It is calculated by the photo fake defender (as used with the LivenessDetection API or with  the VerifyIdentify and Enroll API calls when the LiveFaceDetection or LivePeriocularDetection flag is set). Valid values are between 0 and 359 degrees.
  • Errors  lists non sample specific errors as reported by the operation:
    • Error  describes a single error by providing a
      • Code, a string identifying the error, the error-
      • Message  itself, and some optional
      • Details, which might describe the error message a bit more.
  • Statistics  contains some statistical informations about the performed operation:
    • ProcessingTime  shows the amount of time that was needed to perform the operation.
    • TotalServiceTime  shows the total amount of time the server needed to service the operation.

The parsing of such an XML-message string is very simple. Here is an example of how to do it in C#:

// lets parse the message string 'messages' as it might have been returned
// by a call to Enroll, Verify, Identify or QualityCheck:
using (XmlReader reader = XmlReader.Create(new StringReader(messages)))
{
    XmlSerializer serializer = new XmlSerializer(typeof(JobResult), "http://schemas.bioid.com/2012/02/BWSMessages");
    JobResult result = (JobResult)serializer.Deserialize(reader);
}
// these are the classes we use for the deserialization:
[XmlRoot(ElementName = "OperationResults", Namespace = "http://schemas.bioid.com/2012/02/BWSMessages")]
public class JobResult
{
    public Guid JobID { get; set; }
    public string Command { get; set; }
    public bool Succeeded { get; set; }
    public bool? Face { get; set; }
    public bool? Periocular { get; set; }
    public bool? Voice { get; set; }
    public List<JobSample> Samples { get; set; }
    public List<JobMessage> Errors { get; set; }
}
[XmlType(TypeName = "Sample")]
public class JobSample
{
    [XmlAttribute]
    public Trait Trait { get; set; }
    [XmlAttribute]
    public bool Suitable { get; set; }
    public List<JobMessage> Errors { get; set; }
    // in case you are interested in these tags
    public SampleTags Tags { get; set; }
}
[XmlType(TypeName = "Error")]
public class JobMessage
{
    public string Code { get; set; }
    public string Message { get; set; }
    public string Details { get; set; }
}
[XmlType(TypeName = "Tags")]
public class SampleTags
{
    public Cartesian RightEye { get; set; }
    public Cartesian LeftEye { get; set; }
    public int? HeadMovementDirection { get; set; }
}
public struct Cartesian
{
    [XmlAttribute]
    public double X { get; set; }
    [XmlAttribute]
    public double Y { get; set; }
}