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.
  • AccuracyLevel is only reported with the PhotoVerify operation and contains the actual level of accuracy (1 - 5) the specified photo would comply with; 0 if the photo is to be rejected.
  • 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 (Face, Periocular or Voice) 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 that contains tags typically associated with Face or Periocular samples in case that exactly one face has been found:
        • 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.
      • FoundFaces  is an optional element only available with Face or Periocular samples in case that multiple faces have been found (i.e. no Tags element is provided):
        • 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).
  • 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)))
{
    var serializer = new XmlSerializer(typeof(JobResult), "http://schemas.bioid.com/2012/02/BWSMessages");
    var 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; }
    public JobStatistics Statistics { 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; }
    public SampleTags Tags { get; set; }
    public List<EyeCoordinates> FoundFaces { 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 class EyeCoordinates
{
    public Cartesian RightEye { get; set; }
    public Cartesian LeftEye { get; set; }
}
public struct Cartesian
{
    [XmlAttribute]
    public double X { get; set; }
    [XmlAttribute]
    public double Y { get; set; }
}
[XmlType(TypeName = "Statistics")]
public class JobStatistics
{
    public DateTime ProcessingTime { get; set; }
    public DateTime TotalServiceTime { get; set; }
}