In the Web Method Details section, there is a complete discussion of the parameters that are passed to, and returned from, the Web Service methods in the API. This section provides additional conversation about the most important elements, what those elements mean, and their relevance to the verification process.
| Table of Contents |
|---|
Interpreting the sourceList
A call to any method in the greenID API will return, as part of the currentStatusV3CurrentStatusV3 object, a sourceList element. The sourceList contains a list of data sources that can contribute to the person's verification attempt. This list of sources is not fixed, it is computed based on the current state of the person's verification attempt, so it can be useful because it can indicate which data sources are not worth attempting, and also which data sources, if passed, will result in the person being verified immediately (we refer to this as "one source left").
Consider the snippet of XML below:
| Code Block | ||
|---|---|---|
| ||
<sourceList>
<source>
<available>true</available>
<name>nswregodvs</name>
<notRequired>false</notRequired>
<oneSourceLeft>false</oneSourceLeft>
<order>1</order>
<passed>false</passed>
<state>EMPTY</state>
<version>1</version>
</source>
...
<sourceList> |
sourceList element. One of the most important elements here is the name element, which contains the name of the data source, which is "nswregodvs" in this case. This name is used to refer to this data source when calling setFields. The other important elements are described below:available- if the data source is able to be used, then this element will contain "true", otherwise it will contain "false". If a data source is not available (usually because greenID cannot currently access the data source), thensetFieldsshould not be called for that data source, since the call will fail.passed- if the data source has been previously attempted, and passed, then this element will contain "true", otherwise it will contain "false". If the data source is passed, then callingsetFieldsfor that data source will fail, and have no effect.oneSourceLeft- this element indicates if this data source is sufficient to get the person completely verified. If this element contains "true", then callingsetFieldsfor this data source, and having a successful outcome, will be enough to get the person completely verified. The value is computed based on the current state of the person's verification attempt, so it can change after calls tosetFields.state- while the passed element provides a simple yes/no indication of whether the person has successfully completed this data source, the state element provides a more detailed indication. Please refer to the detailed description of theCheckResulttype below for the list of values that may appear in this field.notRequired- this element indicates whether this data source can contribute to the person's verification attempt. If this field contains "true", then there is no value in attempting this data source, since it cannot make any difference the person's verification attempt. A call tosetFieldsfor this data source would be wasted.
Interpreting the sourceFields
A call to getFields for a given data source (using the name provided in the sourceList, detailed above), will return a list of data fields required for that data source. If the fields are filled, by collecting data from the person being verified, and passed to setFields, then the data source will be checked. However, there is a lot of detail in the return object from getFields, and it is important to know what to do with that information.
The main aim of the getFields method is to provide the customer with enough detail to render HTML input fields to collect input from the person being verified. GreenID also generates an HTML fragment that can be used directly, if desired. This is discussed in more detail later.
The getFields method returns a currentStatusV3 object, like all the other methods, but with the sourceFields member populated. Below is a snippet of XML from a SOAP envelope:
| Code Block | ||
|---|---|---|
| ||
<sourceFields>
<fieldList>
<sourceField>
<attribute>
<name>id</name>
<value>greenid_nswregodvs_number</value>
</attribute>
<attribute>
<name>class</name>
<value>form-control required</value>
</attribute>
<attribute>
<name>aria-required</name>
<value>true</value>
</attribute>
<label>Licence number</label>
<name>greenid_nswregodvs_number</name>
<type>text</type>
<value/>
</sourceField>
<sourceField>
<attribute>
<name>id</name>
<value>greenid_nswregodvs_givenname</value>
</attribute>
<attribute>
<name>class</name>
<value>form-control namevalidation required</value>
</attribute>
<attribute>
<name>aria-required</name>
<value>true</value>
</attribute>
<label>First name</label>
<name>greenid_nswregodvs_givenname</name>
<type>text</type>
<value>Test</value>
</sourceField>
<sourceField>
<attribute>
<name>id</name>
<value>greenid_nswregodvs_middlename</value>
</attribute>
<attribute>
<name>class</name>
<value>form-control</value>
</attribute>
<attribute>
<name>aria-required</name>
<value>false</value>
</attribute>
<label>Middle name(s)</label>
<name>greenid_nswregodvs_middlename</name>
<type>text</type>
<value>Q</value>
</sourceField>
<sourceField>
<attribute>
<name>id</name>
<value>greenid_nswregodvs_surname</value>
</attribute>
<attribute>
<name>class</name>
<value>form-control namevalidation required</value>
</attribute>
<attribute>
<name>aria-required</name>
<value>true</value>
</attribute>
<label>Surname</label>
<name>greenid_nswregodvs_surname</name>
<type>text</type>
<value>Citizen</value>
</sourceField>
<sourceField>
<attribute>
<name>id</name>
<value>greenid_nswregodvs_dob</value>
</attribute>
<attribute>
<name>class</name>
<value>form-control dobvalidation required</value>
</attribute>
<attribute>
<name>aria-required</name>
<value>true</value>
</attribute>
<label>Date of birth (dd/mm/yyyy)</label>
<name>greenid_nswregodvs_dob</name>
<type>text</type>
<value>01/01/1980</value>
</sourceField>
<sourceField>
<attribute>
<name>id</name>
<value>greenid_nswregodvs_tandc</value>
</attribute>
<attribute>
<name>class</name>
<value>required</value>
</attribute>
<attribute>
<name>aria-required</name>
<value>true</value>
</attribute>
<label>I consent to the information above being checked with the Issuer or Official Record Holder</label>
<name>greenid_nswregodvs_tandc</name>
<type>checkbox</type>
</sourceField>
...
</fieldList>
...
</sourceFields> |
...